Base URLs and authentication
The gateway's base URLs for each SDK, the headers ACOG reads your gateway key from, request limits and request IDs.
Base URLs
| Deployment | Gateway | Management API |
|---|---|---|
| Hosted | https://gateway.acog.tessarac.com | https://acog.tessarac.com/api |
| Self-hosted | https://<your-acog-host>/gateway | https://<your-acog-host>/api |
On the hosted service the gateway has its own address, with nothing between your application and ACOG but a load balancer. The console’s address also serves the gateway, at https://acog.tessarac.com/gateway, and integrations made before October 2026 may use it. That path goes through the edge network in front of the console: a request that sends nothing back for 60 seconds is closed with 504, and some errors arrive as an HTML page. Move to gateway.acog.tessarac.com; nothing else changes, and the same keys work on both.
What you configure depends on the path your SDK appends:
| Client | Base URL to configure | Why |
|---|---|---|
| OpenAI SDKs and OpenAI-compatible tools | https://gateway.acog.tessarac.com/v1 | The OpenAI client appends /chat/completions to a base that already includes /v1 |
| Anthropic SDKs and Anthropic-compatible tools | https://gateway.acog.tessarac.com | The Anthropic client appends /v1/messages itself |
| Native provider SDKs | https://gateway.acog.tessarac.com/<provider> | See Native provider routes |
The two shapes are not tied to providers: ACOG translates between them, so an OpenAI SDK can call a Claude model and an Anthropic SDK can call a GPT or Gemini model.
Endpoints
| Method | Path (after the gateway base) | Page |
|---|---|---|
POST | /v1/chat/completions | Chat Completions |
POST | /v1/messages | Messages |
POST | /responses | Responses |
POST | /v1/embeddings | Embeddings |
GET | /v1/models | Models |
GET | /v1/acog/batches/{id} | Batches |
| any | /anthropic/…, /openai/…, /vertex/…, /bedrock/…, /azure/…, /custom/… | Native provider routes |
Authentication
Every request carries a gateway key (acog_…). Create one on the Developer page; see API keys.
On the compatible endpoints (/v1/… and /responses), ACOG reads the key from the first of these that is present:
Authorization: Bearer acog_…x-acog-key: acog_…x-api-keyorapi-key, but only when the value starts withacog_
So with the Anthropic SDK, pass the gateway key as auth_token (Python) or authToken (TypeScript), which is sent as a bearer token, rather than as api_key. A provider key in x-api-key is never treated as a gateway key.
Native routes read the key from the header their provider’s SDK uses. See Native provider routes.
Your provider credentials are never forwarded
ACOG removes x-api-key, api-key and any Authorization header that is not a gateway key before forwarding a request, and authenticates to your provider with your connection’s own credentials.
What a failed authentication looks like
| Status | error.type | Meaning |
|---|---|---|
401 | unauthorized | No key was found, or the key is unknown, disabled, expired, or used from an address outside its IP allowlist. The message does not say which. |
403 | forbidden | The key is valid but lacks the gateway access scope (proxy). |
503 | service_unavailable | ACOG could not reach its key store. Retry. |
A disabled key stops working within about five seconds.
Request limits
| Limit | Value |
|---|---|
| Request body | 64 MiB. Larger requests are refused with 413 request_too_large. |
| Waiting for a non-streaming reply | Up to 10 minutes without data on gateway.acog.tessarac.com; 60 seconds on acog.tessarac.com/gateway. Self-hosted, 2 minutes unless your operator sets ACOG_UPSTREAM_READ_TIMEOUT_SECS, and no longer than your load balancer allows. |
| Waiting between streamed chunks | The same limit applies to silence from the provider. ACOG sends a keep-alive comment every 15 seconds, so a stream stays open for as long as the model keeps working. |
Rate limits and budgets are your organization’s own. See Rate limits and Budgets.
Request IDs
Every response carries x-request-id. Send your own x-request-id and ACOG uses it; otherwise it generates one. Quote it when you contact support.
Useful request headers
| Header | Effect | Page |
|---|---|---|
x-acog-channel | Pin the request to one platform | Routing and failover |
x-acog-batch | Run the request at batch prices | Batches |
x-acog-cache-control | Control the response cache | Caching |
x-acog-label | Tag the request for reports (a ticket number, a cost center) | Request headers |
The full list is in Request headers.