> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokios.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# Tokios API Endpoints: OpenAI & Anthropic Reference

> Reference for Tokios API endpoints — /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /v1/models — request/response schemas.

All Tokios API requests are sent to `https://api.tokios.com` with your `sk-tok-...` key as a Bearer token. Tokios exposes the OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages surfaces, plus model listing and token counting.

> [!NOTE]
>
> **Base URL**
>
> ```text theme={"theme":{"light":"github-light","dark":"css-variables"}}
> https://api.tokios.com
> ```

> [!TIP]
>
> **Try it live** — test any registered model in the [console Playground](https://tokios.com/console/playground) with no code. It runs against your signed-in session, so you don't even need an API key to experiment.

## Authentication

Every request requires these headers:

```http theme={"theme":{"light":"github-light","dark":"css-variables"}}
Authorization: Bearer sk-tok-YOUR_KEY
Content-Type: application/json
```

The `model` field in each request is the **public deployment name** you registered (e.g. `gemma-tunnel`), not your local model id.

***

## Usage examples

POST
`/v1/chat/completions`
OpenAI dialect

Common request shapes against `/v1/chat/completions`. Replace `sk-tok-YOUR_KEY` and `gemma-tunnel` with your own. Streaming and tool calling depend on the underlying model supporting them.

> [tab] Basic
>
> ```bash curl theme={"theme":{"light":"github-light","dark":"css-variables"}}
> curl https://api.tokios.com/v1/chat/completions \
>   -H "Authorization: Bearer sk-tok-YOUR_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gemma-tunnel",
>     "messages": [{"role": "user", "content": "What is 2 + 2?"}]
>   }'
> ```
>
> ```python Python theme={"theme":{"light":"github-light","dark":"css-variables"}}
> from openai import OpenAI
>
> client = OpenAI(api_key="sk-tok-YOUR_KEY", base_url="https://api.tokios.com/v1")
>
> resp = client.chat.completions.create(
>     model="gemma-tunnel",
>     messages=[{"role": "user", "content": "What is 2 + 2?"}],
> )
> print(resp.choices[0].message.content)
> ```

> [tab] Streaming
>
> ```bash curl theme={"theme":{"light":"github-light","dark":"css-variables"}}
> curl https://api.tokios.com/v1/chat/completions \
>   -H "Authorization: Bearer sk-tok-YOUR_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gemma-tunnel",
>     "messages": [{"role": "user", "content": "Write a haiku about tunnels."}],
>     "stream": true
>   }'
> ```
>
> ```python Python theme={"theme":{"light":"github-light","dark":"css-variables"}}
> from openai import OpenAI
>
> client = OpenAI(api_key="sk-tok-YOUR_KEY", base_url="https://api.tokios.com/v1")
>
> stream = client.chat.completions.create(
>     model="gemma-tunnel",
>     messages=[{"role": "user", "content": "Write a haiku about tunnels."}],
>     stream=True,
> )
> for chunk in stream:
>     print(chunk.choices[0].delta.content or "", end="")
> ```

> [tab] Tool calling
>
> ```bash curl theme={"theme":{"light":"github-light","dark":"css-variables"}}
> curl https://api.tokios.com/v1/chat/completions \
>   -H "Authorization: Bearer sk-tok-YOUR_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gemma-tunnel",
>     "messages": [{"role": "user", "content": "What is the weather in Paris?"}],
>     "tools": [{
>       "type": "function",
>       "function": {
>         "name": "get_weather",
>         "description": "Get the current weather for a city",
>         "parameters": {
>           "type": "object",
>           "properties": {"city": {"type": "string"}},
>           "required": ["city"]
>         }
>       }
>     }]
>   }'
> ```
>
> ```python Python theme={"theme":{"light":"github-light","dark":"css-variables"}}
> from openai import OpenAI
>
> client = OpenAI(api_key="sk-tok-YOUR_KEY", base_url="https://api.tokios.com/v1")
>
> tools = [{
>     "type": "function",
>     "function": {
>         "name": "get_weather",
>         "description": "Get the current weather for a city",
>         "parameters": {
>             "type": "object",
>             "properties": {"city": {"type": "string"}},
>             "required": ["city"],
>         },
>     },
> }]
>
> resp = client.chat.completions.create(
>     model="gemma-tunnel",
>     messages=[{"role": "user", "content": "What is the weather in Paris?"}],
>     tools=tools,
> )
> print(resp.choices[0].message.tool_calls)
> ```

> [tab] Windows
>
> PowerShell reads `-d @body.json` from a file to avoid quote-escaping pain:
>
> ```powershell PowerShell theme={"theme":{"light":"github-light","dark":"css-variables"}}
> $body = '{"model":"gemma-tunnel","messages":[{"role":"user","content":"What is 2 + 2?"}]}'
> Set-Content -Path body.json -Value $body -Encoding ascii
> curl.exe https://api.tokios.com/v1/chat/completions `
>   -H "Authorization: Bearer sk-tok-YOUR_KEY" `
>   -H "Content-Type: application/json" `
>   -d "@body.json"
> ```

***

POST
`/v1/chat/completions`
OpenAI dialect

## POST /v1/chat/completions

Works with supported OpenAI SDKs. Send a list of messages and receive a completion from your registered model.

### Request body

**model** `string` *required*

The public deployment name (e.g. `"gemma-tunnel"`).

**messages** `array` *required*

Array of message objects. Each has a `role` (`"system"`, `"user"`, or `"assistant"`) and `content`. Content may be a string or an array of content blocks (text, tool calls, images) — Tokios passes the structure through.

**stream** `boolean` (default: false)

Stream the response using server-sent events.

**temperature** `number`

Sampling temperature. Higher values produce more random output.

**max\_tokens** `integer`

Maximum number of tokens to generate.

Example request

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl https://api.tokios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-tunnel",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is 2 + 2?"}
    ]
  }'
```

Response · 200

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1717000000,
  "model": "gemma-tunnel",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "2 + 2 equals 4." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 9, "total_tokens": 33 }
}
```

POST
`/v1/messages`
Anthropic dialect

## POST /v1/messages

Works with supported Anthropic SDKs. Send a messages array and receive a response in Anthropic's format. Tokios translates this to Chat Completions for your model and back.

### Request body

**model** `string` *required*

The public deployment name.

**messages** `array` *required*

Array of message objects with a `role` (`"user"` or `"assistant"`) and `content` (a string or an array of content blocks).

**max\_tokens** `integer` *required*

Maximum number of tokens to generate.

**system** `string`

System prompt to prepend to the conversation.

**stream** `boolean` (default: false)

Stream the response using server-sent events.

Example request

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl https://api.tokios.com/v1/messages \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-tunnel",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Explain async/await"}]
  }'
```

