API reference

The OpenAI-compatible surface your applications call: chat, embeddings, images, audio, vector stores. Authenticated with an API key.

Generated from the OpenAPI specification. A continuous-integration check enforces the specification against the running router in both directions — an undocumented route fails the build, and so does a documented route that no longer exists. This reference therefore cannot silently drift from the implementation.

100 operations across 32 groups.

A note on free-form responses

Some operations document their body as a free-form object (additionalProperties: true). That is deliberate, not an omission, and it means one of two things:

• Provider passthrough. The gateway forwards the upstream provider’s payload verbatim. Restating the provider’s schema here would create a second source of truth that drifts from theirs. Use the provider’s own documentation for those shapes.
• Application-defined JSON. The value comes from a JSONB column the application does not structurally constrain.

Where a shape is pinned, this reference names the schema and lists its fields. So ChatCompletionRequest — model*: string, … is a contract; “free-form object” is an honest admission that it is not.

Contents

• model — 2 operations
• guardrail — 4 operations
• assistant — 5 operations
• audio — 2 operations
• batch — 1 operations
• batche — 4 operations
• chat — 2 operations
• completion — 2 operations
• embedding — 2 operations
• engine — 1 operations
• eval_job — 1 operations
• file — 5 operations
• fine_tuning — 4 operations
• image — 2 operations
• insight — 1 operations
• knowledge — 6 operations
• knowledge_base — 2 operations
• message — 2 operations
• moderation — 2 operations
• openai — 1 operations
• rerank — 1 operations
• response — 5 operations
• score — 1 operations
• search — 1 operations
• session — 1 operations
• thread — 9 operations
• trace — 2 operations
• usage — 2 operations
• v1beta — 2 operations
• vector_store — 19 operations
• web — 5 operations
• web_fetch — 1 operations

model

GET /v1/models

List available models

Returns the set of models this key may call. The data array is filtered to the caller’s per-key allowlist — keys with a non-empty models[] restriction see only the intersection of the registry and their allowlist. This is part of the 404-on-unauthorized-model security property: enumeration doesn’t leak the existence of models outside the caller’s allowlist. See GET /v1/models/{model} for the singular-retrieve sibling.

GET /v1/models/{model}

Retrieve a model by name

Returns the canonical model object for the given name. Part of the 404-on-unauthorized-model security property — see the 404 response for details.

guardrail

GET /v1/guardrails/available

List configured guardrails

POST /v1/guardrails/check

Run guardrails over a text input

Request body (required): text*: string

POST /v1/guardrails/redact

Redact sensitive tokens from text

Request body (required): text*: string, entity_types: array

POST /v1/guardrails/rehydrate

Rehydrate previously redacted text

Request body (required): text*: string

assistant

GET /v1/assistants

List assistants

POST /v1/assistants

Create an assistant

Request body (required): free-form object — see note

DELETE /v1/assistants/{id}

Delete an assistant

GET /v1/assistants/{id}

Retrieve an assistant

POST /v1/assistants/{id}

Update an assistant

Request body (required): free-form object — see note

audio

POST /v1/audio/speech

Synthesize speech from text

Generates speech audio from a text input. The response Content-Type depends on the requested format (audio/mpeg by default).

Request body (required): model: string, input: string, voice: string, response_format: string, speed: number

POST /v1/audio/transcriptions

Transcribe audio to text

Multipart form upload — file carries the audio bytes.

batch

POST /v1/batch/udf

UDF batch dispatch (Trino plugin only — internal)

Internal endpoint called by the AOCore Trino UDF plugin to dispatch batched UDF invocations through the gateway pipeline (guardrails + budget + audit + provenance).

NOT intended for direct external use. The Java AOCoreGatewayClient (E-03) batches up to 64 UDF invocations per POST; the Go handler fans them out concurrently (max 32 goroutines) through ProxyService and returns ordered results.

Authentication: mTLS client cert (Trino worker) + X-Trino-User header carrying the Trino BasicPrincipal name in ’tenantId:principalId’ format (from B-02’s HeaderAuthenticator plugin).

Cross-tenant requests are rejected with 403 TENANT_MISMATCH: the resolved API key’s tenant must match the X-Trino-User tenant prefix.

Per-item errors do NOT fail the entire batch — they surface as non-empty Error strings in UDFBatchResult items. The Java UDF maps per-item errors to SQL NULL for that row; the query continues with partial results (BigQuery / Snowflake per-item-isolation pattern).

Registered in go/internal/api/v1/register.go (E-01). The chi.Walk vs spec drift test in go/internal/spec/inventory_test.go enforces that this entry matches the registered route bidirectionally.

Request body (required): UDFBatchRequest — items*: array

batche

GET /v1/batches

List batches

POST /v1/batches

