Docs/Budget Ai/Api Reference

API Reference

Budget AI serves an OpenAI-compatible API at https://<your-gateway-host>/v1. Point any OpenAI SDK at that base URL and use a Budget AI key as the API key. The exact address for your deployment is shown in Project Settings → Budget AI → Budget AI address.

This page covers the gateway's own API and the key minting API for short-lived agent keys. Managing model groups and budgets, and issuing other keys, is done in the product; those operations are not part of the public REST API.

Authentication

Send the key in either header:

http
Authorization: Bearer sk-ants-...
http
api-key: sk-ants-...

Requests must use Content-Type: application/json. The default body limit is 4,718,592 bytes (4.5 MiB).

Routes

MethodPathPurpose
POST/v1/chat/completionsChat completions, streaming or not
POST/v1/embeddingsEmbeddings
GET/v1/modelsThe model groups this key may call

Any other path returns 404 with code unknown_route.

POST /v1/chat/completions

The body follows the OpenAI Chat Completions API.

FieldRequiredNotes
modelNoA model group name. May be omitted or empty when the key is granted exactly one model group.
messagesYesA non-empty array; each message needs a role
streamNotrue returns server-sent events
stream_optionsNoAs in the OpenAI API
tools, temperature, max_tokens, max_completion_tokens, response_format and other parametersNoSent on to the provider. For Anthropic, AWS Bedrock and Google Vertex AI the request is translated to the provider's API.
bash
curl https://<your-gateway-host>/v1/chat/completions \ -H "Authorization: Bearer $ANTS_GATEWAY_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "prod-chat", "messages": [{"role": "user", "content": "Summarise our refund policy in one line."}], "max_tokens": 200 }'

The response is an OpenAI chat completion object. For a non-OpenAI provider it is translated to the same shape, including usage.

Streaming

With "stream": true the response is text/event-stream in the OpenAI chunk format, ending with data: [DONE]. Headers are sent when the provider sends its first byte; until then Budget AI can still retry or fail over. If the provider stream breaks after that, the stream ends with an error event and [DONE]:

text
data: {"error":{"message":"stream interrupted: ...","type":"server_error","param":null,"code":"upstream_stream_error"}} data: [DONE]

For OpenAI-compatible and Azure OpenAI providers, Budget AI asks for a final usage chunk so streamed calls are costed from real usage.

When AI Guardrails inspection applies to the key, a stream can also end with an error event coded guardrail_response_blocked or guardrail_unavailable, and can carry SSE comments: : keepalive while the gateway waits for inspection, and : x-ants-guardrail-warning: <categories> just before [DONE] for a Warn result. OpenAI SDKs ignore comments. See What the caller sees.

max_tokens matters for streaming and non-streaming calls alike: it sets the output allowance used for rate limits and budget reservations. Without it, the model group's Default output reserve is assumed (4,096 tokens when it is not set). Under a hard token budget, Budget AI can send the request with a lower output limit than you asked for and say so in the x-ants-max-tokens-capped header; see Output cap.

POST /v1/embeddings

The body follows the OpenAI Embeddings API.

FieldRequiredNotes
modelNoA model group name, with the same single-group rule as chat
inputYesText or an array, as in the OpenAI API

Embeddings are served only by deployments whose provider family has an embeddings API, which today is the OpenAI-compatible family. Streaming does not apply. The response cache does not apply. Usage is priced on input tokens.

bash
curl https://<your-gateway-host>/v1/embeddings \ -H "Authorization: Bearer $ANTS_GATEWAY_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "embeddings", "input": "The quick brown fox"}'

GET /v1/models

Lists the model groups the key is granted, sorted by name:

json
{ "object": "list", "data": [ { "id": "prod-chat", "object": "model", "created": 1760000000, "owned_by": "ants-gateway" } ] }

id is the model group name to send as model. created is when the group was created.

Caller context headers

langfuse-user-id, langfuse-session-id, langfuse-tags, langfuse-metadata and traceparent are accepted on chat completions and embeddings to attribute the request in Tracing. See Caller context headers.

