Skip to main content

​
Base URL

The Gambiarra hub exposes an OpenAI-compatible HTTP API. The base URL depends on your hub configuration: 
http://{hostname}:{port}
Default configuration:
  • Hostname: 0.0.0.0 (listens on all interfaces)
  • Port: 3000
  • Example: http://localhost:3000

​
Authentication

The hub currently does no authentication at the HTTP level. It is designed for trusted local networks. Room-level protection:
  • Rooms can optionally be password-protected
  • Password is required when joining a protected room via POST /rooms/:code/join
  • Passwords are hashed using argon2id before storage

​
Common Headers

​
Request Headers

Content-Type: application/json
All POST requests should include Content-Type: application/json header.

​
Response Headers

All responses include: 
Access-Control-Allow-Origin: *

​
CORS Support

The hub supports CORS with the following configuration: Preflight requests (OPTIONS): 
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
All endpoints accept OPTIONS requests and return 204 No Content.

​
Error Response Format

All error responses follow this consistent format: 
{
  "error": "Error message describing what went wrong"
}

​
Common HTTP Status Codes

​
200
OK
Request succeeded
​
201
Created
Resource successfully created
​
204
No Content
CORS preflight response
​
400
Bad Request
Missing or invalid request parameters
​
401
Unauthorized
Invalid room password
​
404
Not Found
Room, participant, or endpoint not found
​
502
Bad Gateway
Failed to proxy request to participant endpoint
​
503
Service Unavailable
Participant is offline

​
Example Error Responses

​
Room Not Found

{
  "error": "Room not found"
}
Status: 404

​
Invalid Password

{
  "error": "Invalid password"
}
Status: 401

​
Missing Required Fields

{
  "error": "Missing required fields: id, nickname, model, endpoint"
}
Status: 400

​
Participant Offline

{
  "error": "Participant is offline"
}
Status: 503

​
Proxy Failed

{
  "error": "Failed to proxy request: <error details>"
}
Status: 502

​
Health Check

The hub exposes a health check endpoint: 
curl http://localhost:3000/health
Response: 
{
  "status": "ok",
  "timestamp": 1709409600000
}

​
Content Types

​
JSON Endpoints

Most endpoints return application/json:
  • Room management
  • Participant management
  • Model listing
  • Non-streaming chat completions

​
Streaming Endpoints

Streaming endpoints return text/event-stream:
  • POST /rooms/:code/v1/chat/completions (when stream: true)
  • GET /rooms/:code/events (Server-Sent Events)

Build docs developers (and LLMs) love

Get started for freeTalk to us