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 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, with subject_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