Skip to main content

API Reference

Drawbridge Gateway exposes an OpenAI-compatible API. Any client built for OpenAI works with zero modifications.

Base URL

https://api.drawbridge-tech.com/v1

All requests require an Authorization: Bearer <api-key> header. API keys are created via the Admin API and have a db- prefix.

Public Endpoints

POST/v1/chat/completions

Create a chat completion (streaming or non-streaming)

Request Body
{
  "model": "kiro",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": true,
  "temperature": 0.7,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string"}
          }
        }
      }
    }
  ]
}
Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1716000000,
  "model": "kiro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}
GET/v1/models

List available models

Response
{
  "object": "list",
  "data": [
    {
      "id": "kiro",
      "object": "model",
      "owned_by": "drawbridge"
    }
  ]
}
GET/health

Health check endpoint (drain-aware)

Response
{
  "status": "healthy",
  "accounts": 2,
  "total_slots": 6,
  "available_slots": 4
}
GET/metrics

Prometheus metrics (text format)

Response
# HELP drawbridge_requests_total Total requests processed
# TYPE drawbridge_requests_total counter
drawbridge_requests_total{model="kiro",status="success"} 142
drawbridge_requests_total{model="kiro",status="error"} 3

# HELP drawbridge_request_duration_seconds Request duration
# TYPE drawbridge_request_duration_seconds histogram
drawbridge_request_duration_seconds_bucket{le="5"} 89
drawbridge_request_duration_seconds_bucket{le="30"} 130
drawbridge_request_duration_seconds_bucket{le="60"} 140

Admin Endpoints

Protected by admin token. Set via admin.auth_token in config or DRAWBRIDGE_ADMIN_TOKEN env.

MethodEndpointDescription
POST/admin/keysCreate a new API key
GET/admin/keysList all API keys
DELETE/admin/keys/:idRevoke an API key
GET/admin/accountsList account status and pool metrics
GET/admin/usageUsage statistics and credit consumption
GET/admin/metricsJSON metrics snapshot

Streaming

Set "stream": true to receive Server-Sent Events. Each event follows the OpenAI streaming format:

SSE Stream
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Rate Limits

Per-key sliding window rate limiting. Default: 60 requests/minute. Configurable per key via Admin API.

Response headers on rate-limited requests (HTTP 429):

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716000060
Retry-After: 12