Set base_url (Python) or baseURL (TypeScript) to https://gateway.traccia.ai/openai/v1. Send both Traccia headers on the client with default_headers / defaultHeaders. Keep OPENAI_API_KEY on the client.

What this Gateway accepts

OpenAI: POST /openai/v1/chat/completions and GET /openai/v1/models, also under /agents/{agent_id}/v1 and /openai/agents/{agent_id}/v1 with the agent ID in the path. Anthropic: POST /anthropic/v1/messages. Gemini Developer API: POST /google/{v1beta|v1}/models/{model}:generateContent and :streamGenerateContent. Embeddings, the OpenAI Responses API, Assistants, Azure OpenAI paths, Vertex AI paths, and Anthropic Batches are not this Gateway. Those requests 404.

Headers

Header	Value
X-Traccia-Api-Key	Workspace key from Settings → API Keys
X-Traccia-Agent-Id	Same Agent ID you would pass to init

Keep the provider API key on the client. The Gateway forwards it and does not store it. Missing Traccia key returns 401. Missing agent ID returns 400. For OpenAI-compatible clients that allow only one extra header, such as n8n, put the agent ID in the URL instead: https://gateway.traccia.ai/agents/<agent-id>/v1. If both are set, the header wins.

Client

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://gateway.traccia.ai/openai/v1",
    default_headers={
        "X-Traccia-Api-Key": os.environ["TRACCIA_API_KEY"],
        "X-Traccia-Agent-Id": "billing-bot",
    },
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "hello"}],
)

The official client appends /chat/completions to this base. The request that must land is POST https://gateway.traccia.ai/openai/v1/chat/completions. Do not put /chat/completions in base_url.

What Works

client.chat.completions.create (including stream=True)
client.models.list (auth only, no policy check)

What 404s

Not Chat Completions

client.responses.create, embeddings, Assistants, Realtime, and Azure OpenAI /openai/deployments/{id}/chat/completions are not this Gateway.

Gateway: OpenAI SDK

Headers

Client

What Works

What 404s

Next Steps

Gateway Overview

Policies