API Reference

Base URL

Every request goes to:

Authentication

Create a key on the API keys page, then send it as a bearer token in the Authorization header. Only a hash of your key is ever stored — copy it when it's created, because GatifyAI cannot show it to you again.

Quick start

A minimal request in curl, Python, or TypeScript:

curl https://gatifyai.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Restricting a key to specific models

By default a new key can use any of GatifyAI's free models, with the same automatic fallover the web chat uses if one is unavailable. You can restrict a key to a specific model or a short list instead — the key will then only ever use models from that list, in the order you gave them, regardless of what model a request asks for. Requesting a model outside that list returns a 400 error naming the models the key is actually allowed to use.

Chatting as a persona

Pass model: "persona/<slug>" to chat as a persona published in the community gallery — its personality and preferred models are used automatically, still constrained by your key's allowed models if you set any. Find a persona's slug and a ready-made example on its own page, under the API tab.

{
  "model": "persona/senior-engineer",
  "messages": [{"role": "user", "content": "Review my code."}]
}

Streaming vs. non-streaming

Set stream: true to receive tokens as they're generated, exactly like the OpenAI streaming format (Server-Sent Events, terminated by [DONE]). Omit it, or set it to false, to wait for the full reply and get back one JSON response — this is the default.

Errors

Errors follow the OpenAI error shape: {"error": {"message": "...", "type": "..."}}. A 401 means a missing, invalid, or revoked key. A 400 means the request itself is invalid — most often an unrecognized model, an unpublished/unknown persona slug, or a model outside your key's allowed list. A 502 means every candidate model failed to respond.

{
  "error": {
    "message": "This API key may only use: llama-3.1-8b:free",
    "type": "invalid_request_error"
  }
}

Rate limits

API requests count against the same per-account chat rate limit as the web app — there is no separate quota for API traffic today.