Response · 200

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "Async/await is a syntax for handling asynchronous operations..." }],
  "model": "gemma-tunnel",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 12, "output_tokens": 48 }
}
```

POST
`/v1/messages/count_tokens`
Anthropic dialect

## POST /v1/messages/count\_tokens

Works with supported Anthropic SDKs. Send the same body shape as `/v1/messages` and receive the input token count without running a completion.

Example request

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl https://api.tokios.com/v1/messages/count_tokens \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-tunnel",
    "messages": [{"role": "user", "content": "Explain async/await"}]
  }'
```

Response · 200

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{ "input_tokens": 12 }
```

POST
`/v1/responses`
OpenAI dialect

## POST /v1/responses

Works with supported OpenAI SDKs using the newer Responses format (used by OpenAI Codex). Tokios translates it to Chat Completions for your model.

### Request body

**model** `string` *required*

The public deployment name.

**input** `string | array` *required*

The input text, or an array of input items, to generate a response for.

**stream** `boolean` (default: false)

Stream the response using server-sent events.

Example request

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl https://api.tokios.com/v1/responses \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-tunnel",
    "input": "Write a haiku about tunnels."
  }'
```

GET
`/v1/models`
OpenAI dialect

## GET /v1/models

Lists the model deployments your API key can use. Works with supported OpenAI SDKs using the standard list shape.

Example request

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl https://api.tokios.com/v1/models \
  -H "Authorization: Bearer sk-tok-YOUR_KEY"
```

Response · 200

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "object": "list",
  "data": [
    { "id": "gemma-tunnel", "object": "model", "owned_by": "tokios" },
    { "id": "qwen-coder", "object": "model", "owned_by": "tokios" }
  ]
}
```

> [!NOTE]
>
> Claude Code's model picker only lists `claude*` ids, so it won't show your Tokios models. Pass the model explicitly with `claude --model gemma-tunnel` — see the [Claude Code guide](https://docs.tokios.com/guides/claude-code.md).

***

## Error codes

| HTTP status | Meaning |
| - | - |
| 400 | Malformed request body |
| 401 | Missing or invalid API key |
| 403 | The key isn't allowed to use this model, or the account is suspended |
| 404 | Model deployment not found |
| 503 | Connector offline or at capacity (`connector_unavailable` / `connector_busy`) |

> [!WARNING]
>
> A `503` means the connector for that deployment isn't currently connected (or is at its concurrency cap). Start the connector and confirm it shows online in the console before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.