API Reference

TokenSense is a transparent proxy — you call it the same way you'd call your AI provider directly. This page covers the endpoint format, authentication, and code examples.

Base URL

Your TokenSense endpoint is shown on your dashboard home page. All requests go through this URL:

Replace /chat/completions with the appropriate path for your provider and model type.

Supported endpoints

The most common endpoint is /v1/chat/completions — it accepts OpenAI-format requests and automatically translates for Anthropic, Gemini, xAI, and Mistral. Use the native endpoints (/v1/messages, /v1beta/models/...) when you need provider-specific features that don't map to the OpenAI format.

Authentication

Every request must include a Bearer token with your TokenSense API key:

Your TokenSense API key is not your provider key. You add provider keys separately in Settings → Providers. TokenSense uses them to forward requests on your behalf.

Supported formats

TokenSense detects the provider from the model name in your request and routes automatically. You can send requests in any of these formats:

• OpenAI format — /v1/chat/completions with any model. TokenSense translates automatically for all providers.
• Native Anthropic — /v1/messages for the Anthropic Messages API (passthrough, no translation).
• Native Gemini — /v1beta/models/{model}:{action} for the Gemini API (passthrough, no translation).

xAI and Mistral are natively OpenAI-compatible — requests pass through directly via /v1/chat/completions with zero translation.

OpenAI Responses API

The Responses API is OpenAI's newer agentic endpoint, and it's what powers tools like the OpenAI Agents SDK and Vercel AI SDK. TokenSense now supports it at /v1/responses, so any tool that uses the Responses API can run through your TokenSense endpoint with full cost tracking on every request.

With OpenAI models, everything works as a native passthrough. Built-in tools (web search, file search, code interpreter, image generation), remote MCP tools, and stateful sessions (using store or previous_response_id) all work unchanged, and token usage is tracked on every request.

Note on built-in tool fees: OpenAI charges separate per-use fees for built-in tools (web search, file search, code interpreter, image generation) on top of token usage. Those tool fees are not yet includedin TokenSense's cost figures — calls that use them are flagged in your logs, and budgets currently count token cost only. Account for built-in tool fees separately until per-tool pricing lands.

With other providers (Anthropic, Gemini, xAI, Mistral), TokenSense automatically translates standard requests and function/tool calls so they work through the same /v1/responsesendpoint. However, OpenAI-only features like built-in tools, MCP, and stateful storage aren't available on other providers — if you try to use them, you'll get a clear error message explaining why.

Tip: If a tool lets you choose between the Responses API and Chat Completions and you run into issues on a non-OpenAI model, switch it to Chat Completions. For example, Twenty CRM uses OPENAI_COMPATIBLE_API_TYPE=chat for this.

Attribution headers

Add these optional headers to track costs per workflow and step in your dashboard:

Response format

TokenSense returns the exact same response as the upstream provider. Your code doesn't need any changes to parse the response — it's identical to calling the provider directly.

Code examples

cURL

curl https://api.tokensense.io/chat/completions \
  -H "Authorization: Bearer YOUR_TOKENSENSE_KEY" \
  -H "Content-Type: application/json" \
  -H "x-workflow-tag: my-workflow" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [
      {"role": "user", "content": "Hello, world!"}
    ]
  }'

Python

import requests

response = requests.post(
    "https://api.tokensense.io/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_TOKENSENSE_KEY",
        "Content-Type": "application/json",
        "x-workflow-tag": "my-workflow",
    },
    json={
        "model": "gpt-5-mini",
        "messages": [
            {"role": "user", "content": "Hello, world!"}
        ],
    },
)

print(response.json())

Node.js

const response = await fetch(
  "https://api.tokensense.io/chat/completions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_TOKENSENSE_KEY",
      "Content-Type": "application/json",
      "x-workflow-tag": "my-workflow",
    },
    body: JSON.stringify({
      model: "gpt-5-mini",
      messages: [
        { role: "user", content: "Hello, world!" },
      ],
    }),
  }
);

const data = await response.json();
console.log(data);

Error responses

See the full Error Codes reference for detailed troubleshooting.

Related

• Make & Zapier Setup
• n8n Setup Guide
• Cost Attribution
• Supported Providers