Chat Completions

curl https://gateway.toolken.ai/v1/chat/completions \
  -H "X-Toolken-Key: tk_live_..." \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Say hello in one sentence."}]}'

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.toolken.ai/v1",
    api_key="sk-...",
    default_headers={"X-Toolken-Key": "tk_live_..."},
)
client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.toolken.ai/v1",
  apiKey: "sk-...",
  defaultHeaders: { "X-Toolken-Key": "tk_live_..." },
});
await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello, how can I help you today?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 14, "completion_tokens": 12, "total_tokens": 26 }
}

POST

chat

completions

curl https://gateway.toolken.ai/v1/chat/completions \
  -H "X-Toolken-Key: tk_live_..." \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Say hello in one sentence."}]}'

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.toolken.ai/v1",
    api_key="sk-...",
    default_headers={"X-Toolken-Key": "tk_live_..."},
)
client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.toolken.ai/v1",
  apiKey: "sk-...",
  defaultHeaders: { "X-Toolken-Key": "tk_live_..." },
});
await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello, how can I help you today?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 14, "completion_tokens": 12, "total_tokens": 26 }
}

Pass-through to the provider’s chat completions endpoint. Request and response bodies follow the standard OpenAI Chat Completions schema. The gateway infers the provider from the model name; override with X-Toolken-Provider.

Headers

X-Toolken-Key

string

required

Your Toolken API key. Validated by the gateway and stripped before forwarding.

Authorization

string

required

Your provider key in Bearer format (BYOK), e.g. Bearer sk-.... Forwarded untouched, never stored.

X-Toolken-Metadata

string

Primary attribution channel. JSON object of key-value pairs (e.g. {"agent":"research-agent","customer_id":"cust_abc"}). Each key becomes a groupable dimension in the dashboard.

X-Toolken-Metadata-*

string

Flat-header shorthand. X-Toolken-Metadata-Agent: research-agent writes metadata key agent. Equivalent to sending the same key in X-Toolken-Metadata.

X-Toolken-Metadata-Feature

string

Sets the feature metadata key. Use to group costs by agent name, workflow, UI surface, or job type.

X-Toolken-Metadata-Customer-Id

string

Sets the customer_id metadata key. Use to attribute costs to an end-customer, org slug, or account ID.

Body

model

string

required

Model identifier (e.g. gpt-4o).

messages

array

required

Conversation messages, following the standard OpenAI messages schema.

stream

boolean

If true, the gateway streams Server-Sent Events back from the provider.

max_tokens

integer

Maximum tokens to generate. Capped per workspace.

temperature

number

Sampling temperature. Forwarded verbatim.

Response

string

Unique completion ID.

object

string

Always chat.completion.

model

string

The model that produced the response.

choices

array

The generated choices, each with message and finish_reason.

usage

object

Token counts: prompt_tokens, completion_tokens, total_tokens.

curl https://gateway.toolken.ai/v1/chat/completions \
  -H "X-Toolken-Key: tk_live_..." \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Say hello in one sentence."}]}'

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.toolken.ai/v1",
    api_key="sk-...",
    default_headers={"X-Toolken-Key": "tk_live_..."},
)
client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.toolken.ai/v1",
  apiKey: "sk-...",
  defaultHeaders: { "X-Toolken-Key": "tk_live_..." },
});
await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello, how can I help you today?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 14, "completion_tokens": 12, "total_tokens": 26 }
}

API Errors Messages (Anthropic)

Gateway API

AI Gateway

Models

Toolken API

Chat Completions

Headers

Body

Response

​Headers

​Body

​Response

Headers

Body

Response