Contents

FreeTheAI Gateway API

One marketplace gateway with OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages wire formats. Authenticate with an API key created in the console; the routing rule on the key selects a provider per request. Use the exact model IDs from GET /v1/models: free FreeTheAI models are named fta/<provider>/<model> and need a verified email and the daily check-in on the website. Streaming responses include token usage in the final chunk.

Base URL: https://api.freetheai.org
Authentication: Authorization: Bearer <key>; Create a key in the console. Each key carries its own routing rule, spend limit, and wallet.

Setting up an app? Step-by-step guides for JanitorAI, SillyTavern, Claude Code and more are on the setup page.

Machine-readable specification: /openapi.jsonVersion 1.0.0

Inference

OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages.

POST/v1/chat/completionsCreate a chat completion

Routes the OpenAI Chat Completions wire format to the provider selected by the API key.

Request body

OpenAI Chat Completions request. Unknown OpenAI-compatible fields are forwarded when supported by the selected route.

max_tokensinteger (int64)Maximum generated tokens when supported.
messagesarray of objectRequiredConversation messages.
modelstringRequiredModel id from GET /v1/models.
streambooleanReturn server-sent events when true.

Responses

200: Successful provider response.
choicesarray of object
idstring
modelstring
objectstring
usageobject
400: The request body is invalid, uses a parameter the model does not support, or calls an endpoint the model does not serve. When the provider itself refused the request, the error carries an error ID (in error.error_id and the X-Error-ID header).
errorobject
401: The API key is missing, malformed, revoked, or expired.
errorobject
402: Your wallet balance cannot cover this paid route.
errorobject
403: The request is not allowed: your email is not verified, free models need today's check-in, your account is on hold, your key does not allow this model, provider, or IP address, your network or client is blocked, or the request was relayed through a Cloudflare Worker (call the API directly).
errorobject
404: The model does not exist or has no available route.
errorobject
413: The request body is larger than the gateway accepts.
errorobject
429: A rate limit, concurrency limit, or your daily free request limit was reached.
errorobject
502: The upstream provider failed, or the stream broke after it started. The error ID (such as freetheai-1a2b3c4d5e6f) is at the end of the message, in error.error_id, and in the X-Error-ID header; a broken stream ends with an error event that carries it.
errorobject
503: The model is at capacity or the service is temporarily unavailable.
errorobject

POST/v1/responsesCreate a model response

Routes the OpenAI Responses wire format to the provider selected by the API key.

Request body

OpenAI Responses request. Unknown Responses fields are forwarded when supported by the selected route.

inputobjectString or structured Responses input.
instructionsstring
modelstringRequiredModel id from GET /v1/models.
streambooleanReturn server-sent events when true.

Responses

200: Successful provider response.
idstring
modelstring
objectstring
outputarray of object
usageobject
400: The request body is invalid, uses a parameter the model does not support, or calls an endpoint the model does not serve. When the provider itself refused the request, the error carries an error ID (in error.error_id and the X-Error-ID header).
errorobject
401: The API key is missing, malformed, revoked, or expired.
errorobject
402: Your wallet balance cannot cover this paid route.
errorobject
403: The request is not allowed: your email is not verified, free models need today's check-in, your account is on hold, your key does not allow this model, provider, or IP address, your network or client is blocked, or the request was relayed through a Cloudflare Worker (call the API directly).
errorobject
404: The model does not exist or has no available route.
errorobject
413: The request body is larger than the gateway accepts.
errorobject
429: A rate limit, concurrency limit, or your daily free request limit was reached.
errorobject
502: The upstream provider failed, or the stream broke after it started. The error ID (such as freetheai-1a2b3c4d5e6f) is at the end of the message, in error.error_id, and in the X-Error-ID header; a broken stream ends with an error event that carries it.
errorobject
503: The model is at capacity or the service is temporarily unavailable.
errorobject

