AIGateway API usage
For AI Agents: the Markdown version of this page is at https://ankole.agentbull.com/en-US/docs/aigateway-api-usage/index.md. The documentation index is at https://ankole.agentbull.com/en-US/llms.txt.
AIGateway serves both internal Agent turns and external applications, enterprise systems, and HTTP clients over one REST and streaming surface. Complementing the AIGateway architecture reference, this guide covers authentication, call modes, and practical curl examples.
AIGateway calls are Principal-scoped and require an Agent or OIDC Human bearer token. The Responses API accepts OpenResponses-shaped requests and returns JSON or an event stream; media and file endpoints use their own schemas and content types. Upstream provider credentials stay inside the control plane.
Authentication
Every request under /api/v1/ai-gateway requires a bearer token in the Authorization header:
curl https://ankole.example.com/api/v1/ai-gateway/responses \
-H "Authorization: Bearer $AIGATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "model": "primary", "input": "Hello" }'
AIGateway accepts two token kinds:
- Agent token — scoped to a specific Agent’s model bindings; use this when an integration calls AIGateway on behalf of that Agent.
- OIDC Human token — issued to an active Human by an OIDC Client granted
ai_gateway.write; requests resolve against that Client’s model aliases, withsubject_type = "oidc_human".
To obtain an OIDC Human token, create an OIDC Client in the Console with the ai_gateway.write scope, configure its allowed groups and model aliases, and sign in with Authorization Code and PKCE (request offline_access to receive a rotating Refresh Token for long-lived sessions). The Human must belong to an allowed group and may select only from that Client’s model aliases; raw provider_id/model selectors are rejected.
See Principal and AuthZ for how tokens resolve to Principals.
Stateless responses (HTTP and SSE)
A stateless call follows a single request/response cycle—send the full input and receive the complete response body:
curl https://ankole.example.com/api/v1/ai-gateway/responses \
-H "Authorization: Bearer $AIGATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "model": "primary", "input": "Summarize this thread.", "store": false }'
To stream tokens as they arrive, add "stream": true so the endpoint switches to Server-Sent Events:
curl -N https://ankole.example.com/api/v1/ai-gateway/responses \
-H "Authorization: Bearer $AIGATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "model": "primary", "input": "Draft a release note.", "stream": true }'
Stateless HTTP and SSE reject previous_response_id, conversation, and any store value other than false. You may omit store or set store: false; use the /responses WebSocket endpoint for multi-turn continuation.
Other endpoints
| Endpoint | Purpose |
|---|---|
GET /models |
List the currently available models |
POST /embeddings |
Create embeddings |
POST /rerank |
Rerank documents |
POST /web_search |
Search the web |
POST /web_fetch |
Fetch web pages |
POST /decisions |
Answer typed questions with probabilities |
POST /images |
Generate or edit an image |
POST /audio/speech |
Turn text into spoken audio |
POST /audio/transcriptions |
Turn audio into text |
POST /ocr |
Read a PDF or a document image as Markdown |
POST /videos |
Start a video generation, then read the job at GET /videos/:id and the file at GET /videos/:id/content |
POST /audio/music |
Start a music generation, then read the job at GET /audio/music/:id and the file at GET /audio/music/:id/content |
Each endpoint is documented in detail on the AIGateway page and the corresponding User-guide feature page.
Typed decisions
Use POST /decisions when an application needs probabilities rather than generated prose. The decision.default selector resolves the Pod/Site decision profile; an explicit provider_id/model selector can choose a decision model directly.
curl https://ankole.example.com/api/v1/ai-gateway/decisions \
-H "Authorization: Bearer $AIGATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "decision.default",
"state": {"ticket": "I was charged twice."},
"questions": {
"urgent": {"type": "noul", "instructions": "Does this need a reply today?"},
"team": {
"type": "choice",
"instructions": "Which team owns this ticket?",
"criteria": {"billing": "Payments and refunds", "support": "Product questions"}
}
}
}'
A score question takes 2 to 10 ordered labels in criteria. The response contains model, answers, and token usage; every answer includes probabilities. TypeSafe, Azure Foundry, OpenRouter, OpenAI, Google AI Studio, and Cloudflare decision models use the same public request shape. Upstream image support differs: SystemOne accepts PNG/JPEG, Microsoft-Decision-1 is text-only, and OpenAI and Google AI Studio also accept WebP. An OpenAI refusal or Google safety block returns 422 upstream_decision_refusal without partial answers. When no decision profile is configured, the caller’s light language model answers with uncalibrated probabilities.
What this guide is not
This page focuses on client usage rather than protocol internals—read AIGateway for the complete route table, stateful WebSocket lifecycle, and error envelope. Note also that Ankole does not ship a proprietary client SDK; callers use standard HTTP or OpenResponses-compatible clients directly against the REST API.
Next steps
- For the full AIGateway surface, read AIGateway.
- For Provider resolution and request preparation, read Provider Runtime.
- For the Console API reference, read Console API reference.