Skip to content
Ankole

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 is both the worker boundary and a REST API for external applications, enterprise systems, and SDKs. This page covers its endpoints, authentication, call modes, and worked examples. It complements the AIGateway concept page with hands-on usage.

The decisive property, stated up front: the AIGateway API is OpenResponses-compatible and Principal-scoped. A caller presents a bearer token (agent or admin), sends an OpenResponses-shaped request, and receives a JSON response or a stream. The caller never sees a provider credential — the control plane owns those.

Authentication

Every call under /api/v1/ai-gateway requires a bearer token:

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" }'

Two token kinds are accepted:

  • Agent token — scoped to one agent’s model bindings. Use this when an integration acts on behalf of a specific agent.
  • Admin token — scoped to all providers. Use this for operator-side scripts and the Console.

See Principal and AuthZ for how tokens resolve to Principals.

Stateless responses (HTTP and SSE)

A stateless call is one request, one response. Send the full input; get the complete body back:

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 }'

For streaming, add "stream": true and the same 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 the stateful fields (previous_response_id, conversation, store). Use the WebSocket path for 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

Each is documented in the AIGateway concept page and the relevant User-guide feature page.

What this guide is not

It is not the AIGateway concept page. Read AIGateway for the full route table, stateful lifecycle, and error envelope. It is also not an SDK. Ankole does not ship a client SDK; callers use standard HTTP clients against the REST API.

Next steps