POST/v1/messagesCreate an Anthropic message

Routes the Anthropic Messages wire format to the provider selected by the API key. Send the Anthropic version header required by your client.

Request body

Anthropic Messages request. Unknown Anthropic-compatible fields are forwarded when supported by the selected route.

max_tokensinteger (int64)RequiredMaximum generated tokens.
messagesarray of objectRequiredAnthropic-format conversation messages.
modelstringRequiredModel id from GET /v1/models.
streambooleanReturn Anthropic server-sent events when true.
systemobjectSystem prompt as a string or Anthropic content blocks.

Responses

200: Successful provider response.
contentarray of object
idstring
modelstring
rolestring
stop_reasonstring
typestring
usageobject
400: The request body is invalid, uses a parameter the model does not support, or calls an endpoint the model does not serve. When the provider itself refused the request, the error carries an error ID (in error.error_id and the X-Error-ID header).
errorobject
401: The API key is missing, malformed, revoked, or expired.
errorobject
402: Your wallet balance cannot cover this paid route.
errorobject
403: The request is not allowed: your email is not verified, free models need today's check-in, your account is on hold, your key does not allow this model, provider, or IP address, your network or client is blocked, or the request was relayed through a Cloudflare Worker (call the API directly).
errorobject
404: The model does not exist or has no available route.
errorobject
413: The request body is larger than the gateway accepts.
errorobject
429: A rate limit, concurrency limit, or your daily free request limit was reached.
errorobject
502: The upstream provider failed, or the stream broke after it started. The error ID (such as freetheai-1a2b3c4d5e6f) is at the end of the message, in error.error_id, and in the X-Error-ID header; a broken stream ends with an error event that carries it.
errorobject
503: The model is at capacity or the service is temporarily unavailable.
errorobject

Models

Model discovery.

GET/v1/modelsList available models

Returns first-party and marketplace models the calling key may reach. Per-key allowlists filter this listing; group and scope limits stay enforced at dispatch.

Responses

200: Model list.
dataarray of Model
objectstring
401: Missing or invalid API key.
errorobject

Service

Health and status.

GET/v1/healthNo authService health

Responses

200: Service is reachable.
statusstring

Errors

Every error returns the same JSON shape and a generic message; upstream details are never shown. When an upstream provider fails, the message ends with an error ID that Support can look up.

{"error": {"message": "Rate or concurrency limit reached.", "type": "gateway_error"}}

Status	Meaning	What to do
400	The request body is invalid, uses a parameter the model does not support, or calls an endpoint the model does not serve. When the provider itself refused the request, the error carries an error ID (in error.error_id and the X-Error-ID header).	Fix the request. Check the model's endpoint and parameters on its model page.
401	The API key is missing, malformed, revoked, or expired.	Send Authorization: Bearer <key> with an active key from the API keys page.
402	Your wallet balance cannot cover this paid route.	Add funds to your wallet, or use a free model.
403	The request is not allowed: your email is not verified, free models need today's check-in, your account is on hold, your key does not allow this model, provider, or IP address, your network or client is blocked, or the request was relayed through a Cloudflare Worker (call the API directly).	Verify your email, complete the daily check-in on the website, check the key's restrictions, or open a Support ticket if your account is on hold.
404	The model does not exist or has no available route.	List models with GET /v1/models and use an exact model ID.
413	The request body is larger than the gateway accepts.	Send a smaller request.
429	A rate limit, concurrency limit, or your daily free request limit was reached.	Wait and retry. Your plan page shows your limits and when the daily count resets.
502	The upstream provider failed, or the stream broke after it started. The error ID (such as freetheai-1a2b3c4d5e6f) is at the end of the message, in error.error_id, and in the X-Error-ID header; a broken stream ends with an error event that carries it.	Retry, or try another model. If it keeps happening, send the error ID to Support.
503	The model is at capacity or the service is temporarily unavailable.	Retry with exponential backoff.