API Reference

The Endpoint

All chat completion requests go to:

POST https://api.maig.dev/v1/chat/completions

Authentication

Pass your MAIG API key in the Authorization header using the Bearer scheme:

Authorization: Bearer maig_your_key_here

Request Fields

The request body is JSON and follows the OpenAI chat completions format. Fields not supported by the selected provider are silently dropped — see the API Compatibility matrix for the full per-provider breakdown.

For the full per-provider field support matrix, see the API Compatibility page.

Example Request (non-streaming)

curl https://api.maig.dev/v1/chat/completions \
  -H "Authorization: Bearer maig_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Example Response

All gateway responses are returned in the standard OpenAI chat completions format, regardless of which provider handled the request.

{
  "id": "chatcmpl-a1b2c3d4e5f6g7h8i9j0k",
  "object": "chat.completion",
  "created": 1735689600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 9,
    "total_tokens": 19
  }
}

Streaming

Set "stream": true to receive tokens as Server-Sent Events. Use --no-buffer with curl to see chunks as they arrive:

curl https://api.maig.dev/v1/chat/completions \
  --no-buffer \
  -H "Authorization: Bearer maig_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

The response is a sequence of data: lines, each containing a JSON chunk. The stream ends with data: [DONE]:

data: {"id":"chatcmpl-a1b2c3d4","object":"chat.completion.chunk","created":1735689600,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-a1b2c3d4","object":"chat.completion.chunk","created":1735689600,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"! How"},"finish_reason":null}]}

data: {"id":"chatcmpl-a1b2c3d4","object":"chat.completion.chunk","created":1735689600,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":" can I help?"},"finish_reason":"stop"}]}

data: [DONE]

Using Claude

Pass any Anthropic model name — model names starting with claude- are automatically routed to Anthropic. The request and response format remain identical.

curl https://api.maig.dev/v1/chat/completions \
  -H "Authorization: Bearer maig_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Using Gemini

Pass any Google model name — model names starting with gemini- are automatically routed to Google. The request and response format remain identical.

curl https://api.maig.dev/v1/chat/completions \
  -H "Authorization: Bearer maig_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Error Codes

The gateway returns standard HTTP status codes. Error responses include a JSON body with an error object.