When the model is served through a Portkey upstream, x-portkey-metadata (a flat JSON object, up to 4,096 characters) and x-portkey-trace-id (up to 128 characters) are passed on to Portkey on chat completions. x-portkey-api-key and x-portkey-config are never passed from the caller. See Headers passed through to Portkey.

Response headers

HeaderWhenValue
x-ants-request-idEvery chat completions and embeddings response, including errorsThe request id, which is also the trace id in Tracing
x-ants-model-groupWhen the model group was foundThe group that served the request, which is the fallback group when one was used
x-ants-deploymentWhen a deployment was chosenThe deployment id
x-ants-costServed requestsCost in USD. For streams, the estimate made at admission.
x-ants-cost-estimatedServed requeststrue for streams, otherwise false
x-ants-attemptsWhen at least one provider attempt was madeJSON list of attempts: d deployment id, o outcome (ok, retryable, failed, timeout, benched), ms duration, and where available st provider status and why provider message
x-ants-cacheResponse cache hitshit
x-ants-max-tokens-cappedChat completions whose output limit a hard token budget lowered, see Output capThe output limit the request was sent with (per completion when n is above 1)
x-ants-guardrail-warningAI Guardrails found content under a Warn actionComma-separated category names: pii, pci, phi, ethicsBias, safety. Never content. On a stream, response warnings arrive as an SSE comment instead.
retry-afterRate limit refusalsSeconds until the current minute ends

Errors

Errors use the OpenAI error envelope, so OpenAI SDKs raise their usual exception types:

json
{ "error": { "message": "This gateway key has expired.", "type": "authentication_error", "param": null, "code": "key_expired" } }

type follows the status: authentication_error (401), permission_error (403), rate_limit_error (429), invalid_request_error (other 4xx) and server_error (5xx).

StatuscodeCauseTraced
400invalid_requestThe body fails validation, for example messages is missing or emptyNo
400invalid_jsonThe body is not valid JSONNo
400embeddings_not_supportedNo deployment in the model group offers an embeddings APIYes
400guardrail_blockedAI Guardrails blocked the request, or it carries tool calls outside the agent's declared tools. The provider is not called. The message is the policy's Blocked Response Message when set.Yes
400guardrail_response_blockedAI Guardrails blocked the model's response, or the response calls tools outside the agent's declared tools. On a stream that has started, it arrives as an error event.Yes
400guardrail_unsupported_requestAI Guardrails applies to the key and the request sets n above 1Yes
401invalid_api_keyThe key is missing or unknown, or serving is off for its projectNo
401key_blockedThe key is blockedYes, sampled
401agent_suspendedThe key is bound to an agent that was suspended, see Suspend an agent. The message is "This agent has been suspended by an administrator."Yes, sampled
401key_expiredThe key is past its expiry or its rotation grace windowYes, sampled
403ip_not_allowedThe request comes from outside the key's allowed source networksYes, sampled
403model_not_allowedThe key is not granted the model group, the group does not exist, or model was omitted on a key with zero or several groupsYes
404unknown_routeThe path is not servedNo
409budget_unpriced_modelA hard dollar budget applies and the provider model has no priceYes
413request_too_largeThe body exceeds the size limitNo
415unsupported_media_typeThe body is not JSONNo
429rate_limit_exceededA key or project requests-per-minute limit is reachedYes
429tokens_limit_exceededA key or project tokens-per-minute limit is reachedYes
429budget_exceededA hard budget would be exceeded, or a hard token budget has fewer output tokens left than the project's minimum capped output; the message names the budgetYes
502upstream_unreachableNo provider could be reachedYes
502upstream_invalid_responseA provider answered 2xx with a body that is not a JSON objectYes
503no_deployment_availableThe model group has no eligible deploymentYes
503budget_config_invalidThe key's org unit budget chain cannot be builtYes
503guardrail_unavailableAI Guardrails inspection applies, could not finish (time limit, detection service unavailable, or no text to inspect), and the project refuses what it cannot inspect. On a stream that has started, it arrives as an error event.Yes
503gateway_config_staleThe gateway cannot confirm its configuration is current, or its Redis is unavailable. Retry shortly.No
504upstream_timeoutNo provider answered within the timeoutYes
Provider's statusProvider's code, or upstream_errorThe provider returned an error; its own error envelope is passed through when it has oneYes
200, then an error eventupstream_stream_errorThe provider stream broke after it startedYes
500noneUnexpected gateway errorNo

