{
  "openapi": "3.1.0",
  "info": {
    "title": "TOKEN API",
    "version": "1.0.0",
    "summary": "One OpenAI-compatible API for the models in TOKEN's catalog.",
    "description": "TOKEN serves the OpenAI Chat Completions, Responses, Embeddings and Models endpoints, and the Anthropic Messages endpoint, at https://api.thetoken.dev/v1. The `model` lists in this document are generated from TOKEN's model catalog (https://thetoken.dev/models.json) when the site is built. Errors and limits: https://thetoken.dev/docs/errors/.",
    "license": {
      "name": "AGPL-3.0-or-later",
      "url": "https://www.gnu.org/licenses/agpl-3.0.html"
    }
  },
  "servers": [
    {
      "url": "https://api.thetoken.dev/v1",
      "description": "Every path below is relative to this URL. Anthropic SDKs and Claude Code take the base URL without /v1 (https://api.thetoken.dev) and add /v1/messages themselves."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "OpenAI format"
    },
    {
      "name": "Anthropic format"
    }
  ],
  "paths": {
    "/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "tags": [
          "OpenAI format"
        ],
        "summary": "Create a chat completion",
        "description": "OpenAI Chat Completions. With `stream: true` the reply comes as server-sent events (`data: {...}` lines, then `data: [DONE]`); the last chunk before `[DONE]` carries `usage` unless `stream_options.include_usage` is false.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "example": {
                "model": "zai-org/glm-5.3-flash",
                "messages": [
                  {
                    "role": "user",
                    "content": "Say hello in one short sentence."
                  }
                ],
                "max_tokens": 256
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The completion (JSON), or a stream of chunks when `stream` is true.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletion"
                },
                "example": {
                  "id": "chatcmpl-8f2c1e0b6a",
                  "object": "chat.completion",
                  "created": 1761379200,
                  "model": "zai-org/glm-5.3-flash",
                  "choices": [
                    {
                      "index": 0,
                      "message": {
                        "role": "assistant",
                        "content": "Hello, nice to meet you!"
                      },
                      "finish_reason": "stop"
                    }
                  ],
                  "usage": {
                    "prompt_tokens": 14,
                    "completion_tokens": 9,
                    "total_tokens": 23,
                    "prompt_tokens_details": {
                      "cached_tokens": 0
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/responses": {
      "post": {
        "operationId": "createResponse",
        "tags": [
          "OpenAI format"
        ],
        "summary": "Create a response",
        "description": "OpenAI Responses API. Send `input` as a string or as a list of input items. Streams use the Responses event types (`response.output_text.delta`, ..., `response.completed`).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResponseRequest"
              },
              "example": {
                "model": "openai/gpt-oss-120b",
                "input": "Name three prime numbers.",
                "max_output_tokens": 512
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The response object, or a stream of events when `stream` is true.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Response"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/messages": {
      "post": {
        "operationId": "createMessage",
        "tags": [
          "Anthropic format"
        ],
        "summary": "Create a message (Anthropic format)",
        "description": "Anthropic Messages API at https://api.thetoken.dev/v1/messages, for Anthropic SDKs and tools such as Claude Code. Authenticate with `Authorization: Bearer` or `x-api-key`. Errors raised by the relay come in Anthropic's format (`{\"type\": \"error\", \"error\": {...}}`); key and rate-limit errors, checked before the request is read, come in the OpenAI format.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageRequest"
              },
              "example": {
                "model": "moonshotai/kimi-k3",
                "max_tokens": 1024,
                "messages": [
                  {
                    "role": "user",
                    "content": "Explain failover in one paragraph."
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The message, or a stream of Anthropic events when `stream` is true.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                },
                "example": {
                  "id": "msg_01a9c3e7",
                  "type": "message",
                  "role": "assistant",
                  "model": "moonshotai/kimi-k3",
                  "content": [
                    {
                      "type": "text",
                      "text": "Failover means that when one provider fails, the request is sent to the next one."
                    }
                  ],
                  "stop_reason": "end_turn",
                  "usage": {
                    "input_tokens": 15,
                    "output_tokens": 21
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/embeddings": {
      "post": {
        "operationId": "createEmbedding",
        "tags": [
          "OpenAI format"
        ],
        "summary": "Create embeddings",
        "description": "OpenAI Embeddings. `input` is a string or a list of strings; each result is a list of floats.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingRequest"
              },
              "example": {
                "model": "baai/bge-m3",
                "input": [
                  "The quick brown fox",
                  "Le renard brun"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One embedding per input, in order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmbeddingList"
                },
                "example": {
                  "object": "list",
                  "model": "baai/bge-m3",
                  "data": [
                    {
                      "object": "embedding",
                      "index": 0,
                      "embedding": [
                        0.0123,
                        -0.0456,
                        0.0789
                      ]
                    },
                    {
                      "object": "embedding",
                      "index": 1,
                      "embedding": [
                        0.0119,
                        -0.0441,
                        0.0802
                      ]
                    }
                  ],
                  "usage": {
                    "prompt_tokens": 10,
                    "total_tokens": 10
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/models": {
      "get": {
        "operationId": "listModels",
        "tags": [
          "OpenAI format"
        ],
        "summary": "List models",
        "description": "The models your key can use (all catalog models, or the key's allow-list). The public catalog with prices and providers, without a key: https://thetoken.dev/models.json.",
        "responses": {
          "200": {
            "description": "The model list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                },
                "example": {
                  "object": "list",
                  "success": true,
                  "data": [
                    {
                      "id": "moonshotai/kimi-k3",
                      "object": "model",
                      "created": 1626777600
                    },
                    {
                      "id": "baai/bge-m3",
                      "object": "model",
                      "created": 1626777600
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your TOKEN API key (it starts with tkn_; older keys start with sk- or thetoken_ and keep working), from the console's API Keys page."
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Anthropic-style key header; accepted on /messages and /models."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request is invalid, for example tools sent to a model without tool calling.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The key is missing, invalid, disabled, expired or used up.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Insufficient balance or key spending limit, or the model is not allowed for this key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Per-account rate limit (requests per minute) or concurrency limit (requests in flight) reached.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unavailable": {
        "description": "No provider can serve the model for this key's group right now.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "ChatModel": {
        "type": "string",
        "description": "A chat model ID or alias from the catalog. Without tool calling: meta-llama/llama-4-maverick.",
        "enum": [
          "moonshotai/kimi-k3",
          "kimi-k3",
          "zai-org/glm-5.3",
          "glm-5.3",
          "zai-org/glm-5.3-flash",
          "glm-5.3-flash",
          "deepseek/deepseek-v4-pro",
          "deepseek-v4-pro",
          "deepseek/deepseek-v4.1-flash",
          "deepseek-v4.1-flash",
          "openai/gpt-oss-120b",
          "gpt-oss-120b",
          "openai/gpt-oss-20b",
          "gpt-oss-20b",
          "google/gemma-4-31b-it",
          "gemma-4-31b-it",
          "google/gemma-4-26b-a4b-it",
          "gemma-4-26b-a4b-it",
          "meta-llama/llama-4-maverick",
          "llama-4-maverick"
        ]
      },
      "EmbeddingModel": {
        "type": "string",
        "description": "An embedding model ID or alias from the catalog.",
        "enum": [
          "baai/bge-m3",
          "bge-m3"
        ]
      },
      "ChatMessage": {
        "type": "object",
        "required": [
          "role"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "developer",
              "user",
              "assistant",
              "tool"
            ]
          },
          "content": {
            "description": "A string, or a list of content parts (`{\"type\": \"text\", ...}`, `{\"type\": \"image_url\", ...}` for models with image input).",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Tool calls made by the assistant."
          },
          "tool_call_id": {
            "type": "string",
            "description": "For `role: tool`: the call this message answers."
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/ChatModel"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            },
            "description": "The conversation so far."
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Maximum output tokens. Lowered automatically when your balance or the key's spending limit cannot pay for it."
          },
          "max_completion_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Same as `max_tokens` (newer OpenAI name)."
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "Stream the reply as server-sent events."
          },
          "stream_options": {
            "type": "object",
            "properties": {
              "include_usage": {
                "type": "boolean",
                "default": true
              }
            },
            "description": "`include_usage`: send `usage` in the last chunk (on unless set to false)."
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2
          },
          "top_p": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "stop": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Function tools (`{\"type\": \"function\", \"function\": {...}}`). Refused with 400 by models without tool calling."
          },
          "tool_choice": {
            "description": "`auto`, `none`, `required`, or a specific function.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object"
              }
            ]
          },
          "response_format": {
            "type": "object",
            "description": "`{\"type\": \"json_object\"}` or `{\"type\": \"json_schema\", \"json_schema\": {...}}` on models with structured output."
          },
          "reasoning_effort": {
            "type": "string",
            "description": "For example `low`, `medium` or `high`, on reasoning models that accept an effort level (see each model's page)."
          }
        }
      },
      "ChatCompletion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "chat.completion"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string",
            "description": "The model as reported by the provider that served the request; its spelling can differ from the name you sent."
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "type": "object",
                  "properties": {
                    "role": {
                      "type": "string"
                    },
                    "content": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "reasoning_content": {
                      "type": "string",
                      "description": "Reasoning text, from reasoning models that return it."
                    },
                    "tool_calls": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                },
                "finish_reason": {
                  "type": "string",
                  "description": "`stop`, `length`, `tool_calls` or `content_filter`."
                }
              }
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "prompt_tokens": {
            "type": "integer"
          },
          "completion_tokens": {
            "type": "integer",
            "description": "Output tokens, reasoning included."
          },
          "total_tokens": {
            "type": "integer"
          },
          "prompt_tokens_details": {
            "type": "object",
            "properties": {
              "cached_tokens": {
                "type": "integer",
                "description": "Input tokens billed at the cached-input price."
              }
            }
          },
          "completion_tokens_details": {
            "type": "object",
            "properties": {
              "reasoning_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "ResponseRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/ChatModel"
          },
          "input": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            ]
          },
          "instructions": {
            "type": "string",
            "description": "System instructions."
          },
          "max_output_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Maximum output tokens. Lowered automatically when your balance or the key's spending limit cannot pay for it."
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "text": {
            "type": "object",
            "description": "Output format, for example `{\"format\": {\"type\": \"json_schema\", ...}}`."
          },
          "reasoning": {
            "type": "object",
            "description": "For example `{\"effort\": \"low\"}`."
          }
        }
      },
      "Response": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "response"
          },
          "status": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "output": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "input_tokens": {
                "type": "integer"
              },
              "output_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "MessageRequest": {
        "type": "object",
        "required": [
          "model",
          "max_tokens",
          "messages"
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/ChatModel"
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Maximum output tokens. Lowered automatically when your balance or the key's spending limit cannot pay for it."
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "`{\"role\": \"user\" | \"assistant\", \"content\": string | blocks}`."
          },
          "system": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            ]
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Anthropic tools (`name`, `description`, `input_schema`). Refused with 400 by models without tool calling."
          },
          "tool_choice": {
            "type": "object"
          },
          "temperature": {
            "type": "number"
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "const": "message"
          },
          "role": {
            "type": "string",
            "const": "assistant"
          },
          "model": {
            "type": "string"
          },
          "content": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "`text`, `thinking` and `tool_use` blocks."
          },
          "stop_reason": {
            "type": "string",
            "description": "`end_turn`, `max_tokens`, `stop_sequence` or `tool_use`."
          },
          "usage": {
            "type": "object",
            "properties": {
              "input_tokens": {
                "type": "integer"
              },
              "output_tokens": {
                "type": "integer"
              },
              "cache_read_input_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "EmbeddingRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "$ref": "#/components/schemas/EmbeddingModel"
          },
          "input": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ],
            "description": "Text, or a list of texts, to embed."
          },
          "encoding_format": {
            "type": "string",
            "enum": [
              "float"
            ],
            "default": "float"
          }
        }
      },
      "EmbeddingList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "list"
          },
          "model": {
            "type": "string"
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "object": {
                  "type": "string",
                  "const": "embedding"
                },
                "index": {
                  "type": "integer"
                },
                "embedding": {
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                }
              }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "prompt_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "ModelList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "list"
          },
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "object": {
                  "type": "string",
                  "const": "model"
                },
                "created": {
                  "type": "integer"
                },
                "owned_by": {
                  "type": "string"
                },
                "supported_endpoint_types": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "OpenAI-format error. The message ends with the request id, which support can look up: \"... (request id: <id>)\".",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "examples": [
                  "new_api_error"
                ]
              },
              "param": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "examples": [
                  "concurrency_limit_exceeded",
                  "insufficient_user_quota",
                  "invalid_request",
                  "model_not_found"
                ]
              }
            }
          }
        }
      }
    }
  }
}