Create a batch

Request body (required): free-form object — see note

GET /v1/batches/{id}

Retrieve a batch

POST /v1/batches/{id}/cancel

Cancel a batch

chat

POST /chat/completions

Alias for POST /v1/chat/completions (non-prefixed)

Identical contract to POST /v1/chat/completions; documented separately so the inventory drift gate sees both.

Request body (required): ChatCompletionRequest — model: string, messages: array, temperature: number|null, top_p: number|null, n: integer|null, stream: boolean, stop: any, max_tokens: integer|null … +13

POST /v1/chat/completions

Create a chat completion

OpenAI-compatible chat completion endpoint. Routes to the upstream provider configured for the requested model. Supports streaming via the stream: true request field — the response Content-Type becomes text/event-stream and each event carries a ChatCompletionChunk JSON payload terminated by data: [DONE]\n\n.

Request body (required): ChatCompletionRequest — model: string, messages: array, temperature: number|null, top_p: number|null, n: integer|null, stream: boolean, stop: any, max_tokens: integer|null … +13

completion

POST /completions

Alias for POST /v1/completions (non-prefixed)

Request body (required): CompletionRequest — model: string, prompt: string, max_tokens: integer|null, temperature: number|null, stream: boolean

POST /v1/completions

Create a legacy completion

Legacy OpenAI completions endpoint. Wraps the prompt as a single user-role chat message and routes to the same proxy as /v1/chat/completions. Provided for backwards compatibility with older SDKs.

Request body (required): CompletionRequest — model: string, prompt: string, max_tokens: integer|null, temperature: number|null, stream: boolean

embedding

POST /embeddings

Alias for POST /v1/embeddings (non-prefixed)

Request body (required): EmbeddingRequest — model: string, input: any, encoding_format: string, dimensions: integer|null, user: string

POST /v1/embeddings

Create embeddings

Request body (required): EmbeddingRequest — model: string, input: any, encoding_format: string, dimensions: integer|null, user: string

engine

POST /engines/{model}/chat/completions

Legacy engine-style chat completion alias

Legacy OpenAI engine path. Same handler as the Azure deployment alias.

Request body (required): ChatCompletionRequest — model: string, messages: array, temperature: number|null, top_p: number|null, n: integer|null, stream: boolean, stop: any, max_tokens: integer|null … +13

eval_job

POST /v1/eval_job/{id}/pull

Lease a batch of eval test-case items (worker-facing)

The worker-facing pull endpoint for the eval execution split (Objective 5 TRD 5-03). An external eval worker polls this to LEASE a batch of NOT-yet-leased (or lease-expired) test-case items, runs each prompt through /v1/chat/completions under the PINNED reproducibility conditions echoed in the response (seed + temperature, SC2), then posts /v1/scores (Job 4) to ACK them. Lease semantics are crash-safe: an un-ACK’d item re-surfaces after the visibility timeout. Auth is the same Bearer API key /v1/chat/completions uses — a missing key is 401.

Request body (required): worker_id*: string, batch_size: integer

file

GET /v1/files

List files

POST /v1/files

Upload a file

DELETE /v1/files/{id}

Delete a file

GET /v1/files/{id}

Retrieve a file’s metadata

GET /v1/files/{id}/content

Retrieve a file’s content

fine_tuning

GET /v1/fine_tuning/jobs

List fine-tuning jobs

POST /v1/fine_tuning/jobs

Create a fine-tuning job

Request body (required): free-form object — see note

GET /v1/fine_tuning/jobs/{id}

Retrieve a fine-tuning job

POST /v1/fine_tuning/jobs/{id}/cancel

Cancel a fine-tuning job

image

POST /v1/images/edits

Edit an existing image with a prompt

The handler currently accepts JSON (not multipart) and forwards to the same image-generation provider with model defaulted to dall-e-2. See go/internal/api/v1/images.go::Edits (line 52).

Request body (required): ImageGenerationRequest — model: string, prompt*: string, n: integer, size: string, quality: string, style: string, response_format: string, user: string

POST /v1/images/generations

Generate images from a text prompt

Request body (required): ImageGenerationRequest — model: string, prompt*: string, n: integer, size: string, quality: string, style: string, response_format: string, user: string

insight

POST /v1/insights/message

Send a single message to the insights chat

Request body (required): free-form object — see note

knowledge

POST /v1/knowledge/async

Trigger an async knowledge-base ingest job

Request body (required): free-form object — see note

POST /v1/knowledge/batch_upload

Upload multiple documents

POST /v1/knowledge/extract

Extract plain text from document bytes (no vector store)

Runs the OCR dispatcher over uploaded bytes and returns the extracted text WITHOUT creating or touching a vector store. Binary content (PDF/image/office/archive) is routed through the gemma4-first dispatcher; text content is returned verbatim.