When every deployment and fallback fails, the caller receives the last provider error (or upstream_unreachable / upstream_timeout), and the trace records gateway.refusal = all_deployments_failed.

"Sampled" means the refusal is traced at most once per minute per key and reason. "Traced" refusals carry zero usage. See Observability & Cost.

ℹ

Retry 429 responses after the retry-after interval, and 503 gateway_config_stale after a short pause. Budget AI already retries provider failures inside the request according to the model group's routing policy, so aggressive client retries on 502 and 504 mostly add load.

Operational endpoints

These are for load balancers and monitoring, not for applications. They need no key.

EndpointPortMeaning
GET /healthAPI port and admin port200 when the process is up and Redis answers
GET /readyAPI port and admin portAs /health, and 503 while the gateway is draining for shutdown or its configuration is stale
GET /metricsAdmin port onlyJSON counters for requests, refusals and errors by code, latency percentiles, telemetry, configuration and process health

See Self-Hosting & Configuration for ports.

Key minting API

An authorised system can mint a short-lived Budget AI key for one agent. This endpoint is served by ANTS Platform, not by the gateway.

  • Off by default. Your ANTS deployment turns it on. Until then every call returns 403.
  • Authentication. HTTP Basic with an organization API key. A project API key is refused with 403, so an SDK key cannot mint Budget AI keys. The organization needs the API and Budget AI entitlements, and Budget AI must be enabled for the project.
bash
curl -X POST "https://<your-ants-url>/api/public/organizations/projects/<project-id>/gateway-keys" \ -u "$ANTS_ORG_PUBLIC_KEY:$ANTS_ORG_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "agentId": "<agent-id>", "modelGroupIds": ["<model-group-id>"], "expiresInMinutes": 120, "budgetUsd": 5 }'
Request fieldRequiredDescription
agentIdYesThe agent the key is bound to. It must exist in the project.
modelGroupIdsYesIDs of the model groups the key may call, at least one
expiresInMinutesYesLifetime in minutes, at least 1. It cannot exceed the project's maximum key expiry.
budgetUsdYesA key budget in USD. Like Monthly budget (USD, optional) on the issue form, it resets monthly and is alert only: it records threshold crossings but does not stop requests. See Short-lived keys for agents. Because it is in dollars, every mint in a project that budgets in tokens is refused with 400.
aliasNoA name for the key, unique in the project. A name is generated when omitted.
rpmLimit, tpmLimitNoRequests and tokens per minute limits for the key
tagsNoTags for the key
allowedCidrsNoIPv4 or IPv6 addresses or CIDR ranges the key may be used from
orgUnitIdNoPlace the key in an org unit, so that unit's budget applies

Fields that are not listed are refused.

A successful request returns 201 with the key. The response is sent with Cache-Control: no-store.

json
{ "id": "<key-id>", "key": "<secret, shown once>", "alias": "task-invoice-reader-1a2b3c4d", "agentId": "<agent-id>", "expiresAt": "2026-10-19T10:30:00.000Z", "propagated": true, "availableInMs": 0 }

The plaintext key appears only in this response. Store it where the agent can read it, and do not log it. Every minted key is written to the audit log.

When the key can be used

A new key reaches the gateways within about 2 seconds. availableInMs is how long to wait before the first call; it is 0 when the key is already live. If propagated is false, the gateways pick the key up on their next full reload, up to 60 seconds later. Use a lifetime of at least 5 minutes.

Errors

StatusMeaning
400Invalid body, a lifetime above the project maximum, or the project budgets in tokens (This project budgets in tokens.)
401Bad credentials
403The API is off, the key is not an organization key, or the plan or Budget AI does not allow it
404Project, agent or model group not found
409The alias is already used in the project
429Too many keys. A project can mint 60 keys per minute and an agent can hold 100 active keys. The response carries Retry-After: 60.
© 2026 ANTS Platform, Inc.Docs v1.0 · Last updated June 2026