Request body (required): free-form object — see note

GET /v1/knowledge/jobs

List knowledge-base ingest jobs

GET /v1/knowledge/jobs/{id}

Retrieve a knowledge-base ingest job

POST /v1/knowledge/upload

Upload a document to the knowledge base

knowledge_base

DELETE /v1/knowledge_base/jobs/{id}

Cancel a knowledge-base ingest job

GET /v1/knowledge_base/ocr_providers

List configured OCR providers

message

POST /v1/messages

Create an Anthropic message

Native Anthropic Messages API proxy. The handler at go/internal/api/anthropic/messages.go::Create accepts Anthropic’s wire shape directly — messages array with role+content, plus a top-level system string and max_tokens (required). It is intentionally NOT coerced to OpenAI’s chat-completions shape.

Request body (required): AnthropicMessagesRequest — model: string, max_tokens: integer, messages*: array, system: string, stream: boolean

POST /v1/messages/count_tokens

Count tokens for a planned Anthropic Messages call

Forwards the request body verbatim to Anthropic’s /v1/messages/count_tokens endpoint. Source: go/internal/api/anthropic/messages.go::CountTokens (line 88).

Request body (required): free-form object — see note

moderation

POST /moderations

Alias for POST /v1/moderations (non-prefixed)

Request body (required): ModerationRequest — input*: any, model: string

POST /v1/moderations

Classify content against the moderation taxonomy

Request body (required): ModerationRequest — input*: any, model: string

openai

POST /openai/deployments/{model}/chat/completions

Azure-OpenAI-style deployment alias for chat completions

Azure-OpenAI-compatible path shape — the {model} path parameter is treated as the deployment/model name. Source: go/internal/api/v1/register.go (line 170) routes this to ChatCompletionsHandler.DeploymentCreate.

Request body (required): ChatCompletionRequest — model: string, messages: array, temperature: number|null, top_p: number|null, n: integer|null, stream: boolean, stop: any, max_tokens: integer|null … +13

rerank

POST /v1/rerank

Rerank documents by relevance to a query

Request body (required): RerankRequest — model: string, query: string, documents*: array, top_n: integer

response

GET /v1/responses

List responses

POST /v1/responses

Create a response

Request body (required): free-form object — see note

DELETE /v1/responses/{id}

Delete a response

GET /v1/responses/{id}

Retrieve a response

POST /v1/responses/{id}/cancel

Cancel a response

score

POST /v1/scores

Ingest a per-test-case eval score (worker-facing)

The worker-facing score-ingest endpoint that CLOSES the eval-run loop (Objective 5 TRD 5-04). After running a leased test-case prompt through /v1/chat/completions, the worker POSTs the per-case score here. On the DECIDING score (when every expected test case has been scored) the aggregator computes the deterministic weighted-mean aggregate (sorted by test_case_id, SC2), derives the pass/fail verdict against the suite’s pass_threshold, and writes the eval_results verdict row — the row the eval gate reads — atomically in one transaction. Each score is also fanned out as an OTel GenAI gen_ai.evaluation.result event. The verdict tenant is bound from the eval_jobs row (NOT the request); a cross-tenant eval_job_id returns 404 (no existence oracle). Ingest is idempotent on (eval_job_id, test_case_id, scored_by). Auth is the same Bearer API key /v1/chat/completions uses — a missing key is 401.

Request body (required): eval_job_id: string, test_case_id: string, score: number, label: string, explanation: string, gen_ai_response_id: string, scored_by: string

search

POST /v1/search

Run a web search

Request body (required): query*: string, num_results: integer

session

GET /v1/sessions

List request-id session rollups for the calling tenant

Lists the calling tenant’s sessions — request_id rollups of the chain events each request produced, grouped from the audit_logs spine and ordered by start time DESC. Same tenant binding (attested principal only, never a wire field) and same auth as GET /v1/traces. limit/offset are clamped (not rejected): limit defaults to 100 and is capped at 500; offset floors at 0.

thread

POST /v1/threads

Create a thread

Request body (required): free-form object — see note

DELETE /v1/threads/{id}

Delete a thread

GET /v1/threads/{id}

Retrieve a thread

POST /v1/threads/{id}

Update a thread

Request body (required): free-form object — see note

GET /v1/threads/{id}/messages

List messages on a thread

POST /v1/threads/{id}/messages

Create a message on a thread

Request body (required): free-form object — see note

GET /v1/threads/{id}/runs

List runs on a thread

POST /v1/threads/{id}/runs

Run an assistant on a thread

Request body (required): free-form object — see note

GET /v1/threads/{thread_id}/runs/{run_id}

Retrieve a run

trace

GET /v1/traces

List trace events for the calling tenant

Lists the calling tenant’s trace events — a PURE PROJECTION over the audit_logs provenance spine filtered to gen_ai.* / udf.* / eval.promotion.decided chain entries, ordered by sequence_number DESC. The tenant is bound from the attested principal ONLY (the org UUID the provenance spine stamps on audit_logs.tenant_id); it is NEVER read from a wire field, so a caller can only ever see their own tenant’s events. Auth is the same Bearer API key /v1/chat/completions uses — a missing key is 401. limit/offset are clamped (not rejected): limit defaults to 100 and is capped at 500; offset floors at 0.

GET /v1/traces/{id}

Get one trace event by id (tenant-scoped)

Returns one trace event by id, scoped to the calling tenant. The read is filtered by WHERE id = $1 AND tenant_id = $caller: an id that exists for ANOTHER tenant yields NO row and returns 404 — NEVER 403. A 403 would confirm the id exists and leak existence across tenants; the 404 (the SAME response as a genuinely missing id) blocks that cross-tenant existence oracle. The handler does NOT branch on “exists for another tenant” — the SQL WHERE clause, not the app layer, enforces isolation. Auth is the same Bearer API key /v1/chat/completions uses — a missing key is 401.

usage

GET /v1/usage

Aggregate usage for the calling key

Returns lifetime totals for the API key making the call.

GET /v1/usage/summary

Spend summary for the calling key

Returns a 30-day spend summary scoped to the caller. API-key callers receive ONLY their own key’s spend (the response is filtered via WHERE api_key = the_caller_token_hash). Master-key callers (IsMasterKey == true) receive the global gateway spend for admin observability — preserved for the admin dashboard. Pre-TRD-06 the handler unconditionally returned global gateway spend, leaking other customers’ totals to every API-key caller; TRD 06 fixed the handler to branch on the auth principal.

v1beta

POST /v1beta/models/{model}:generateContent

Google AI generateContent (native shape)

Native Google AI surface — request body is a contents array of parts, not OpenAI’s messages. Currently the response is the gateway’s internal ChatCompletionResponse shape rather than Google’s native shape (acknowledged in the handler — open issue).

Request body (required): GoogleGenerateContentRequest — contents*: array

POST /v1beta/models/{model}:streamGenerateContent

Google AI streamGenerateContent (SSE)

Request body (required): GoogleGenerateContentRequest — contents*: array

vector_store

GET /v1/vector_stores

List vector stores

POST /v1/vector_stores

Create a vector store

Request body (required): free-form object — see note

DELETE /v1/vector_stores/{id}

Delete a vector store

GET /v1/vector_stores/{id}

Retrieve a vector store

PATCH /v1/vector_stores/{id}

Update a vector store

Request body (required): free-form object — see note

GET /v1/vector_stores/{id}/documents

List documents in a vector store

POST /v1/vector_stores/{id}/documents

Add documents to a vector store

Request body (required): free-form object — see note

DELETE /v1/vector_stores/{id}/documents/{docID}

Delete a document

GET /v1/vector_stores/{id}/documents/{docID}

Retrieve a document

PATCH /v1/vector_stores/{id}/documents/{docID}

Update a document’s stored content type

Request body (required): free-form object — see note

POST /v1/vector_stores/{id}/documents/{docID}/reprocess

Reprocess a document

GET /v1/vector_stores/{id}/graph/communities

List communities in the knowledge graph

GET /v1/vector_stores/{id}/graph/communities/{cid}

Retrieve a community

GET /v1/vector_stores/{id}/graph/entities

List entities in a vector store’s knowledge graph

POST /v1/vector_stores/{id}/graph/global-query

Run a global query against the knowledge graph

Request body (required): free-form object — see note

POST /v1/vector_stores/{id}/graph/query

Run a query against the knowledge graph

Request body (required): free-form object — see note

GET /v1/vector_stores/{id}/graph/relationships

List relationships in a vector store’s knowledge graph

GET /v1/vector_stores/{id}/graph/stats

Summary statistics for the knowledge graph

POST /v1/vector_stores/{id}/search

Search a vector store

Request body (required): free-form object — see note

web

POST /v1/web/crawl

Crawl a starting URL

Request body (required): free-form object — see note

POST /v1/web/crawl/batch

Crawl multiple URLs in a batch

Request body (required): free-form object — see note

POST /v1/web/fetch

Fetch a URL’s content

Request body (required): free-form object — see note

POST /v1/web/ingest

Ingest a crawled URL into a knowledge store

Request body (required): free-form object — see note

POST /v1/web/search

Web search

Request body (required): free-form object — see note

web_fetch

POST /v1/web_fetch

Fetch and extract content from a URL

Request body (required): free-form object — see note