Canonical API contract
LLM Proxy HTTP API
The sole canonical wire contract for llm-proxy-owned proxy, browser configuration, and management endpoints. Each configured text model owns one explicit upstream wire contract and execution lifecycle. OpenAI Gemini 3.5 Transcribe accepts file dictation through synchronous Interactions. The filename extension selects a supported audio MIME type. An unsupported extension returns HTTP 400 with invalid_audio_input. The upload byte limit applies. Gemini enforces its one-hour audio duration limit. Gemini 3.6 Flash accepts reasoning efforts minimal, low, medium, and high. Gemini 3.7 Flash accepts low, medium, and high. An omitted effort leaves the provider default in effect. Both routes accept text, image, and audio input with a maximum of 65,536 output tokens. Responses and Gemini 3.x Interactions use stored pollable resources. OpenAI-compatible Chat Completions and Anthropic Messages complete synchronously. Generation responses remain synchronous. A hosted duplicate can return an active receipt. The proxy does not expose provider resource identifiers. For customer-owned credentials, OpenAI resource ids remain in memory only. The adapter does not cancel or delete stored Responses. The OpenAI account retention policy applies. For hosted work, the journal keeps private provider resource identifiers. For customer-owned credentials, background Gemini interaction ids are request-local. The adapter cancels active resources and deletes every stored interaction on exit. Each Gemini Interactions route rejects assistant history before provider dispatch. An incomplete Gemini response returns a provider error without replay. TAuth-owned endpoints are outside this contract. Contributors must update this document in the same change as any owned handler or bundled-client wire change.
OpenAPI YAML
The complete canonical manifest is shown below. The download action publishes these exact source bytes.
openapi: 3.1.0
info:
title: LLM Proxy HTTP API
version: 1.0.0
description: >-
The sole canonical wire contract for llm-proxy-owned proxy, browser
configuration, and management endpoints. Each configured text model owns
one explicit upstream wire contract and execution lifecycle. OpenAI
Gemini 3.5 Transcribe accepts file dictation through synchronous Interactions.
The filename extension selects a supported audio MIME type. An unsupported
extension returns HTTP 400 with invalid_audio_input. The upload byte limit
applies. Gemini enforces its one-hour audio duration limit.
Gemini 3.6 Flash accepts reasoning efforts minimal, low, medium, and high.
Gemini 3.7 Flash accepts low, medium, and high. An omitted effort leaves
the provider default in effect. Both routes accept text, image, and audio
input with a maximum of 65,536 output tokens.
Responses and Gemini 3.x Interactions use stored pollable resources.
OpenAI-compatible Chat Completions and Anthropic Messages complete
synchronously. Generation responses remain synchronous. A hosted duplicate
can return an active receipt. The proxy does not expose provider resource identifiers.
For customer-owned credentials, OpenAI resource ids remain in memory only.
The adapter does not cancel or delete stored Responses. The OpenAI account retention policy applies.
For hosted work, the journal keeps private provider resource identifiers.
For customer-owned credentials, background Gemini interaction ids are request-local.
The adapter cancels active resources and deletes every stored interaction on exit.
Each Gemini Interactions route rejects
assistant history before provider dispatch. An incomplete Gemini response
returns a provider error without replay.
TAuth-owned endpoints are outside this contract.
Contributors must update this document in the same change as any owned
handler or bundled-client wire change.
servers:
- url: https://llm-proxy-api.mprlab.com
description: Production API origin
x-llm-proxy-protocol-methods:
- OPTIONS
tags:
- name: Client protocols
description: Tenant bearer interfaces for OpenAI clients and OpenCode.
- name: Proxy
description: Tenant-key-authenticated text and dictation operations.
- name: Configuration
description: Public browser runtime configuration owned by llm-proxy.
- name: Capabilities
description: Public provider, model, capability, and request-limit resources.
- name: Management
description: TAuth-session-authenticated tenant management operations.
paths:
/api/payments/paddle/events:
post:
operationId: receivePaddlePaymentEvent
summary: Retain a verified Paddle event
description: >-
Verifies the signature against raw bytes before JSON parsing. The configured
secret binds the event to one processor account and environment. A successful
response confirms durable inbox storage, not a funding credit. Identical
events have one inbox record. Changed content for the same event returns 409.
This receiver currently has controlled development integration only.
tags: [Payments]
security:
- PaddleSignature: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [event_id, event_type, occurred_at, data]
properties:
event_id: {type: string, pattern: '^evt_[a-z0-9]{26}$'}
event_type: {type: string, maxLength: 128, pattern: '^[a-z_]+\.[a-z_]+$'}
occurred_at: {type: string, format: date-time}
data:
type: object
required: [id]
properties:
id: {type: string, pattern: '^[a-z]{3}_[a-z0-9]{26}$'}
responses:
'200':
description: The verified event is in the durable inbox.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [event_id, status]
properties:
event_id: {type: string, pattern: '^evt_[a-z0-9]{26}$'}
status: {type: string, enum: [accepted]}
'400':
$ref: '#/components/responses/PaymentEventError'
'401':
$ref: '#/components/responses/PaymentEventError'
'409':
$ref: '#/components/responses/PaymentEventError'
'413':
$ref: '#/components/responses/PaymentEventError'
'415':
$ref: '#/components/responses/PaymentEventError'
'503':
$ref: '#/components/responses/PaymentEventError'
/.well-known/oauth-protected-resource/mcp:
get:
operationId: getMCPResourceMetadata
summary: Read OAuth metadata for the MCP resource.
security: []
responses:
'200':
description: The metadata identifies the TAuth issuer and required scope.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [resource, authorization_servers, scopes_supported, bearer_methods_supported]
properties:
resource:
type: string
format: uri
authorization_servers:
type: array
items:
type: string
format: uri
scopes_supported:
type: array
items:
type: string
const: llm-proxy:use
bearer_methods_supported:
type: array
items:
type: string
const: header
/mcp:
post:
operationId: postMCPRequest
summary: Use an owned tenant through MCP.
description: >-
Stateless Streamable HTTP supports 2026-07-28, 2025-11-25, 2025-06-18, and 2025-03-26 with JSON responses.
The 2025 revisions use initialize and notifications/initialized.
The 2026 revision uses server/discover and per-request protocol metadata.
TAuth issues tokens for the API origin with the llm-proxy:use scope.
Each request requires a bearer token.
The body must arrive within server.request_timeout_seconds and cannot exceed 8 MiB.
An upload timeout returns HTTP 408 before tool execution.
Generation uses a separate request_timeout_seconds budget after the upload.
The llm_proxy.list_tenants tool provides all owned tenant summaries.
The llm_proxy.generate_text tool requires tenant_id and messages.
Hosted text also requires idempotency_key and returns the original execution identifier for identical requests.
A concurrent hosted request returns state dispatched without generated text.
The llm-proxy://tenants/{tenant_id}/routes resource template provides configured text routes.
Tool execution failures use isError with a sanitized code.
Resource errors and protocol errors use JSON-RPC errors with the protocol HTTP status.
security:
- MCPAccessToken: []
parameters:
- name: MCP-Protocol-Version
in: header
description: >-
Send the negotiated version after initialization. The initial handshake can omit this header.
An absent header selects the protocol-defined 2025-03-26 default. Repeated headers are rejected.
schema:
type: string
enum: ['2026-07-28', '2025-11-25', '2025-06-18', '2025-03-26']
- name: Mcp-Method
in: header
schema:
type: string
description: Required for 2026-07-28. The value must equal the JSON-RPC method.
- name: Mcp-Name
in: header
schema:
type: string
description: Supply the tool name for tools/call or the resource URI for resources/read.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MCPRequest'
responses:
'200':
description: An MCP result or application error.
content:
application/json:
schema:
$ref: '#/components/schemas/MCPResponse'
'202':
description: The handshake-family notification was accepted. The response has no body.
'400':
description: The protocol version, resource URI, or request is invalid.
'401':
description: A valid TAuth OAuth access token is required.
headers:
WWW-Authenticate:
schema:
type: string
'403':
description: The required scope is absent or the origin is prohibited.
'404':
description: The MCP method is unknown.
'406':
description: The Accept header does not permit the required response type.
'408':
description: The request body did not arrive within the server timeout or the request was canceled.
'413':
description: The request exceeds the configured message limit.
'415':
description: The request content type is unsupported.
'500':
description: The requested resource is unavailable because of a server error.
/healthz:
get:
operationId: getHealth
summary: Read local datastore readiness without authentication or provider work.
security: []
responses:
'200':
description: The local datastore is available.
headers:
Cache-Control:
schema:
type: string
const: no-store
content:
application/json:
schema:
type: object
required: [status]
additionalProperties: false
properties:
status:
const: ok
'503':
description: The local datastore is unavailable.
headers:
Cache-Control:
schema:
type: string
const: no-store
content:
application/json:
schema:
type: object
required: [status]
additionalProperties: false
properties:
status:
const: unavailable
/v1/chat/completions:
post:
operationId: createChatCompletion
tags:
- Client protocols
description: >-
Authenticate with a tenant bearer key. Select one exact provider/model route. Reject unsupported fields
before provider dispatch.
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/RequestTimeout'
- $ref: '#/components/parameters/HostedCompletionIdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIChatRequest'
responses:
'202':
$ref: '#/components/responses/StructuredRequestPending'
'402':
$ref: '#/components/responses/HostedClientFailure'
'403':
$ref: '#/components/responses/HostedClientFailure'
'409':
$ref: '#/components/responses/HostedClientFailure'
'410':
$ref: '#/components/responses/HostedClientFailure'
'200':
description: Completed result.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIChatCompletion'
text/event-stream:
schema:
type: string
x-event-contract: OpenAIChatChunk
x-event-sequence:
- assistant-role
- content-or-tool-calls
- finish
- optional-usage
- '[DONE]'
'400':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/OptionalResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'401':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'405':
description: The HTTP method is unsupported.
headers:
Allow:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'413':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'415':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'429':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
Retry-After:
$ref: '#/components/headers/SafeRetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'499':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'502':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'503':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'504':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
/v1/responses:
post:
operationId: createResponse
tags:
- Client protocols
description: >-
Authenticate with a tenant bearer key. Select one exact provider/model route. Reject unsupported fields
before provider dispatch.
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/RequestTimeout'
- $ref: '#/components/parameters/HostedCompletionIdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIResponsesRequest'
responses:
'202':
$ref: '#/components/responses/StructuredRequestPending'
'402':
$ref: '#/components/responses/HostedClientFailure'
'403':
$ref: '#/components/responses/HostedClientFailure'
'409':
$ref: '#/components/responses/HostedClientFailure'
'410':
$ref: '#/components/responses/HostedClientFailure'
'200':
description: Completed result.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIResponse'
text/event-stream:
schema:
type: string
x-event-contract: OpenAIResponseEvent
x-event-sequence:
- response.created
- response.in_progress
- output-item-events
- response.completed
'400':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/OptionalResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'401':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'405':
description: The HTTP method is unsupported.
headers:
Allow:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'413':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'415':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'429':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
Retry-After:
$ref: '#/components/headers/SafeRetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'499':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'502':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'503':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'504':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
/v1/audio/transcriptions:
post:
operationId: createTranscription
tags:
- Client protocols
description: >-
Authenticate with a tenant bearer key. Select one exact provider/model route. Reject unsupported fields
before provider dispatch. Hosted requests require Idempotency-Key.
Identical audio and format use the same request identity across both transcription interfaces.
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/RequestTimeout'
- $ref: '#/components/parameters/HostedCompletionIdempotencyKey'
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/OpenAITranscriptionRequest'
responses:
'202':
$ref: '#/components/responses/StructuredRequestPending'
'402':
$ref: '#/components/responses/HostedClientFailure'
'403':
$ref: '#/components/responses/HostedClientFailure'
'409':
$ref: '#/components/responses/HostedClientFailure'
'410':
$ref: '#/components/responses/HostedClientFailure'
'200':
description: Completed result.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/DictationResponse'
'400':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/OptionalResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'401':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'405':
description: The HTTP method is unsupported.
headers:
Allow:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'413':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'415':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'429':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
Retry-After:
$ref: '#/components/headers/SafeRetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'499':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'502':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'503':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'504':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
/v1/models:
get:
operationId: listClientModels
tags:
- Client protocols
description: >-
Return only catalog routes available to the authenticated tenant. The created value records catalog
entry creation from repository history.
security:
- TenantBearerKey: []
responses:
'200':
description: Completed result.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIModels'
'400':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'401':
description: Request failure.
headers:
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
X-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'405':
description: The HTTP method is unsupported.
headers:
Allow:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
/:
get:
operationId: getText
summary: Generate text from a query prompt
tags:
- Proxy
security:
- TenantClientKey: []
x-llm-proxy-allow-undeclared-query: true
parameters:
- $ref: '#/components/parameters/TenantClientKey'
- $ref: '#/components/parameters/Prompt'
- $ref: '#/components/parameters/Provider'
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/WebSearch'
- $ref: '#/components/parameters/SystemPrompt'
- $ref: '#/components/parameters/MaxTokens'
- $ref: '#/components/parameters/ReasoningEffort'
- $ref: '#/components/parameters/ResponseFormat'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/RequestTimeout'
- $ref: '#/components/parameters/HostedCompletionIdempotencyKey'
responses:
'202':
$ref: '#/components/responses/StructuredRequestPending'
'410':
$ref: '#/components/responses/HostedResultExpired'
'200':
$ref: '#/components/responses/TextSuccess'
'400':
$ref: '#/components/responses/ProxyBadRequest'
'402':
$ref: '#/components/responses/HostedFundsFailure'
'403':
$ref: '#/components/responses/ProxyForbidden'
'409':
$ref: '#/components/responses/V2Conflict'
'429':
$ref: '#/components/responses/ProxyRateLimited'
'499':
$ref: '#/components/responses/CallerClosed'
'502':
$ref: '#/components/responses/ProxyBadGateway'
'503':
$ref: '#/components/responses/ProxyUnavailable'
'504':
$ref: '#/components/responses/ProxyTimeout'
post:
operationId: postText
summary: Generate text from a prompt or messages JSON body
tags:
- Proxy
security:
- TenantClientKey: []
x-llm-proxy-allow-undeclared-query: true
parameters:
- $ref: '#/components/parameters/TenantClientKey'
- $ref: '#/components/parameters/Provider'
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/ResponseFormat'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/RequestTimeout'
- $ref: '#/components/parameters/HostedCompletionIdempotencyKey'
requestBody:
$ref: '#/components/requestBodies/TextRequest'
responses:
'202':
$ref: '#/components/responses/StructuredRequestPending'
'410':
$ref: '#/components/responses/HostedResultExpired'
'200':
$ref: '#/components/responses/TextSuccess'
'400':
$ref: '#/components/responses/ProxyBadRequest'
'402':
$ref: '#/components/responses/HostedFundsFailure'
'403':
$ref: '#/components/responses/ProxyForbidden'
'409':
$ref: '#/components/responses/V2Conflict'
'413':
$ref: '#/components/responses/ProxyPayloadTooLarge'
'429':
$ref: '#/components/responses/ProxyRateLimited'
'499':
$ref: '#/components/responses/CallerClosed'
'502':
$ref: '#/components/responses/ProxyBadGateway'
'503':
$ref: '#/components/responses/ProxyUnavailable'
'504':
$ref: '#/components/responses/ProxyTimeout'
/v2:
post:
operationId: postV2Messages
summary: Generate text from canonical messages
description: >-
The current messages-only operation. `messages` is required. User
messages may include ordered inline or tenant-asset-backed image and
audio attachments. `model`, `web_search`, `max_tokens`,
`reasoning_effort`, and `structured_output` are optional. A structured
request requires one Idempotency-Key and a supported provider protocol.
The proxy compiles the schema and validates the selected provider subset
before dispatch. It saves its provider result for reconciliation through
`GET /v2/requests`. Omitting `reasoning_effort` selects the tenant or route
default. A supplied value must be non-blank and supported by the resolved
route. The selected provider offering owns media admission and transport
limits. Unsupported media or route capabilities return HTTP 400 before
an upstream call. Each Gemini Interactions route returns HTTP 400 when
any message has the assistant role. The service rejects an encoded request body above 8
MiB before JSON decoding. A smaller catalog-derived body limit applies
when configured. Current Moonshot Kimi image routes preserve attachment
order and exact bytes through Chat Completions Data URL blocks.
tags:
- Proxy
security:
- TenantClientKey: []
x-llm-proxy-allow-undeclared-query: true
parameters:
- $ref: '#/components/parameters/TenantClientKey'
- $ref: '#/components/parameters/Provider'
- $ref: '#/components/parameters/ResponseFormat'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/RequestTimeout'
- $ref: '#/components/parameters/OptionalIdempotencyKey'
requestBody:
$ref: '#/components/requestBodies/V2Request'
responses:
'200':
$ref: '#/components/responses/V2Success'
'202':
$ref: '#/components/responses/V2StructuredRequestPending'
'400':
$ref: '#/components/responses/V2BadRequest'
'402':
$ref: '#/components/responses/HostedFundsFailure'
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/AssetFailure'
'410':
$ref: '#/components/responses/V2Expired'
'409':
$ref: '#/components/responses/V2Conflict'
'413':
$ref: '#/components/responses/ProxyPayloadTooLarge'
'429':
$ref: '#/components/responses/ProxyRateLimited'
'499':
$ref: '#/components/responses/CallerClosed'
'502':
$ref: '#/components/responses/ProxyBadGateway'
'503':
$ref: '#/components/responses/ProxyUnavailable'
'504':
$ref: '#/components/responses/ProxyTimeout'
'500':
$ref: '#/components/responses/V2InternalFailure'
/v2/identity:
get:
operationId: getTenantIdentity
summary: Read the authenticated tenant identity
description: >-
Returns the server-resolved tenant identifier for the supplied tenant
client key. This operation never dispatches provider work. A successful
response sets Cache-Control to no-store.
tags:
- Proxy
security:
- TenantClientKey: []
parameters:
- $ref: '#/components/parameters/TenantClientKey'
responses:
'200':
$ref: '#/components/responses/TenantIdentitySuccess'
'400':
$ref: '#/components/responses/ProxyBadRequest'
'403':
$ref: '#/components/responses/ProxyForbidden'
'499':
$ref: '#/components/responses/CallerClosed'
/v2/requests:
get:
operationId: getV2StructuredRequest
summary: Reconcile a durable text request
description: >-
Returns the terminal JSON result, a safe in-progress receipt, or a safe
terminal failure for the authenticated tenant and exact Idempotency-Key.
This operation never dispatches provider work. Every response sets
Cache-Control to no-store.
tags:
- Proxy
security:
- TenantClientKey: []
x-llm-proxy-allow-undeclared-query: true
parameters:
- $ref: '#/components/parameters/TenantClientKey'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
'200':
$ref: '#/components/responses/StructuredRequestSucceeded'
'202':
$ref: '#/components/responses/StructuredRequestPending'
'400':
$ref: '#/components/responses/StructuredRequestBadRequest'
'404':
$ref: '#/components/responses/StructuredRequestNotFound'
'410':
$ref: '#/components/responses/StructuredRequestExpired'
'409':
$ref: '#/components/responses/StructuredRequestConflict'
'429':
$ref: '#/components/responses/StructuredRequestFailed'
'500':
$ref: '#/components/responses/StructuredRequestStoreFailure'
'502':
$ref: '#/components/responses/StructuredRequestFailed'
'503':
$ref: '#/components/responses/StructuredRequestFailed'
'504':
$ref: '#/components/responses/StructuredRequestFailed'
/model/v1/capabilities:
get:
operationId: getTenantMediaCapabilities
summary: Read tenant-available durable media routes
tags:
- Proxy
security:
- TenantBearerKey: []
responses:
'200':
description: Tenant-available media capability routes.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaCapabilities'
'403':
$ref: '#/components/responses/ProxyForbidden'
/model/v1/operations:
post:
operationId: createTenantMediaOperation
summary: Accept one durable tenant media operation
tags:
- Proxy
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/MediaOperationIdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MediaOperationRequest'
responses:
'200':
$ref: '#/components/responses/MediaOperation'
'202':
$ref: '#/components/responses/MediaOperation'
'400':
$ref: '#/components/responses/MediaOperationFailure'
'402':
$ref: '#/components/responses/MediaOperationFailure'
'403':
$ref: '#/components/responses/MediaOperationForbidden'
'409':
$ref: '#/components/responses/MediaOperationFailure'
'410':
$ref: '#/components/responses/MediaOperationExpired'
'422':
$ref: '#/components/responses/MediaOperationFailure'
'429':
$ref: '#/components/responses/MediaOperationFailure'
'500':
$ref: '#/components/responses/MediaOperationFailure'
'503':
$ref: '#/components/responses/MediaOperationFailure'
/model/v1/operations/{operation_id}:
get:
operationId: getTenantMediaOperation
summary: Read one durable tenant media operation
tags:
- Proxy
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/MediaOperationID'
responses:
'200':
$ref: '#/components/responses/MediaOperation'
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/MediaOperationFailure'
'410':
$ref: '#/components/responses/MediaOperationExpired'
/model/v1/operations/{operation_id}/cancellation:
put:
operationId: cancelTenantMediaOperation
summary: Request cancellation of one durable tenant media operation
tags:
- Proxy
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/MediaOperationID'
responses:
'200':
$ref: '#/components/responses/MediaOperation'
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/MediaOperationFailure'
'422':
$ref: '#/components/responses/MediaOperationFailure'
/model/v1/provider-diagnostics/{provider}:
get:
operationId: getProviderDiagnostics
summary: Read retained tenant operation counts for a provider
description: >-
Counts include only retained media operations owned by the authenticated tenant for the selected provider.
Each accepted operation counts once. Repeated status reads and idempotent retries do not add operations.
Counts include every retained state, including uncertain. Terminal detail expiry removes its count.
These are retained operation counts, not lifetime usage or billing totals.
An assigned connection is required. Connection changes do not transfer another tenant's history.
The request does not contact the provider or return server health, uptime, or global latency.
tags: [Proxy]
security:
- TenantBearerKey: []
parameters:
- name: provider
in: path
required: true
schema:
type: string
pattern: ^[a-z][a-z0-9_-]*$
- $ref: '#/components/parameters/RequestTimeout'
responses:
'200':
$ref: '#/components/responses/ProviderDiagnostics'
'400':
$ref: '#/components/responses/ProxyBadRequest'
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/ProviderDiagnosticsFailure'
'405':
$ref: '#/components/responses/ProviderDiagnosticsFailure'
'500':
$ref: '#/components/responses/ProviderDiagnosticsFailure'
head:
operationId: getProviderDiagnosticsHeaders
summary: Read diagnostic response headers without a response body
tags: [Proxy]
security:
- TenantBearerKey: []
parameters:
- name: provider
in: path
required: true
schema:
type: string
pattern: ^[a-z][a-z0-9_-]*$
- $ref: '#/components/parameters/RequestTimeout'
responses:
'200':
description: Retained tenant operation counts are available.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
default:
description: The diagnostic read failed. The response has no body.
/model/v1/voices:
get:
operationId: listTenantMediaVoices
summary: Discover and list tenant-owned provider voices
description: >-
Hosted access requires an active speech grant and qualified platform credentials.
Hosted ElevenLabs discovery exposes default premade voices.
Hosted Dictator discovery includes only presets and the tenant's retained extracted voices.
Hosted cursors bind the grant revision and credential version.
Metadata reads do not create billable attempts.
tags:
- Proxy
security:
- TenantBearerKey: []
parameters:
- name: provider
in: query
required: true
description: Canonical provider identifier.
schema:
type: string
pattern: ^[a-z][a-z0-9_-]*$
- name: cursor
in: query
schema:
type: string
maxLength: 16384
- name: search
in: query
schema:
type: string
maxLength: 1000
- name: page_size
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: sort
in: query
schema:
type: string
enum: [name, created_at_unix]
- name: sort_direction
in: query
schema:
type: string
enum: [asc, desc]
- name: voice_type
in: query
description: Hosted ElevenLabs access accepts only default. Other values return 400.
schema:
type: string
enum: [personal, community, default, account, non-default, non-community, saved]
- name: category
in: query
description: Hosted ElevenLabs access accepts only premade. Other values return 400.
schema:
type: string
enum: [premade, cloned, generated, professional]
- name: include_total_count
in: query
schema:
type: boolean
responses:
'200':
$ref: '#/components/responses/MediaVoiceCollection'
'400':
$ref: '#/components/responses/MediaVoiceFailure'
'403':
$ref: '#/components/responses/ProxyForbidden'
'500':
$ref: '#/components/responses/MediaVoiceFailure'
'502':
$ref: '#/components/responses/MediaVoiceFailure'
/model/v1/voices/{voice_id}:
get:
operationId: getTenantMediaVoice
summary: Read one tenant-owned voice
tags:
- Proxy
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/MediaVoiceID'
responses:
'200':
$ref: '#/components/responses/MediaVoice'
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/MediaVoiceFailure'
'500':
$ref: '#/components/responses/MediaVoiceFailure'
/model/v1/voices/{voice_id}/previews/{preview}:
get:
operationId: getTenantMediaVoicePreview
summary: Read one account-bound voice preview
tags: [Proxy]
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/MediaVoiceID'
- name: preview
in: path
required: true
schema: {type: integer, minimum: 0}
responses:
'200':
description: Audio preview from the current provider connection.
headers:
Cache-Control:
schema: {type: string, const: no-store}
content:
audio/mpeg:
schema: {type: string, contentEncoding: binary}
audio/wav:
schema: {type: string, contentEncoding: binary}
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/MediaVoiceFailure'
'500':
$ref: '#/components/responses/MediaVoiceFailure'
'502':
$ref: '#/components/responses/MediaVoiceFailure'
/model/v1/provider-resources/{provider}/{kind}:
get:
operationId: getTenantProviderResource
summary: Read assigned provider account metadata or quota
description: Account observations do not add executable model routes. The YAML catalog controls available routes.
tags: [Proxy]
security:
- TenantBearerKey: []
parameters:
- name: provider
in: path
required: true
schema: {type: string, pattern: '^[a-z][a-z0-9_-]*$'}
- name: kind
in: path
required: true
schema: {type: string, enum: [metadata, quotas, account]}
responses:
'200':
description: Current provider account observation.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ProviderMetadata'
- $ref: '#/components/schemas/ProviderQuotas'
- $ref: '#/components/schemas/ProviderAccount'
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/ProviderResourceFailure'
'502':
$ref: '#/components/responses/ProviderResourceFailure'
/model/v1/assets:
post:
operationId: uploadTenantAsset
summary: Upload exact tenant media bytes
description: >-
Stores one media asset for the configured retention
period. The authenticated tenant owns the returned opaque asset id.
tags:
- Proxy
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/RequestTimeout'
requestBody:
$ref: '#/components/requestBodies/AssetUpload'
responses:
'201':
$ref: '#/components/responses/AssetCreated'
'400':
$ref: '#/components/responses/AssetFailure'
'403':
$ref: '#/components/responses/ProxyForbidden'
'413':
$ref: '#/components/responses/AssetFailure'
'499':
$ref: '#/components/responses/CallerClosed'
'504':
$ref: '#/components/responses/ProxyTimeout'
'500':
$ref: '#/components/responses/AssetFailure'
/model/v1/assets/{asset_id}:
get:
operationId: getTenantAsset
summary: Read one tenant asset metadata record
tags:
- Proxy
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/AssetID'
responses:
'200':
$ref: '#/components/responses/AssetAvailable'
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/AssetFailure'
'410':
$ref: '#/components/responses/AssetFailure'
'500':
$ref: '#/components/responses/AssetFailure'
delete:
operationId: deleteTenantAsset
summary: Delete one tenant asset
tags:
- Proxy
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/AssetID'
responses:
'204':
description: The asset is deleted.
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/AssetFailure'
'410':
$ref: '#/components/responses/AssetFailure'
'500':
$ref: '#/components/responses/AssetFailure'
/model/v1/assets/{asset_id}/content:
get:
operationId: downloadTenantAsset
summary: Download exact tenant asset bytes
tags:
- Proxy
security:
- TenantBearerKey: []
parameters:
- $ref: '#/components/parameters/AssetID'
responses:
'200':
description: Exact authenticated asset bytes.
content:
application/json:
schema: {}
application/x-subrip:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/webp:
schema:
type: string
format: binary
audio/m4a:
schema:
type: string
format: binary
audio/mpeg:
schema:
type: string
format: binary
audio/wav:
schema:
type: string
format: binary
audio/flac:
schema:
type: string
format: binary
audio/ogg:
schema:
type: string
format: binary
video/mp4:
schema:
type: string
format: binary
video/webm:
schema:
type: string
format: binary
application/octet-stream:
schema:
type: string
format: binary
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/AssetFailure'
'410':
$ref: '#/components/responses/AssetFailure'
'500':
$ref: '#/components/responses/AssetFailure'
/dictate:
post:
operationId: postDictation
summary: Transcribe an audio upload
description: >-
Hosted dictation requires Idempotency-Key. Identical audio and format replay the accepted request across both transcription interfaces.
The usage journal retains provider measurements and the request identity after result expiry.
tags:
- Proxy
security:
- TenantClientKey: []
x-llm-proxy-allow-undeclared-query: true
parameters:
- $ref: '#/components/parameters/TenantClientKey'
- $ref: '#/components/parameters/Provider'
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/RequestTimeout'
- $ref: '#/components/parameters/HostedCompletionIdempotencyKey'
requestBody:
$ref: '#/components/requestBodies/DictationRequest'
responses:
'202':
$ref: '#/components/responses/StructuredRequestPending'
'410':
$ref: '#/components/responses/HostedResultExpired'
'200':
$ref: '#/components/responses/DictationSuccess'
'400':
$ref: '#/components/responses/ProxyBadRequest'
'402':
$ref: '#/components/responses/HostedFundsFailure'
'403':
$ref: '#/components/responses/ProxyForbidden'
'409':
$ref: '#/components/responses/V2Conflict'
'413':
$ref: '#/components/responses/ProxyPayloadTooLarge'
'429':
$ref: '#/components/responses/ProxyRateLimited'
'499':
$ref: '#/components/responses/CallerClosed'
'502':
$ref: '#/components/responses/ProxyBadGateway'
'503':
$ref: '#/components/responses/ProxyUnavailable'
'504':
$ref: '#/components/responses/ProxyTimeout'
/config-ui.yaml:
get:
operationId: getBrowserConfiguration
summary: Read the browser runtime configuration
tags:
- Configuration
security: []
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
description: Current browser runtime configuration.
headers:
Cache-Control:
description: Prevents persistence of environment-specific browser configuration.
schema:
type: string
const: no-store
x-required: true
content:
application/yaml:
schema:
type: string
description: >-
YAML with llmProxy origins and environment auth configuration.
Auth includes tauthUrl, tenantId, logoutPath, sessionPath, and providers.
The Google provider declares enabled, clientId, loginPath, and noncePath.
Apple and password providers declare enabled false.
/api/public/capabilities:
get:
operationId: getPublicCapabilities
summary: Read the public normalized model capability catalog
description: Returns the deterministic, secret-free projection of model publishers, families, exact models, provider offerings, and public proxy request limits.
tags:
- Capabilities
security: []
responses:
'200':
description: Current public capability catalog.
headers:
Access-Control-Allow-Origin:
description: Permits browser reads of this public resource without credentials.
schema:
type: string
const: '*'
x-required: true
Cache-Control:
description: Allows short-lived caching of the public catalog.
schema:
type: string
const: public, max-age=300
x-required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCapabilityCatalog'
/api/management/account:
get:
operationId: getManagementAccount
summary: Read the authenticated user and owned tenant summaries
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/AccountSuccess'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/usage:
get:
operationId: getManagementAccountUsage
summary: Read interval-scoped usage across every owned tenant
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/UsageInterval'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/UsageSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/usage/failures:
get:
operationId: getManagementAccountUsageFailures
summary: Read safe failure details across every owned tenant and interval
description: Returns a newest-first snapshot page of failed managed proxy events across every tenant owned by the authenticated user. Each row identifies its tenant by opaque ID and current name while exposing only bounded diagnostic metadata and canonical outcome codes. Rows never include prompts, responses, provider bodies, free-form errors, credentials, or another user's ownership data.
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/UsageInterval'
- $ref: '#/components/parameters/UsageDetailLimit'
- $ref: '#/components/parameters/UsageDetailCursor'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/AccountUsageFailuresSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/usage/rejections:
get:
operationId: getManagementAccountUsageRejections
summary: Read safe rejected-request details across every owned tenant and interval
description: Returns a newest-first snapshot page of rejected managed proxy requests across every tenant owned by the authenticated user. Rejected requests did not reach provider dispatch and are excluded from execution totals, failure totals, charts, dimensions, status breakdowns, and success rate. Each row exposes only bounded diagnostic metadata and its canonical rejection outcome.
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/UsageInterval'
- $ref: '#/components/parameters/UsageDetailLimit'
- $ref: '#/components/parameters/UsageDetailCursor'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/AccountUsageRejectionsSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants:
post:
operationId: createManagementTenant
summary: Create an owned tenant
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
$ref: '#/components/requestBodies/TenantNameRequest'
responses:
'201':
$ref: '#/components/responses/TenantProfileCreated'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'409':
$ref: '#/components/responses/ManagementConflict'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/admin/users:
get:
operationId: getManagementAdminUsers
summary: Read the administrative user and tenant usage summary
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/AdminUsersSuccess'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}:
get:
operationId: getManagementTenant
summary: Read an owned tenant profile
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/TenantProfileSuccess'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/ManagementNotFound'
'500':
$ref: '#/components/responses/ManagementInternalError'
put:
operationId: renameManagementTenant
summary: Rename an owned tenant
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
$ref: '#/components/requestBodies/TenantNameRequest'
responses:
'200':
$ref: '#/components/responses/TenantProfileSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/ManagementNotFound'
'409':
$ref: '#/components/responses/ManagementConflict'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
delete:
operationId: deleteManagementTenant
summary: Delete an owned non-final tenant
description: Tenants with hosted grant history cannot be deleted. The service returns 409 with managed_tenant_hosted_history.
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'204':
description: Tenant deleted.
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/ManagementNotFound'
'409':
$ref: '#/components/responses/ManagementConflict'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}/usage:
get:
operationId: getManagementTenantUsage
summary: Read interval-scoped usage for an owned tenant
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/UsageInterval'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/UsageSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/ManagementNotFound'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}/usage/failures:
get:
operationId: getManagementTenantUsageFailures
summary: Read safe failure details for an owned tenant and interval
description: Returns a newest-first snapshot page of failed managed proxy events. Rows expose only bounded diagnostic metadata and canonical outcome codes; they never include prompts, responses, provider bodies, free-form errors, credentials, or ownership identifiers. Historical rows use status-derived normalized outcome codes rather than reconstructed error messages.
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/UsageInterval'
- $ref: '#/components/parameters/UsageDetailLimit'
- $ref: '#/components/parameters/UsageDetailCursor'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/UsageFailuresSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/ManagementNotFound'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}/usage/rejections:
get:
operationId: getManagementTenantUsageRejections
summary: Read safe rejected-request details for an owned tenant and interval
description: Returns a newest-first snapshot page of rejected managed proxy requests. These requests did not reach provider dispatch and are excluded from execution and failure metrics. Rows expose only bounded diagnostic metadata and canonical rejection outcomes.
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/UsageInterval'
- $ref: '#/components/parameters/UsageDetailLimit'
- $ref: '#/components/parameters/UsageDetailCursor'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/UsageRejectionsSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/ManagementNotFound'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/billing-accounts:
get:
operationId: listBillingAccounts
summary: Read the authenticated owner's billing account
tags: [Management]
security:
- TAuthSession: []
responses:
'200':
description: The account list. A read does not create an account.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [billing_accounts]
properties:
billing_accounts:
type: array
maxItems: 1
items:
$ref: '#/components/schemas/BillingAccount'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'500':
$ref: '#/components/responses/HostedResourceError'
post:
operationId: createBillingAccount
summary: Create one USD billing account for the authenticated owner
tags: [Management]
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
- $ref: '#/components/parameters/HostedCreationKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required: [currency]
properties:
currency:
type: string
enum: [USD]
responses:
'201':
description: The immutable account creation response, including on a retry with the same key.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
Location:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/BillingAccount'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'409':
$ref: '#/components/responses/HostedResourceError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}:
get:
operationId: getBillingAccount
summary: Read an owned billing account
tags: [Management]
security:
- TAuthSession: []
parameters:
- name: billing_account_id
in: path
required: true
schema:
type: string
responses:
'200':
description: The owned account.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/BillingAccount'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/funding-offers:
get:
operationId: listFundingOffers
summary: List server funding offers
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
responses:
'200':
description: The owned funding resource.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/FundingOffers'
'400':
$ref: '#/components/responses/FundingError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/FundingError'
'500':
$ref: '#/components/responses/HostedResourceError'
'503':
$ref: '#/components/responses/FundingError'
/api/management/billing-accounts/{billing_account_id}/funding-orders:
get:
operationId: listFundingOrders
summary: List owned funding orders
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/HostedPageLimit'
- name: cursor
in: query
schema: {type: string, pattern: '^funding-[a-f0-9]{32}$'}
description: Continue after this identifier in ascending identifier order.
responses:
'200':
description: The owned funding resource.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/FundingOrders'
'400':
$ref: '#/components/responses/FundingError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/FundingError'
'500':
$ref: '#/components/responses/HostedResourceError'
'503':
$ref: '#/components/responses/FundingError'
post:
operationId: createFundingOrder
summary: Create an owned funding order
tags: [Management]
security:
- TAuthSession: []
description: >-
Select one server offer. Commit its immutable price, USD funding amount,
processor identity, and checkout delivery intent in one transaction.
The account and creation key identify one order. A repeated key returns
that order. A changed offer or processor identity returns 409.
Order creation does not grant funds or confirm payment.
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/OptionalOrigin'
- $ref: '#/components/parameters/HostedCreationKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required: [offer_code]
properties:
offer_code: {type: string, minLength: 1, maxLength: 64}
responses:
'201':
description: The owned funding resource.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
Location:
schema: {type: string}
content:
application/json:
schema:
$ref: '#/components/schemas/FundingOrder'
'400':
$ref: '#/components/responses/FundingError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/FundingError'
'500':
$ref: '#/components/responses/HostedResourceError'
'503':
$ref: '#/components/responses/FundingError'
'403':
$ref: '#/components/responses/ManagementForbidden'
'409':
$ref: '#/components/responses/FundingError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
/api/management/billing-accounts/{billing_account_id}/funding-orders/{order_id}:
get:
operationId: getFundingOrder
summary: Read an owned funding order
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- name: order_id
in: path
required: true
schema: {type: string, pattern: '^funding-[a-f0-9]{32}$'}
responses:
'200':
description: The owned funding resource.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/FundingOrder'
'400':
$ref: '#/components/responses/FundingError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/FundingError'
'500':
$ref: '#/components/responses/HostedResourceError'
'503':
$ref: '#/components/responses/FundingError'
/api/management/billing-accounts/{billing_account_id}/funding-orders/{order_id}/checkout:
get:
operationId: getPaymentCheckout
summary: Read the checkout for an owned funding order
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- name: order_id
in: path
required: true
schema: {type: string, pattern: '^funding-[a-f0-9]{32}$'}
responses:
'200':
description: The owned funding resource.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentCheckout'
'400':
$ref: '#/components/responses/FundingError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/FundingError'
'500':
$ref: '#/components/responses/HostedResourceError'
'503':
$ref: '#/components/responses/FundingError'
/api/management/billing-accounts/{billing_account_id}/funding-orders/{order_id}/receipt:
get:
operationId: getPaymentReceipt
summary: Read the receipt for an owned funding order
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- name: order_id
in: path
required: true
schema: {type: string, pattern: '^funding-[a-f0-9]{32}$'}
responses:
'200':
description: The owned funding resource.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentReceipt'
'400':
$ref: '#/components/responses/FundingError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/FundingError'
'500':
$ref: '#/components/responses/HostedResourceError'
'503':
$ref: '#/components/responses/FundingError'
/api/management/billing-accounts/{billing_account_id}/payment-portal-sessions:
post:
operationId: createPaymentPortalSession
summary: Create a temporary Paddle customer portal session
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
description: Each request creates a temporary link without a financial effect. Do not cache or store the link.
x-llm-proxy-required-request-content-type: application/json
requestBody:
required: true
content:
application/json:
schema: {type: object, additionalProperties: false, properties: {}}
responses:
'201':
description: The temporary portal session.
headers:
Location:
schema: {type: string, format: uri}
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentPortalSession'
'400':
$ref: '#/components/responses/FundingError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/FundingError'
'500':
$ref: '#/components/responses/HostedResourceError'
'503':
$ref: '#/components/responses/FundingError'
'403':
$ref: '#/components/responses/ManagementForbidden'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/charge-summary:
get:
operationId: getRequestChargeSummary
summary: Read the charge totals for an owned request
description: Totals include all attempts and customer credits from one database snapshot. Pending or unresolved customer totals are null.
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- name: request_id
in: path
required: true
schema: {type: string, minLength: 1}
responses:
'200':
description: The current request totals.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/RequestChargeSummary'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/reservations/{request_id}:
get:
operationId: getFundsReservation
summary: Read a reservation and its exact authorization
description: Requires the account owner or an operator. The revision and exact maximum support an audited financial decision.
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/JournalRequestID'
responses:
'200':
description: The current reservation and immutable authorization.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/HostedFundsReservationDetail'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/funds-resolution:
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/JournalRequestID'
get:
operationId: getFundsResolution
summary: Read an audited financial resolution
description: The account owner or an operator can read this receipt. Private operator identity and evidence references remain in the audit record.
tags: [Management]
security:
- TAuthSession: []
responses:
'200':
description: The retained financial decision. Provider evidence remains unchanged.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/HostedFundsResolution'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
put:
operationId: createFundsResolution
summary: Record an operator decision for an uncertain hold
description: Requires an operator session and the current reservation revision. Authorization, known pricing, and prior credits bound the final net charge. An identical repeat has one financial effect.
tags: [Management]
security:
- TAuthSession: []
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required: [revision, customer_charge, reason, evidence_reference]
properties:
revision: {type: integer, minimum: 1}
customer_charge:
$ref: '#/components/schemas/ExactMoney'
description: Final net USD charge after prior credits. Zero waives the charge.
reason: {type: string, pattern: '^[a-z][a-z0-9_]{0,63}$'}
evidence_reference: {type: string, minLength: 1, maxLength: 256}
responses:
'200':
description: The immutable decision and settled amount.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/HostedFundsResolution'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/HostedResourceError'
'409':
$ref: '#/components/responses/HostedResourceError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/funds-credits/{credit_id}:
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/JournalRequestID'
- name: credit_id
in: path
required: true
schema: {type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'}
get:
operationId: getFundsCredit
summary: Read an audited request credit
description: The account owner or an operator can read this receipt. Private operator identity and evidence references remain in the audit record.
tags: [Management]
security:
- TAuthSession: []
responses:
'200':
description: The retained credit. Provider evidence remains unchanged.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/HostedFundsCredit'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
put:
operationId: createFundsCredit
summary: Record an operator credit for a settled request
description: Requires an operator session. Total credits cannot exceed the settled request charge. An identical repeat has one financial effect.
tags: [Management]
security:
- TAuthSession: []
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required: [credit, reason, evidence_reference]
properties:
credit:
$ref: '#/components/schemas/ExactMoney'
description: Positive exact USD credit. The account remainder controls the whole cents returned.
reason: {type: string, pattern: '^[a-z][a-z0-9_]{0,63}$'}
evidence_reference: {type: string, minLength: 1, maxLength: 256}
responses:
'200':
description: The immutable credit and returned whole cents.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/HostedFundsCredit'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/HostedResourceError'
'409':
$ref: '#/components/responses/HostedResourceError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/tenant-limits/{tenant_id}:
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- name: tenant_id
in: path
required: true
schema: {type: string, minLength: 1}
get:
operationId: getTenantFundsLimit
summary: Read the cumulative spending limit of an owned tenant
tags: [Management]
security:
- TAuthSession: []
responses:
'200':
description: Exact net usage and active reservations under the optional limit. This read creates no records.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/HostedTenantFundsLimit'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
put:
operationId: setTenantFundsLimit
summary: Set the cumulative spending limit of an owned tenant
description: The revision prevents concurrent replacement. A repeated identical last change returns the current resource. Existing reservations remain authorized.
tags: [Management]
security:
- TAuthSession: []
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required: [limit_cents, revision]
properties:
limit_cents:
type: [string, 'null']
pattern: '^(0|[1-9][0-9]*)$'
description: Cumulative USD limit in cents, through the maximum signed 64-bit integer. Null removes the tenant limit.
revision: {type: integer, minimum: 0}
responses:
'200':
description: The retained limit and current usage.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/HostedTenantFundsLimit'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/HostedResourceError'
'409':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/balance:
get:
operationId: getFundsBalance
summary: Read the funds of an owned billing account
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
responses:
'200':
description: Funds from one database snapshot. This read creates no financial records.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/HostedFundsBalance'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/reservations:
get:
operationId: listFundsReservations
summary: Read reservations of an owned billing account
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/HostedPageLimit'
- name: cursor
in: query
schema: {type: string, pattern: '^request-[a-f0-9]{32}$'}
responses:
'200':
description: Reservations in ascending identifier order. The cursor is the last identifier of a nonfinal page.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/FundsReservationPage'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/ledger-entries:
get:
operationId: listFundsEntries
summary: Read Ledger entries of an owned billing account
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/HostedPageLimit'
- name: cursor
in: query
schema: {type: string, minLength: 1, maxLength: 128}
responses:
'200':
description: Entries in ascending identifier order. The cursor is the last identifier of a nonfinal page.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/FundsEntryPage'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/charges:
get:
operationId: listCharges
summary: Read charges for an owned billing account
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/HostedPageLimit'
- name: cursor
in: query
schema: {type: string, pattern: '^charge-[a-f0-9]{32}$'}
responses:
'200':
description: The retained account resource.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ChargePage'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/charges/{charge_id}:
get:
operationId: getCharge
summary: Read one charge from an owned billing account
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- name: charge_id
in: path
required: true
schema: {type: string, minLength: 1}
responses:
'200':
description: The retained account resource.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/HostedCharge'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/price-snapshots/{price_snapshot_id}:
get:
operationId: getPriceSnapshot
summary: Read the prices retained for an accepted request
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- name: price_snapshot_id
in: path
required: true
schema: {type: string, minLength: 1}
responses:
'200':
description: The retained account resource.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/HostedPriceSnapshot'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/requests:
get:
operationId: listJournalRequests
summary: Read the usage journal for an owned billing account
description: Results use ascending request identifiers. Each response contains at most 100 requests. Credentials and request content are omitted.
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/HostedPageLimit'
- name: cursor
in: query
schema:
type: string
pattern: '^request-[a-f0-9]{32}$'
responses:
'200':
description: The account usage journal page.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [requests, next_cursor]
properties:
requests:
type: array
items:
$ref: '#/components/schemas/JournalRequest'
next_cursor:
type: string
description: The last request identifier when another page exists. An empty value ends the collection.
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}:
get:
operationId: getJournalRequest
summary: Read one request from an owned usage journal
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- name: request_id
in: path
required: true
schema:
type: string
pattern: '^request-[a-f0-9]{32}$'
responses:
'200':
description: The retained request and its usage completeness.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/JournalRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/attempts:
get:
operationId: listJournalAttempts
summary: Read attempts for an owned journal request
description: Results use ascending opaque identifiers. Each response contains at most 100 records. Private provider identifiers and source content are omitted.
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/JournalRequestID'
- $ref: '#/components/parameters/HostedPageLimit'
- name: cursor
in: query
schema:
type: string
pattern: '^attempt-[a-f0-9]{32}$'
responses:
'200':
description: The owned request collection page.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [attempts, next_cursor]
properties:
attempts:
type: array
maxItems: 100
items:
$ref: '#/components/schemas/JournalAttempt'
next_cursor:
type: string
description: The last record identifier when another page exists. An empty value ends the collection.
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/observations:
get:
operationId: listJournalObservations
summary: Read usage observations for an owned journal request
description: Results use ascending opaque identifiers. Each response contains at most 100 records. Private provider identifiers and source content are omitted.
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/JournalRequestID'
- $ref: '#/components/parameters/HostedPageLimit'
- name: cursor
in: query
schema:
type: string
pattern: '^observation-[a-f0-9]{32}$'
responses:
'200':
description: The owned request collection page.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [observations, next_cursor]
properties:
observations:
type: array
maxItems: 100
items:
$ref: '#/components/schemas/JournalObservation'
next_cursor:
type: string
description: The last record identifier when another page exists. An empty value ends the collection.
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/reconciliation-cases:
get:
operationId: listJournalReconciliationCases
summary: Read reconciliation cases for an owned journal request
description: Results use ascending opaque identifiers. Each response contains at most 100 records. Private provider identifiers and source content are omitted.
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/BillingAccountID'
- $ref: '#/components/parameters/JournalRequestID'
- $ref: '#/components/parameters/HostedPageLimit'
- name: cursor
in: query
schema:
type: string
pattern: '^case-[a-f0-9]{32}$'
responses:
'200':
description: The owned request collection page.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [cases, next_cursor]
properties:
cases:
type: array
maxItems: 100
items:
$ref: '#/components/schemas/JournalReconciliationCase'
next_cursor:
type: string
description: The last record identifier when another page exists. An empty value ends the collection.
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/platform-connections:
get:
operationId: listPlatformConnections
summary: Read platform connection metadata as an operator
tags: [Management]
security:
- TAuthSession: []
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: cursor
in: query
schema:
type: string
pattern: '^platform-[a-f0-9]{32}$'
responses:
'200':
description: Connection metadata in ascending identifier order. Credentials are excluded.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [platform_connections, next_cursor]
properties:
platform_connections:
type: array
items:
$ref: '#/components/schemas/PlatformConnection'
next_cursor:
type: string
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'500':
$ref: '#/components/responses/HostedResourceError'
post:
operationId: createPlatformConnection
summary: Verify and create a platform connection as an operator
tags: [Management]
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
- $ref: '#/components/parameters/HostedCreationKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformConnectionWrite'
responses:
'201':
description: The immutable creation receipt. Repeated keys require identical intent.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
Location:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformConnection'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'409':
$ref: '#/components/responses/HostedResourceError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'422':
$ref: '#/components/responses/ProviderKeyRejected'
'429':
$ref: '#/components/responses/ProviderKeyVerificationRateLimited'
'500':
$ref: '#/components/responses/HostedResourceError'
'503':
$ref: '#/components/responses/ProviderKeyVerificationUnavailable'
'504':
$ref: '#/components/responses/ProviderKeyVerificationTimedOut'
/api/management/platform-connections/{platform_connection_id}:
get:
operationId: getPlatformConnection
summary: Read platform connection metadata as an operator
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/PlatformConnectionID'
responses:
'200':
$ref: '#/components/responses/PlatformConnectionSuccess'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
put:
operationId: rotatePlatformConnection
summary: Replace platform credentials while retaining accepted versions
tags: [Management]
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
- $ref: '#/components/parameters/PlatformConnectionID'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformConnectionWrite'
responses:
'200':
$ref: '#/components/responses/PlatformConnectionSuccess'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/HostedResourceError'
'409':
$ref: '#/components/responses/HostedResourceError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'422':
$ref: '#/components/responses/ProviderKeyRejected'
'429':
$ref: '#/components/responses/ProviderKeyVerificationRateLimited'
'500':
$ref: '#/components/responses/HostedResourceError'
'503':
$ref: '#/components/responses/ProviderKeyVerificationUnavailable'
'504':
$ref: '#/components/responses/ProviderKeyVerificationTimedOut'
/api/management/hosted-access-grants:
get:
operationId: listHostedAccessGrants
summary: Read hosted access grants for the authenticated account
description: Operators can read all grants. Results use ascending ID order and an exclusive cursor.
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/HostedPageLimit'
- name: cursor
in: query
schema:
type: string
pattern: '^grant-[a-f0-9]{32}$'
responses:
'200':
description: The account grants without platform credentials or private provider handles.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [hosted_access_grants, next_cursor]
properties:
hosted_access_grants:
type: array
items:
$ref: '#/components/schemas/HostedAccessGrant'
next_cursor:
type: string
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'500':
$ref: '#/components/responses/HostedResourceError'
post:
operationId: createHostedAccessGrant
summary: Create a hosted access grant as an operator
description: >-
Creation binds one tenant to its billing account and explicit provider offerings.
A grant does not bypass pricing, metering, funds admission, or the hosted activation gate.
The original creation response remains available after grant changes and catalog changes.
tags: [Management]
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
- $ref: '#/components/parameters/HostedCreationKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HostedAccessGrantCreate'
responses:
'201':
description: The retained creation response. Read the resource for its current state.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
Location:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/HostedAccessGrant'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/HostedResourceError'
'409':
$ref: '#/components/responses/HostedResourceError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/hosted-access-grants/{grant_id}:
get:
operationId: getHostedAccessGrant
summary: Read one hosted access grant
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/HostedGrantID'
responses:
'200':
$ref: '#/components/responses/HostedAccessGrantSuccess'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
patch:
operationId: changeHostedAccessGrant
summary: Change grant state with a revision precondition
description: >-
Only operators can change grants. Each change records its actor and reason in the same transaction.
Suspended grants can return to active state. Revoked grants cannot return to another state.
A stale revision or an unchanged state returns a conflict. Read the current resource before another change.
tags: [Management]
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
- $ref: '#/components/parameters/HostedGrantID'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required: [state, revision, reason]
properties:
state:
$ref: '#/components/schemas/HostedGrantState'
revision:
type: integer
minimum: 1
maximum: 9223372036854775806
reason:
$ref: '#/components/schemas/HostedGrantReason'
responses:
'200':
$ref: '#/components/responses/HostedAccessGrantSuccess'
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/HostedResourceError'
'409':
$ref: '#/components/responses/HostedResourceError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/hosted-access-grants/{grant_id}/revisions:
get:
operationId: listHostedAccessGrantRevisions
summary: Read the grant audit as an operator
description: Revisions use ascending order. Each cursor identifies the last revision on the previous page.
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/HostedGrantID'
- $ref: '#/components/parameters/HostedPageLimit'
- name: cursor
in: query
schema:
type: string
pattern: '^[1-9][0-9]*$'
responses:
'200':
description: Retained grant revisions with operator identity and reason.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [revisions, next_cursor]
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/HostedAccessGrantRevision'
next_cursor:
type: string
'400':
$ref: '#/components/responses/HostedResourceError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/HostedResourceError'
'500':
$ref: '#/components/responses/HostedResourceError'
/api/management/connections:
get:
operationId: listManagementConnections
summary: List account connections and provider definitions
description: Connections use ascending ID order. Continue with next_cursor. An empty next_cursor indicates the last page.
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: cursor
in: query
description: The next_cursor from the previous page. The cursor remains valid after connection deletion.
schema:
type: string
pattern: '^connection-[0-9a-f]{32}$'
responses:
'200':
description: Operation completed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/AccountConnections'
'400':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'409':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'500':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
post:
operationId: createManagementConnection
summary: Verify credentials and create an account connection
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
- $ref: '#/components/parameters/ConnectionCreationKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountConnectionWrite'
responses:
'201':
description: Operation completed.
content:
application/json:
schema:
$ref: '#/components/schemas/AccountConnection'
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
Location:
description: The created connection resource.
schema:
type: string
'400':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'409':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'422':
$ref: '#/components/responses/ProviderKeyRejected'
'429':
$ref: '#/components/responses/ProviderKeyVerificationRateLimited'
'500':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'503':
$ref: '#/components/responses/ProviderKeyVerificationUnavailable'
'504':
$ref: '#/components/responses/ProviderKeyVerificationTimedOut'
/api/management/connections/{connection_id}:
get:
operationId: getManagementConnection
summary: Read a connection with masked credentials
tags:
- Management
security:
- TAuthSession: []
parameters:
- name: connection_id
in: path
required: true
schema:
type: string
minLength: 1
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
description: Operation completed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/AccountConnection'
'400':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'409':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'500':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
put:
operationId: replaceManagementConnection
summary: Update a connection at its expected version
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- name: connection_id
in: path
required: true
schema:
type: string
minLength: 1
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountConnectionWrite'
responses:
'200':
description: Operation completed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/AccountConnection'
'400':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'409':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'422':
$ref: '#/components/responses/ProviderKeyRejected'
'429':
$ref: '#/components/responses/ProviderKeyVerificationRateLimited'
'500':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'503':
$ref: '#/components/responses/ProviderKeyVerificationUnavailable'
'504':
$ref: '#/components/responses/ProviderKeyVerificationTimedOut'
delete:
operationId: deleteManagementConnection
summary: Delete an unassigned connection
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- name: connection_id
in: path
required: true
schema:
type: string
minLength: 1
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'204':
description: Operation completed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
'400':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'409':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
/api/management/tenants/{tenant_id}/connections:
get:
operationId: listManagementProviderAssignments
summary: Read the tenant's explicit provider assignments
description: The list contains one assignment per selected provider, in provider ID order. It contains no platform credentials.
tags: [Management]
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/TenantID'
responses:
'200':
description: The tenant's selected account connections and hosted access grants.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [assignments]
properties:
assignments:
type: array
items:
$ref: '#/components/schemas/TenantProviderAssignment'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
description: The tenant does not belong to the authenticated account.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'500':
description: The assignment store is unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
/api/management/tenants/{tenant_id}/connections/{provider}:
put:
operationId: assignManagementConnection
summary: Select an account connection or hosted access grant for one provider
description: >-
The resource must belong to the tenant's account. A hosted grant must also name this tenant and provider.
Detach the current assignment before selecting a different resource. The service does not substitute credential sources.
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/ProviderPath'
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TenantConnectionAssignment'
responses:
'200':
description: Operation completed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/TenantProfile'
'400':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'409':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
delete:
operationId: detachManagementConnection
summary: Detach the selected provider resource and optionally clear dependent defaults
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/ProviderPath'
- name: clear_defaults
in: query
schema:
type: string
enum:
- 'true'
- 'false'
description: Use true to confirm removal of dependent default routes.
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'204':
description: Operation completed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
'400':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'409':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
/api/management/tenants/{tenant_id}/provider-profiles/{provider}:
put:
operationId: updateManagementProviderProfile
summary: Save the tenant provider model and system prompt
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/ProviderPath'
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TenantProviderProfileWrite'
responses:
'200':
description: Operation completed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/TenantProfile'
'400':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'409':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
description: The connection operation failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectionError'
/api/management/tenants/{tenant_id}/defaults:
put:
operationId: putManagementTenantDefaults
summary: Replace the tenant routing defaults
description: Every nonempty provider/model pair must use a provider for which this tenant has a saved API key. The text pair is empty only when no provider key exists. An empty dictation pair is a valid unset selection. A catalog capability change preserves it.
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
$ref: '#/components/requestBodies/DefaultsRequest'
responses:
'200':
$ref: '#/components/responses/TenantProfileSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/ManagementNotFound'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}/secrets:
post:
operationId: postManagementTenantSecret
summary: Generate and replace the tenant client secret
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
$ref: '#/components/requestBodies/EmptyJSONRequest'
responses:
'200':
$ref: '#/components/responses/TenantSecretSuccess'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/ManagementNotFound'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
components:
securitySchemes:
PaddleSignature:
type: apiKey
in: header
name: Paddle-Signature
description: Timestamp and HMAC signature of the raw request body, verified with the configured Paddle secret.
MCPAccessToken:
type: http
scheme: bearer
bearerFormat: JWT
description: TAuth OAuth access token with the API audience and llm-proxy:use scope.
TenantBearerKey:
type: http
scheme: bearer
bearerFormat: tenant-client-key
TenantClientKey:
type: apiKey
in: query
name: key
description: The tenant client secret generated by the management API.
TAuthSession:
type: apiKey
in: cookie
name: app_session_llm_proxy
description: The exact deployment-configured TAuth session cookie. The production cookie name is configured through management.session_cookie_name.
parameters:
TenantClientKey:
name: key
in: query
required: true
description: Tenant client secret.
schema:
type: string
minLength: 1
Prompt:
name: prompt
in: query
required: true
description: User prompt.
schema:
type: string
minLength: 1
Provider:
name: provider
in: query
required: false
description: Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. Omission uses the tenant default.
schema:
type: string
minLength: 1
Model:
name: model
in: query
required: false
description: Model identifier. Omission uses the resolved provider default.
schema:
type: string
minLength: 1
WebSearch:
name: web_search
in: query
required: false
description: Exact boolean query parameter. Use true or false; omission disables web search. Any other supplied spelling is invalid and returns HTTP 400.
schema:
type: boolean
SystemPrompt:
name: system_prompt
in: query
required: false
schema:
type: string
MaxTokens:
name: max_tokens
in: query
required: false
description: Initial per-attempt output budget. A transport that declares continuation actions reuses this budget for a missing suffix.
schema:
type: integer
minimum: 1
ReasoningEffort:
name: reasoning_effort
in: query
required: false
description: >-
Non-blank effort supported by the resolved route. Omission selects the
tenant or route default.
schema:
type: string
minLength: 1
ResponseFormat:
name: format
in: query
required: false
description: Preferred response media type. Unknown values select text/plain.
schema:
type: string
enum:
- text/plain
- application/json
- application/xml
- text/xml
- text/csv
Accept:
name: Accept
in: header
required: false
description: Response media preference used when format is omitted.
schema:
type: string
RequestTimeout:
name: X-LLM-Proxy-Request-Timeout-Seconds
in: header
required: false
description: A positive whole-second request budget no greater than the server maximum. Omission selects the configured default.
schema:
type: integer
minimum: 1
OptionalIdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: >-
Required for hosted text and structured output. A hosted key identifies one tenant request across native and client protocols.
An identical request returns its saved result or active receipt. Changed intent returns 409. Expired hosted results return 410.
A hosted replay never starts another execution. For account-owned credentials, the key requires structured_output.
A known failed request with account-owned credentials permits an explicit new attempt.
schema:
type: string
pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
HostedCompletionIdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: >-
Required for hosted text and dictation. The key identifies one tenant request across native and client protocols.
An identical request returns its saved result or active receipt. Changed intent returns 409.
Expired hosted results return 410. A hosted replay never starts another execution.
schema:
type: string
pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
HostedPageLimit:
name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
BillingAccountID:
name: billing_account_id
in: path
required: true
schema:
type: string
pattern: '^billing-[a-f0-9]{32}$'
JournalRequestID:
name: request_id
in: path
required: true
schema:
type: string
pattern: '^request-[a-f0-9]{32}$'
HostedGrantID:
name: grant_id
in: path
required: true
schema:
type: string
pattern: '^grant-[a-f0-9]{32}$'
HostedCreationKey:
name: Idempotency-Key
in: header
required: true
description: A creation key scoped to the authenticated actor and resource kind.
schema:
type: string
pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
PlatformConnectionID:
name: platform_connection_id
in: path
required: true
schema:
type: string
pattern: '^platform-[a-f0-9]{32}$'
ConnectionCreationKey:
name: Idempotency-Key
in: header
required: true
description: >-
Account-scoped key for one connection creation request. Repeat the same
key and request to receive the original 201 response and Location.
A changed request returns 409. Receipts survive connection deletion.
Read the connection resource for its current state.
schema:
type: string
pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
IdempotencyKey:
name: Idempotency-Key
in: header
required: true
description: Exact key of the durable structured-output request to reconcile.
schema:
type: string
pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
MediaOperationIdempotencyKey:
name: Idempotency-Key
in: header
required: true
description: Tenant-bound key for one durable media operation intent. Exact repeats converge to the retained operation or tombstone. Changed intent returns 409 before dispatch.
schema:
type: string
pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$'
AssetID:
name: asset_id
in: path
required: true
description: Opaque tenant asset identifier.
schema:
type: string
pattern: ^ast_[0-9a-f]{32}$
MediaOperationID:
name: operation_id
in: path
required: true
description: Opaque durable media operation identifier.
schema:
type: string
pattern: ^mop_[0-9a-f]{32}$
MediaVoiceID:
name: voice_id
in: path
required: true
description: Opaque tenant voice identifier.
schema:
type: string
pattern: ^voi_[0-9a-f]{32}$
TenantID:
name: tenant_id
in: path
required: true
description: Opaque tenant identifier from the authenticated account response.
schema:
type: string
minLength: 1
ProviderPath:
name: provider
in: path
required: true
description: Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid.
schema:
type: string
minLength: 1
ProviderFieldPath:
name: field
in: path
required: true
description: Canonical secret field identifier from the selected provider definition.
schema:
type: string
minLength: 1
UsageInterval:
name: interval
in: query
required: true
schema:
type: string
enum:
- 1d
- 7d
- 30d
- all
UsageDetailLimit:
name: limit
in: query
required: false
description: Maximum failure rows in this page. Omission selects 25.
schema:
type: integer
minimum: 1
maximum: 100
default: 25
UsageDetailCursor:
name: cursor
in: query
required: false
description: Opaque continuation cursor returned by the preceding page for the same interval and reporting scope.
schema:
type: string
minLength: 1
OptionalOrigin:
name: Origin
in: header
required: false
description: When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers.
schema:
type: string
format: uri
RequiredOrigin:
name: Origin
in: header
required: true
description: Must exactly match the configured public origin.
schema:
type: string
format: uri
requestBodies:
TextRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TextRequest'
V2Request:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/V2Request'
DictationRequest:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/DictationRequest'
encoding:
audio:
contentType: audio/*,application/octet-stream
AssetUpload:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
application/json:
schema: {}
application/x-subrip:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/webp:
schema:
type: string
format: binary
audio/m4a:
schema:
type: string
format: binary
audio/mpeg:
schema:
type: string
format: binary
audio/wav:
schema:
type: string
format: binary
audio/flac:
schema:
type: string
format: binary
audio/ogg:
schema:
type: string
format: binary
video/mp4:
schema:
type: string
format: binary
video/webm:
schema:
type: string
format: binary
TenantNameRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TenantNameRequest'
DefaultsRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultsRequest'
EmptyJSONRequest:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyObject'
responses:
PaymentEventError:
description: The payment event was rejected or could not be retained.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [error]
properties:
error:
type: object
additionalProperties: false
required: [code]
properties:
code:
type: string
enum: [payment_event_invalid, payment_event_conflict, payment_content_type_invalid, payment_event_too_large, payment_signature_invalid, payment_inbox_unavailable]
TextSuccess:
description: >-
Complete generated text in the selected representation. Each provider
offering publishes one validated wire contract and an execution
lifecycle for text-only requests. A media-capable offering also
publishes media_execution_lifecycle for requests that contain image or
audio input. The proxy does not infer a lifecycle from an endpoint or
an upstream identifier. The proxy observes queued and in_progress
states only for a pollable lifecycle. Each public operation remains
blocking. Gemini media requests use synchronous completion and do not
poll an Interaction resource. Transports with continuation actions
continue exact output-budget stops through new provider calls. These
transports are OpenAI Responses incomplete/max_output_tokens,
OpenAI-compatible Chat Completions length, and Anthropic max_tokens.
Gemini Interactions has no continuation actions. An incomplete result
returns a provider error after cleanup. The adapter returns HTTP 200
only after the provider reports its complete signal. These signals are
OpenAI or Gemini completed, Chat stop, or Anthropic end_turn or
stop_sequence. Intermediate, safety, refusal, tool, malformed, missing,
and unknown states do not return text as success.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
X-LLM-Proxy-Request-Tokens:
$ref: '#/components/headers/OptionalTokenCount'
X-LLM-Proxy-Response-Tokens:
$ref: '#/components/headers/OptionalTokenCount'
X-LLM-Proxy-Total-Tokens:
$ref: '#/components/headers/OptionalTokenCount'
content:
text/plain:
schema:
type: string
application/json:
schema:
$ref: '#/components/schemas/TextJSONResponse'
application/xml:
schema:
type: string
text/csv:
schema:
type: string
V2Success:
description: Final text, caller-schema JSON, or caller function calls. Structured output includes durable request state. Function calls use NativeToolResult.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
X-LLM-Proxy-Request-Tokens:
$ref: '#/components/headers/OptionalTokenCount'
X-LLM-Proxy-Response-Tokens:
$ref: '#/components/headers/OptionalTokenCount'
X-LLM-Proxy-Total-Tokens:
$ref: '#/components/headers/OptionalTokenCount'
X-LLM-Proxy-Structured-Request-State:
$ref: '#/components/headers/OptionalStructuredRequestState'
content:
text/plain:
schema:
type: string
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/NativeToolResult'
- description: Native text response or JSON that passes the caller schema.
application/xml:
schema:
type: string
text/csv:
schema:
type: string
DictationSuccess:
description: Transcription result.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/DictationResponse'
ProxyBadRequest:
description: The request is malformed, names an invalid route/capability, or supplies an invalid timeout. Text validation failures use the canonical plain-text error. Timeout-header validation uses the canonical JSON error.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/OptionalResolvedRequestTimeout'
content:
text/plain:
schema:
type: string
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ProxyErrorEnvelope'
- $ref: '#/components/schemas/StructuredRequestErrorEnvelope'
MediaOperationForbidden:
description: The tenant key is unknown or the financial account is suspended.
content:
text/plain:
schema:
type: string
const: unknown client key
application/json:
schema:
$ref: '#/components/schemas/MediaOperationErrorEnvelope'
ProxyForbidden:
description: The tenant client key is absent or unknown, or hosted admission is denied.
content:
text/plain:
schema:
type: string
const: unknown client key
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorEnvelope'
TenantIdentitySuccess:
description: Server-resolved identity for the authenticated tenant.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/TenantIdentity'
ProxyPayloadTooLarge:
description: The compatibility JSON request limit, dictation audio limit, tenant asset limit, or selected provider media limit was exceeded.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
text/plain:
schema:
type: string
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorEnvelope'
V2BadRequest:
description: The canonical message input or referenced asset is invalid.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/OptionalResolvedRequestTimeout'
content:
text/plain:
schema:
type: string
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ProxyErrorEnvelope'
- $ref: '#/components/schemas/AssetErrorEnvelope'
- $ref: '#/components/schemas/StructuredRequestErrorEnvelope'
V2StructuredRequestPending:
description: The durable request is active. Reconcile the same key again.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
X-LLM-Proxy-Structured-Request-State:
$ref: '#/components/headers/StructuredRequestState'
content:
application/json:
schema:
$ref: '#/components/schemas/StructuredRequestStatus'
V2Conflict:
description: The provider is not configured, or the key identifies a different intent or an uncertain provider outcome.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
text/plain:
schema:
type: string
enum:
- provider_not_configured
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/StructuredRequestErrorEnvelope'
- $ref: '#/components/schemas/ProviderErrorEnvelope'
V2InternalFailure:
description: The asset store or structured request store failed.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AssetErrorEnvelope'
- $ref: '#/components/schemas/StructuredRequestErrorEnvelope'
AssetAvailable:
description: The asset metadata is available to its authenticated tenant.
content:
application/json:
schema:
$ref: '#/components/schemas/TenantAsset'
AssetCreated:
description: The asset is available to its authenticated tenant.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/TenantAsset'
AssetFailure:
description: The asset operation failed with a stable safe code.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/OptionalResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/AssetErrorEnvelope'
MediaOperation:
description: Current durable media operation state.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaOperation'
MediaOperationFailure:
description: The media operation request failed with a stable caller-safe code.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaOperationErrorEnvelope'
MediaOperationExpired:
description: Terminal operation detail expired. The tenant idempotency tombstone remains.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaOperationExpired'
ProviderDiagnostics:
description: Retained tenant operation counts for one assigned provider.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderDiagnostics'
ProviderDiagnosticsFailure:
description: A diagnostic read failed with a stable public code.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [error]
properties:
error:
type: object
additionalProperties: false
required: [code]
properties:
code:
type: string
enum: [provider_diagnostics_not_found, media_operation_store_error, method_not_allowed]
ProviderResourceFailure:
description: The assigned resource is absent or the provider observation is unavailable.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [error]
properties:
error:
type: object
additionalProperties: false
required: [code]
properties:
code:
type: string
enum: [provider_resource_not_found, provider_resource_unavailable]
MediaVoice:
description: One tenant-owned voice without native provider identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaVoice'
MediaVoiceCollection:
description: Tenant-owned voices discovered from the selected provider.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaVoiceCollection'
MediaVoiceFailure:
description: The voice request failed with a stable caller-safe code.
content:
application/json:
schema:
$ref: '#/components/schemas/MediaVoiceErrorEnvelope'
HostedClientFailure:
description: Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired.
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
HostedResultExpired:
description: The saved hosted result expired. The journal keeps the request identity and prevents another execution.
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorEnvelope'
V2Expired:
description: A referenced asset or saved hosted result expired.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AssetErrorEnvelope'
- $ref: '#/components/schemas/ProviderErrorEnvelope'
StructuredRequestExpired:
description: The saved hosted result expired. The journal keeps the request identity and prevents another execution.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/StructuredRequestErrorEnvelope'
StructuredRequestSucceeded:
description: >-
A saved hosted completion contains text, optional tool_calls, and optional usage.
An account-owned structured request returns the exact JSON that passed its caller schema.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Structured-Request-State:
$ref: '#/components/headers/StructuredRequestState'
content:
application/json:
schema: {}
StructuredRequestPending:
description: The durable request has not reached a terminal state. Reconcile the same key again.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Structured-Request-State:
$ref: '#/components/headers/StructuredRequestState'
content:
application/json:
schema:
$ref: '#/components/schemas/StructuredRequestStatus'
StructuredRequestBadRequest:
description: The Idempotency-Key is missing or invalid.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/StructuredRequestErrorEnvelope'
StructuredRequestNotFound:
description: No durable request exists for the authenticated tenant and key.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/StructuredRequestErrorEnvelope'
StructuredRequestConflict:
description: The key names a different request intent, or provider dispatch completed with an outcome that cannot be proven.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/StructuredRequestErrorEnvelope'
StructuredRequestFailed:
description: The durable request reached a safe terminal provider failure.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
X-LLM-Proxy-Structured-Request-State:
$ref: '#/components/headers/StructuredRequestState'
content:
application/json:
schema:
$ref: '#/components/schemas/StructuredRequestErrorEnvelope'
StructuredRequestStoreFailure:
description: The durable request record cannot be read or updated.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/StructuredRequestErrorEnvelope'
ProxyRateLimited:
description: The selected upstream provider returned HTTP 429. The proxy preserves 429 at its public boundary and returns only sanitized provider metadata; it never exposes the raw provider body or message.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Retry-After:
$ref: '#/components/headers/SafeRetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorEnvelope'
CallerClosed:
description: The caller canceled or closed the request.
ProxyBadGateway:
description: >-
The provider failed or returned an unusable response. A retained request failure uses the durable error representation.
The proxy continues output-budget stops only when the execution contract permits another attempt.
Errors exclude partial text, token-count headers, and raw provider errors. The journal can retain available usage after failure.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Retry-After:
$ref: '#/components/headers/SafeRetryAfter'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ProviderErrorEnvelope'
- $ref: '#/components/schemas/StructuredRequestErrorEnvelope'
HostedFundsFailure:
description: The available funds cannot cover the accepted maximum cost.
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorEnvelope'
ProxyUnavailable:
description: The request queue is full or financial admission is unavailable.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorEnvelope'
text/plain:
schema:
type: string
ProviderNotConfigured:
description: The selected catalog route cannot execute because its provider credentials are not configured. No provider dispatch occurs.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
text/plain:
schema:
type: string
enum:
- provider_not_configured
ProxyTimeout:
description: The proxy request budget or upstream operation timed out.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
text/plain:
schema:
type: string
application/json:
schema:
$ref: '#/components/schemas/ProxyErrorEnvelope'
FundingError:
description: The funding request failed without a financial effect.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [error]
properties:
error:
type: object
additionalProperties: false
required: [code]
properties:
code:
type: string
enum: [funding_invalid, funding_conflict, funding_not_found, funding_unavailable, billing_account_not_found]
HostedResourceError:
description: The hosted resource request failed.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
type: object
additionalProperties: false
required: [error]
properties:
error:
type: object
additionalProperties: false
required: [code]
properties:
code:
type: string
enum:
- billing_account_invalid
- billing_account_conflict
- billing_account_not_found
- billing_account_store_failed
- hosted_access_invalid
- hosted_access_conflict
- hosted_access_not_found
- hosted_access_store_failed
- usage_journal_invalid
- usage_journal_not_found
- usage_journal_conflict
- usage_journal_unavailable
HostedAccessGrantSuccess:
description: The grant state. Only operators receive the platform connection identifier.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/HostedAccessGrant'
PlatformConnectionSuccess:
description: Platform metadata without credentials. Only operators can read this resource.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformConnection'
AccountSuccess:
description: Authenticated account snapshot.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ManagementAccount'
TenantProfileSuccess:
description: Current tenant profile.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/TenantProfile'
TenantProfileCreated:
description: Created tenant profile.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/TenantProfile'
UsageSuccess:
description: Usage summary for the exact requested interval and authenticated reporting scope.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/UsageSummary'
UsageFailuresSuccess:
description: Snapshot page of safe tenant failure details for the exact requested interval.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/UsageFailurePage'
AccountUsageFailuresSuccess:
description: Snapshot page of safe failure details across every owned tenant for the exact requested interval.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/AccountUsageFailurePage'
UsageRejectionsSuccess:
description: Snapshot page of safe tenant rejection details for the exact requested interval.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/UsageRejectionPage'
AccountUsageRejectionsSuccess:
description: Snapshot page of safe rejection details across every owned tenant for the exact requested interval.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/AccountUsageRejectionPage'
AdminUsersSuccess:
description: Administrative user and tenant usage summary.
content:
application/json:
schema:
$ref: '#/components/schemas/AdminUsersSummary'
TenantSecretSuccess:
description: The newly generated tenant client secret and current profile. The secret is returned only by this response.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/TenantSecret'
ManagementBadRequest:
description: Malformed or invalid management input.
content:
text/plain:
schema:
type: string
ManagementUnauthorized:
description: The TAuth session is absent or invalid.
ManagementForbidden:
description: The user lacks the required role or the supplied Origin is not allowed.
ManagementNotFound:
description: The tenant or provider credential does not exist within the authenticated ownership boundary.
ManagementConflict:
description: The requested tenant name conflicts, the final owned tenant cannot be deleted, or a retained provider credential changed after verification began.
content:
text/plain:
schema:
type: string
ManagementUnsupportedMediaType:
description: A management mutation did not supply application/json.
ProviderKeyRejected:
description: The candidate credential was rejected or cannot access the selected text model. Nothing was saved.
content:
text/plain:
schema:
type: string
const: provider_key_rejected
ProviderKeyVerificationRateLimited:
description: The provider rate-limited the single verification operation. The credential remains unconfirmed and nothing was saved.
content:
text/plain:
schema:
type: string
const: provider_key_verification_rate_limited
ProviderKeyVerificationUnavailable:
description: The provider was unavailable or returned a malformed success envelope. The credential remains unconfirmed and nothing was saved.
content:
text/plain:
schema:
type: string
const: provider_key_verification_unavailable
ProviderKeyVerificationTimedOut:
description: The single verification operation timed out or was canceled. The credential remains unconfirmed and nothing was saved.
content:
text/plain:
schema:
type: string
const: provider_key_verification_timed_out
ManagementInternalError:
description: The management operation failed internally.
content:
text/plain:
schema:
type: string
headers:
ResolvedRequestTimeout:
description: The resolved whole-second budget used for the request.
schema:
type: integer
minimum: 1
x-required: true
OptionalResolvedRequestTimeout:
description: Present after the supplied timeout header passes validation.
schema:
type: integer
minimum: 1
ProxyRequestID:
description: Proxy-owned identifier matching error.request_id and the request_id field in structured proxy logs.
schema:
type: string
minLength: 1
x-required: true
SafeRetryAfter:
description: Present only when the provider supplied a syntactically valid Retry-After value. Delta seconds are normalized to unsigned decimal form and HTTP dates are normalized to IMF-fixdate.
schema:
type: string
minLength: 1
OptionalTokenCount:
description: Provider-reported token count when available.
schema:
type: integer
minimum: 0
NoStore:
description: Prevents persistence of authenticated or secret-bearing responses.
schema:
type: string
const: no-store
x-required: true
StructuredRequestState:
description: Current durable state of the structured request.
schema:
type: string
enum:
- not_dispatched
- dispatched
- succeeded
- failed
- uncertain
x-required: true
OptionalStructuredRequestState:
description: Present when this response belongs to a structured request.
schema:
type: string
enum:
- not_dispatched
- dispatched
- succeeded
- failed
- uncertain
schemas:
AccountConnectionWrite:
type: object
additionalProperties: false
required:
- name
- provider
- fields
properties:
name:
type: string
minLength: 1
maxLength: 80
provider:
type: string
fields:
type: object
additionalProperties:
type: string
version:
type: integer
minimum: 0
description: Use zero or omit on creation. Updates require the current connection version.
AccountConnection:
type: object
additionalProperties: false
required:
- id
- name
- provider
- version
- fields
- tenant_ids
- created_at
- updated_at
properties:
id:
type: string
name:
type: string
provider:
type: string
version:
type: integer
minimum: 1
fields:
type: array
items:
$ref: '#/components/schemas/ProviderField'
tenant_ids:
type: array
items:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
AccountConnections:
type: object
additionalProperties: false
required:
- connections
- providers
- next_cursor
properties:
next_cursor:
type: string
description: The last returned connection ID when another page exists. An empty string indicates the last page.
connections:
type: array
items:
$ref: '#/components/schemas/AccountConnection'
providers:
type: array
items:
$ref: '#/components/schemas/ProviderProfile'
TenantConnectionAssignment:
type: object
additionalProperties: false
required:
- kind
- resource_id
properties:
kind:
$ref: '#/components/schemas/ProviderAssignmentKind'
resource_id:
type: string
minLength: 1
ProviderAssignmentKind:
type: string
enum: [account_connection, hosted_access_grant]
TenantProviderAssignment:
type: object
additionalProperties: false
required: [provider, kind, resource_id]
properties:
provider:
type: string
minLength: 1
kind:
$ref: '#/components/schemas/ProviderAssignmentKind'
resource_id:
type: string
minLength: 1
TenantProviderProfileWrite:
type: object
additionalProperties: false
required:
- text_model
- system_prompt
properties:
text_model:
type: string
minLength: 1
speech_provider:
type: string
description: Selected speech provider. An empty value clears the selection.
speech_model:
type: string
description: Selected speech model. An empty value clears the selection.
system_prompt:
type: string
ConnectionError:
type: object
additionalProperties: false
required:
- error
properties:
error:
type: object
additionalProperties: false
required:
- code
properties:
code:
type: string
MCPRequest:
type: object
additionalProperties: false
required: [jsonrpc, id, method]
properties:
jsonrpc:
type: string
const: '2.0'
id:
type: [string, integer]
method:
type: string
params:
type: object
description: The MCP method defines parameters and required protocol metadata.
MCPResponse:
type: object
additionalProperties: false
required: [jsonrpc, id]
properties:
jsonrpc:
type: string
const: '2.0'
id:
type: [string, integer, 'null']
result:
type: object
error:
type: object
required: [code, message]
properties:
code:
type: integer
message:
type: string
oneOf:
- required: [result]
- required: [error]
MCPGenerateInput:
type: object
additionalProperties: false
required: [tenant_id, messages]
properties:
tenant_id:
type: string
minLength: 1
idempotency_key:
type: string
pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
description: Required for hosted text. Identifies one complete request within its tenant. Customer-owned text rejects this field.
messages:
type: array
minItems: 1
items:
$ref: '#/components/schemas/V2ChatMessage'
provider:
type: string
model:
type: string
web_search:
type: boolean
max_tokens:
type: integer
minimum: 1
reasoning_effort:
type: string
minLength: 1
request_timeout_seconds:
type: integer
minimum: 1
MCPGenerateOutput:
type: object
oneOf:
- $ref: '#/components/schemas/MCPGenerateCompletionOutput'
- $ref: '#/components/schemas/MCPGeneratePendingOutput'
MCPGenerateCompletionOutput:
type: object
additionalProperties: false
required: [text, request_id, provider, model, usage, request_timeout_seconds]
properties:
text:
type: string
request_id:
type: string
provider:
type: string
model:
type: string
usage:
oneOf:
- $ref: '#/components/schemas/TokenUsage'
- type: 'null'
request_timeout_seconds:
type: integer
minimum: 1
MCPGeneratePendingOutput:
type: object
additionalProperties: false
required: [state, request_id, provider, model, request_timeout_seconds]
properties:
state:
type: string
enum: [dispatched]
request_id:
type: string
description: The original hosted execution identifier.
provider:
type: string
model:
type: string
request_timeout_seconds:
type: integer
minimum: 1
ClientFunction:
type: object
additionalProperties: false
required:
- name
- parameters
properties:
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
description:
type: string
parameters:
type: object
strict:
anyOf:
- type: boolean
- type: 'null'
ClientFunctionCall:
type: object
additionalProperties: false
required:
- id
- name
- arguments
properties:
id:
type: string
minLength: 1
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
arguments:
type: string
minLength: 2
ClientToolChoice:
type: object
additionalProperties: false
required:
- mode
properties:
mode:
enum:
- auto
- none
- required
- function
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
OpenAIError:
type: object
additionalProperties: false
required:
- error
properties:
error:
type: object
additionalProperties: false
required:
- message
- type
- param
- code
- request_id
properties:
message:
type: string
type:
enum:
- invalid_request_error
- authentication_error
- rate_limit_error
- server_error
param:
type: 'null'
code:
type: string
request_id:
type: string
minLength: 1
OpenAIModel:
type: object
additionalProperties: false
required:
- id
- object
- created
- owned_by
properties:
id:
type: string
pattern: ^[^/]+/.+$
object:
const: model
created:
type: integer
minimum: 0
owned_by:
type: string
OpenAIModels:
type: object
additionalProperties: false
required:
- object
- data
properties:
object:
const: list
data:
type: array
items:
$ref: '#/components/schemas/OpenAIModel'
OpenAIChatFunctionCall:
type: object
additionalProperties: false
required:
- id
- type
- function
properties:
id:
type: string
minLength: 1
type:
const: function
function:
type: object
additionalProperties: false
required:
- name
- arguments
properties:
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
arguments:
type: string
OpenAIChatTool:
type: object
additionalProperties: false
required:
- type
- function
properties:
type:
const: function
function:
$ref: '#/components/schemas/ClientFunction'
OpenAIResponsesTool:
type: object
additionalProperties: false
required:
- type
- name
- parameters
properties:
type:
const: function
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
description:
type: string
parameters:
type: object
strict:
anyOf:
- type: boolean
- type: 'null'
OpenAIJSONSchema:
type: object
additionalProperties: false
required:
- name
- schema
properties:
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
description:
type: string
schema:
type: object
strict:
anyOf:
- type: boolean
- type: 'null'
OpenAIChatUsage:
type: object
additionalProperties: false
required:
- prompt_tokens
- completion_tokens
- total_tokens
properties:
prompt_tokens:
type: integer
minimum: 0
completion_tokens:
type: integer
minimum: 0
total_tokens:
type: integer
minimum: 0
OpenAIResponsesUsage:
type: object
additionalProperties: false
required:
- input_tokens
- output_tokens
- total_tokens
properties:
input_tokens:
type: integer
minimum: 0
output_tokens:
type: integer
minimum: 0
total_tokens:
type: integer
minimum: 0
input_tokens_details:
type: object
additionalProperties: false
required:
- cached_tokens
properties:
cached_tokens:
type: integer
minimum: 0
output_tokens_details:
type: object
additionalProperties: false
required:
- reasoning_tokens
properties:
reasoning_tokens:
type: integer
minimum: 0
OpenAIChatContent:
anyOf:
- type: string
- type: 'null'
- type: array
items:
type: object
additionalProperties: false
required:
- type
- text
properties:
type:
const: text
text:
type: string
annotations:
type: array
maxItems: 0
logprobs:
type: array
maxItems: 0
OpenAIChatMessage:
type: object
additionalProperties: false
required:
- role
properties:
role:
enum:
- system
- developer
- user
- assistant
- tool
content:
$ref: '#/components/schemas/OpenAIChatContent'
tool_calls:
type: array
items:
$ref: '#/components/schemas/OpenAIChatFunctionCall'
tool_call_id:
type: string
refusal:
type: 'null'
OpenAIChatRequest:
type: object
additionalProperties: false
required:
- model
- messages
properties:
model:
type: string
pattern: ^[^/]+/.+$
messages:
type: array
items:
$ref: '#/components/schemas/OpenAIChatMessage'
minItems: 1
max_tokens:
type: integer
minimum: 1
max_completion_tokens:
type: integer
minimum: 1
reasoning_effort:
type: string
minLength: 1
tools:
type: array
items:
$ref: '#/components/schemas/OpenAIChatTool'
tool_choice:
anyOf:
- enum:
- auto
- none
- required
- type: object
additionalProperties: false
required:
- type
- function
properties:
type:
const: function
function:
type: object
additionalProperties: false
required:
- name
properties:
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
parallel_tool_calls:
type: boolean
stream:
type: boolean
stream_options:
type: object
additionalProperties: false
properties:
include_usage:
type: boolean
store:
const: false
response_format:
oneOf:
- type: object
additionalProperties: false
required:
- type
properties:
type:
const: text
- type: object
additionalProperties: false
required:
- type
- json_schema
properties:
type:
const: json_schema
json_schema:
$ref: '#/components/schemas/OpenAIJSONSchema'
allOf:
- not:
required:
- max_tokens
- max_completion_tokens
- if:
required:
- stream_options
then:
required:
- stream
properties:
stream:
const: true
OpenAIResponseContentPart:
type: object
additionalProperties: false
required:
- type
- text
properties:
type:
enum:
- input_text
- output_text
text:
type: string
annotations:
type: array
maxItems: 0
logprobs:
type: array
maxItems: 0
OpenAIResponseInputItem:
oneOf:
- type: object
additionalProperties: false
required:
- role
- content
properties:
type:
const: message
role:
enum:
- system
- developer
- user
- assistant
content:
anyOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/OpenAIResponseContentPart'
id:
type: string
status:
enum:
- completed
- in_progress
- incomplete
- type: object
additionalProperties: false
required:
- type
- call_id
- name
- arguments
properties:
type:
const: function_call
id:
type: string
status:
enum:
- completed
- in_progress
- incomplete
call_id:
type: string
minLength: 1
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
arguments:
type: string
- type: object
additionalProperties: false
required:
- type
- call_id
- output
properties:
type:
const: function_call_output
id:
type: string
call_id:
type: string
minLength: 1
output:
type: string
OpenAIResponsesRequest:
type: object
additionalProperties: false
required:
- model
- input
properties:
model:
type: string
pattern: ^[^/]+/.+$
input:
anyOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/OpenAIResponseInputItem'
instructions:
type: string
max_output_tokens:
type: integer
minimum: 1
reasoning:
type: object
additionalProperties: false
properties:
effort:
type: string
minLength: 1
summary:
type: 'null'
tools:
type: array
items:
$ref: '#/components/schemas/OpenAIResponsesTool'
tool_choice:
anyOf:
- enum:
- auto
- none
- required
- type: object
additionalProperties: false
required:
- type
- name
properties:
type:
const: function
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
parallel_tool_calls:
type: boolean
stream:
type: boolean
store:
const: false
include:
type: array
maxItems: 0
prompt_cache_key:
type: 'null'
text:
type: object
additionalProperties: false
properties:
verbosity:
type: 'null'
format:
oneOf:
- type: object
additionalProperties: false
required:
- type
properties:
type:
const: text
description:
type: string
- type: object
additionalProperties: false
required:
- type
- name
- schema
properties:
type:
const: json_schema
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
description:
type: string
schema:
type: object
strict:
anyOf:
- type: boolean
- type: 'null'
OpenAIChatCompletion:
type: object
additionalProperties: false
required:
- id
- object
- created
- model
- choices
- usage
properties:
id:
type: string
pattern: ^chatcmpl-
object:
const: chat.completion
created:
type: integer
minimum: 0
model:
type: string
choices:
type: array
items:
type: object
additionalProperties: false
required:
- index
- message
- finish_reason
- logprobs
properties:
index:
type: integer
minimum: 0
message:
$ref: '#/components/schemas/OpenAIChatMessage'
finish_reason:
enum:
- stop
- tool_calls
logprobs:
type: 'null'
usage:
anyOf:
- $ref: '#/components/schemas/OpenAIChatUsage'
- type: 'null'
OpenAIResponseOutputItem:
oneOf:
- type: object
additionalProperties: false
required:
- type
- id
- status
- role
- content
properties:
type:
const: message
id:
type: string
status:
const: completed
role:
const: assistant
content:
type: array
items:
$ref: '#/components/schemas/OpenAIResponseContentPart'
- type: object
additionalProperties: false
required:
- type
- id
- status
- call_id
- name
- arguments
properties:
type:
const: function_call
id:
type: string
status:
const: completed
call_id:
type: string
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
arguments:
type: string
OpenAIResponse:
type: object
additionalProperties: false
required:
- id
- object
- created_at
- completed_at
- status
- model
- output
- error
- incomplete_details
- store
- usage
properties:
id:
type: string
pattern: ^resp_
object:
const: response
created_at:
type: integer
minimum: 0
completed_at:
type: integer
minimum: 0
status:
const: completed
model:
type: string
output:
type: array
items:
$ref: '#/components/schemas/OpenAIResponseOutputItem'
error:
type: 'null'
incomplete_details:
type: 'null'
instructions:
anyOf:
- type: string
- type: 'null'
max_output_tokens:
anyOf:
- type: integer
minimum: 1
- type: 'null'
parallel_tool_calls:
type: boolean
previous_response_id:
type: 'null'
store:
const: false
tools:
type: array
items:
$ref: '#/components/schemas/OpenAIResponsesTool'
tool_choice:
anyOf:
- enum:
- auto
- none
- required
- type: object
additionalProperties: false
required:
- type
- name
properties:
type:
const: function
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
truncation:
const: disabled
metadata:
type: object
additionalProperties: false
properties: {}
usage:
anyOf:
- $ref: '#/components/schemas/OpenAIResponsesUsage'
- type: 'null'
temperature:
type: 'null'
top_p:
type: 'null'
OpenAITranscriptionRequest:
type: object
additionalProperties: false
required:
- model
- file
properties:
model:
type: string
pattern: ^[^/]+/.+$
file:
type: string
format: binary
response_format:
const: json
NativeToolResult:
type: object
additionalProperties: false
required:
- type
- text
- tool_calls
- usage
properties:
type:
const: tool_calls
text:
type: string
tool_calls:
type: array
items:
$ref: '#/components/schemas/ClientFunctionCall'
minItems: 1
usage:
anyOf:
- $ref: '#/components/schemas/TokenUsage'
- type: 'null'
PublicCapabilityCatalog:
type: object
additionalProperties: false
required:
- revision
- operations
- providers
- publishers
- families
- models
- offerings
- prices
- counts
- max_prompt_bytes
- max_input_audio_bytes
- max_request_timeout_seconds
properties:
revision:
type: string
minLength: 1
operations:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicModelOperation'
providers:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicProviderCapability'
publishers:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicModelPublisher'
families:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicModelFamily'
models:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicExactModelCapability'
offerings:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicProviderOffering'
prices:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicPriceDescriptor'
counts:
$ref: '#/components/schemas/PublicCapabilityCounts'
max_prompt_bytes:
type: integer
format: int64
minimum: 1
max_input_audio_bytes:
type: integer
format: int64
minimum: 1
max_request_timeout_seconds:
type: integer
minimum: 1
PublicProviderService:
type: object
additionalProperties: false
required: [operation, controls, limits, price]
properties:
operation:
enum: [audio_alignment, pronunciation_dictionary_creation, video_lipsync, video_translation, avatar_creation, avatar_video_generation]
controls:
type: array
items:
$ref: '#/components/schemas/PublicCatalogControl'
limits:
type: array
items:
$ref: '#/components/schemas/PublicCatalogLimit'
price:
$ref: '#/components/schemas/PublicServicePrice'
PublicServicePrice:
type: object
additionalProperties: false
required:
- operation
- available
- rates
- minimum_charge
- source
- last_verified
- unavailable_reason
properties:
operation:
type: string
enum:
- text
- dictation
- image_generation
- image_editing
- video_generation
- audio_transcription
- audio_diarization
- audio_alignment
- pronunciation_dictionary_creation
- subtitle_creation
- speech_generation
- speech_conversion
- voice_extraction
- video_lipsync
- video_translation
- avatar_creation
- avatar_video_generation
available:
type: boolean
rates:
type: array
items:
$ref: '#/components/schemas/PublicPriceRate'
minimum_charge:
oneOf:
- $ref: '#/components/schemas/PublicMinimumCharge'
- type: 'null'
source:
type: string
format: uri
pattern: '^https://'
last_verified:
type: string
format: date
unavailable_reason:
type: string
PublicProviderCapability:
type: object
additionalProperties: false
required:
- identifier
- label
- credential_kinds
- resources
- services
properties:
services:
type: array
items:
$ref: '#/components/schemas/PublicProviderService'
resources:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/ProviderResourceKind'
identifier:
type: string
minLength: 1
label:
type: string
minLength: 1
credential_kinds:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- api_key
- deployment
PublicModelOperation:
type: object
additionalProperties: false
required:
- id
- input_artifacts
- output_artifacts
properties:
id:
type: string
enum:
- text
- dictation
- image_generation
- image_editing
- video_generation
- audio_transcription
- audio_diarization
- audio_alignment
- pronunciation_dictionary_creation
- subtitle_creation
- speech_generation
- speech_conversion
- voice_extraction
- video_lipsync
- video_translation
- avatar_creation
- avatar_video_generation
input_artifacts:
type: array
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/PublicArtifactKind'
output_artifacts:
type: array
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/PublicArtifactKind'
PublicArtifactKind:
type: string
enum:
- text
- image
- audio
- video
PublicModelPublisher:
type: object
additionalProperties: false
required:
- identifier
- label
- model_count
properties:
identifier:
type: string
minLength: 1
label:
type: string
minLength: 1
model_count:
type: integer
minimum: 1
PublicModelFamily:
type: object
additionalProperties: false
required:
- identifier
- publisher
- label
- weight_access
properties:
identifier:
type: string
minLength: 1
publisher:
type: string
minLength: 1
label:
type: string
minLength: 1
weight_access:
type: string
enum:
- proprietary
- open_weights
PublicCapabilityDomains:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- text
- transcription
- speech
- image
- video
PublicExactModelCapability:
type: object
additionalProperties: false
required:
- identifier
- publisher
- family
- version
- operations
- media_inputs
- capabilities
- provider_offerings
- domains
properties:
identifier:
type: string
minLength: 1
publisher:
type: string
minLength: 1
family:
type: string
minLength: 1
version:
type: string
minLength: 1
operations:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- text
- dictation
- image_generation
- image_editing
- video_generation
- audio_transcription
- audio_diarization
- audio_alignment
- pronunciation_dictionary_creation
- subtitle_creation
- speech_generation
- speech_conversion
- voice_extraction
- video_lipsync
- video_translation
- avatar_creation
- avatar_video_generation
media_inputs:
type: array
uniqueItems: true
items:
type: string
enum:
- image
- audio
capabilities:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- text
- dictation
- caller_tools
- web_search
- image_input
- audio_input
- reasoning
- image_generation
- image_editing
- video_generation
- audio_transcription
- audio_diarization
- audio_alignment
- pronunciation_dictionary_creation
- subtitle_creation
- speech_generation
- speech_conversion
- voice_extraction
- video_lipsync
- video_translation
- avatar_creation
- avatar_video_generation
provider_offerings:
type: array
minItems: 1
uniqueItems: true
items:
type: string
minLength: 1
domains:
$ref: '#/components/schemas/PublicCapabilityDomains'
PublicProviderOffering:
type: object
additionalProperties: false
allOf:
- if:
properties:
capabilities:
contains:
enum:
- image_input
- audio_input
then:
required:
- media_execution_lifecycle
else:
not:
required:
- media_execution_lifecycle
required:
- identifier
- provider
- model
- capabilities
- wire_contract
- execution_lifecycle
- output_token_limit
- reasoning_efforts
- controls
- limits
- media_limits
- domains
properties:
identifier:
type: string
minLength: 1
provider:
type: string
minLength: 1
model:
type: string
minLength: 1
image_mime_types:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum: [image/jpeg, image/png, image/webp]
description: Explicit image formats for this offering. Omission uses the protocol adapter formats.
capabilities:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- text
- dictation
- caller_tools
- web_search
- image_input
- audio_input
- reasoning
- image_generation
- image_editing
- video_generation
- audio_transcription
- audio_diarization
- audio_alignment
- pronunciation_dictionary_creation
- subtitle_creation
- speech_generation
- speech_conversion
- voice_extraction
- video_lipsync
- video_translation
- avatar_creation
- avatar_video_generation
wire_contract:
type: string
minLength: 1
execution_lifecycle:
type: string
enum:
- synchronous_completion
- pollable_resource
- asynchronous_job
media_execution_lifecycle:
type: string
enum:
- synchronous_completion
- pollable_resource
- asynchronous_job
output_token_limit:
type: integer
minimum: 0
reasoning_efforts:
type: array
uniqueItems: true
items:
type: string
minLength: 1
controls:
type: array
items:
$ref: '#/components/schemas/PublicCatalogControl'
limits:
type: array
items:
$ref: '#/components/schemas/PublicCatalogLimit'
media_limits:
type: array
items:
$ref: '#/components/schemas/PublicCatalogMediaLimit'
domains:
$ref: '#/components/schemas/PublicCapabilityDomains'
PublicCatalogControl:
type: object
additionalProperties: false
required:
- id
- kind
- values
- minimum
- maximum
- account_dependent
properties:
id:
type: string
minLength: 1
kind:
type: string
enum:
- enum
- integer
- number
- boolean
- image_size
values:
type: array
uniqueItems: true
items:
type: string
minLength: 1
minimum:
oneOf:
- type: number
- type: 'null'
maximum:
oneOf:
- type: number
- type: 'null'
account_dependent:
type: boolean
image_size:
$ref: '#/components/schemas/PublicImageSizeConstraints'
allOf:
- if:
properties:
kind:
enum: [integer, number]
then:
properties:
minimum:
type: number
maximum:
type: number
values:
maxItems: 0
else:
properties:
minimum:
type: 'null'
maximum:
type: 'null'
- if:
properties:
kind:
const: integer
then:
properties:
minimum:
type: integer
minimum: 0
maximum:
type: integer
minimum: 0
- if:
properties:
kind:
const: image_size
then:
required: [image_size]
else:
not:
required: [image_size]
PublicImageSizeConstraints:
type: object
additionalProperties: false
required: [automatic, dimension_multiple, maximum_edge, minimum_pixels, maximum_pixels, maximum_aspect_ratio]
properties:
automatic:
type: boolean
dimension_multiple:
type: integer
minimum: 1
maximum_edge:
type: integer
minimum: 1
maximum: 32768
minimum_pixels:
type: integer
minimum: 1
maximum_pixels:
type: integer
minimum: 1
maximum_aspect_ratio:
type: integer
minimum: 1
PublicCatalogLimit:
type: object
additionalProperties: false
required:
- id
- value
- unit
- account_dependent
properties:
id:
type: string
minLength: 1
value:
oneOf:
- type: integer
minimum: 0
- type: 'null'
unit:
type: string
minLength: 1
account_dependent:
type: boolean
PublicCatalogMediaLimit:
type: object
additionalProperties: false
required:
- id
- media_type
- transport
- status
- value
- unit
- scope
- source
- last_verified
properties:
id:
type: string
minLength: 1
media_type:
type: string
enum:
- all
- image
- audio
transport:
type: string
enum:
- any
- inline
- file
status:
type: string
enum:
- bounded
- unbounded
- unknown
value:
oneOf:
- type: integer
minimum: 1
- type: 'null'
unit:
type: string
enum:
- bytes
- files
- pixels
scope:
type: string
enum:
- attachment
- attachment_encoded_bytes
- attachment_data_uri_bytes
- request
- request_encoded_bytes
source:
type: string
format: uri
pattern: '^https://'
last_verified:
type: string
format: date
PublicPriceDescriptor:
type: object
additionalProperties: false
required:
- provider
- model
- operation
- available
- rates
- minimum_charge
- source
- last_verified
- unavailable_reason
properties:
provider:
type: string
minLength: 1
model:
type: string
minLength: 1
operation:
type: string
enum:
- text
- dictation
- image_generation
- image_editing
- video_generation
- audio_transcription
- audio_diarization
- audio_alignment
- pronunciation_dictionary_creation
- subtitle_creation
- speech_generation
- speech_conversion
- voice_extraction
- video_lipsync
- video_translation
- avatar_creation
- avatar_video_generation
available:
type: boolean
rates:
type: array
items:
$ref: '#/components/schemas/PublicPriceRate'
minimum_charge:
oneOf:
- $ref: '#/components/schemas/PublicMinimumCharge'
- type: 'null'
source:
type: string
format: uri
pattern: '^https://'
last_verified:
type: string
format: date
unavailable_reason:
type: string
ExactMoney:
type: object
additionalProperties: false
description: An exact nonnegative USD amount expressed as a reduced fraction.
required: [numerator, denominator]
properties:
numerator: {type: string, pattern: '^(0|[1-9][0-9]*)$', maxLength: 512}
denominator: {type: string, pattern: '^[1-9][0-9]*$', maxLength: 512}
NullableExactMoney:
oneOf:
- $ref: '#/components/schemas/ExactMoney'
- type: 'null'
RatedLine:
type: object
additionalProperties: false
required: [dimension, component, quantity, quantity_unit, provider_rate, customer_rate, rate_unit, conditions, provider_cost, customer_charge]
properties:
dimension: {type: string}
component: {type: string}
quantity:
$ref: '#/components/schemas/ExactNonnegativeDecimal'
quantity_unit: {type: string}
provider_rate:
$ref: '#/components/schemas/ExactNonnegativeDecimal'
customer_rate:
$ref: '#/components/schemas/ExactMoney'
rate_unit: {type: string}
conditions:
$ref: '#/components/schemas/PublicPriceConditions'
provider_cost:
$ref: '#/components/schemas/ExactMoney'
customer_charge:
$ref: '#/components/schemas/ExactMoney'
RatedUsage:
type: object
additionalProperties: false
description: The exact calculation under the accepted prices. Charge state controls settlement eligibility.
required: [state, lines, provider_cost, customer_charge, minimum_adjustment, unresolved_dimensions]
properties:
state: {type: string, enum: [resolved, unresolved]}
lines:
type: array
items:
$ref: '#/components/schemas/RatedLine'
provider_cost:
$ref: '#/components/schemas/NullableExactMoney'
customer_charge:
$ref: '#/components/schemas/NullableExactMoney'
minimum_adjustment:
$ref: '#/components/schemas/NullableExactMoney'
unresolved_dimensions:
type: array
items: {type: string}
FundsReservationPage:
type: object
additionalProperties: false
required: [reservations, next_cursor]
properties:
reservations:
type: array
items:
$ref: '#/components/schemas/HostedFundsReservation'
next_cursor: {type: string}
HostedFundsReservation:
type: object
additionalProperties: false
required: [id, currency, maximum_cents, state, revision, created_at, updated_at]
properties:
id: {type: string, pattern: '^request-[a-f0-9]{32}$', description: The request identifier also identifies its reservation.}
currency: {type: string, enum: [USD]}
maximum_cents: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
state: {type: string, enum: [held, settled, released, reconciliation_required]}
revision: {type: integer, minimum: 1}
created_at: {type: string, format: date-time}
updated_at: {type: string, format: date-time}
FundsEntryPage:
type: object
additionalProperties: false
required: [entries, next_cursor]
properties:
entries:
type: array
items:
$ref: '#/components/schemas/HostedFundsEntry'
next_cursor: {type: string}
HostedFundsEntry:
type: object
additionalProperties: false
required: [id, currency, type, amount_cents, reservation_id, refund_of_entry_id, created_at]
properties:
id: {type: string}
currency: {type: string, enum: [USD]}
type: {type: string, enum: [grant, hold, reverse_hold, spend, refund]}
amount_cents: {type: string, pattern: '^(0|-?[1-9][0-9]*)$'}
reservation_id: {type: [string, 'null']}
refund_of_entry_id: {type: [string, 'null']}
created_at: {type: string, format: date-time}
HostedFundsReservationDetail:
type: object
additionalProperties: false
required: [id, currency, maximum_cents, state, revision, created_at, updated_at, authorized_maximum, resolution_charge_limit, known_provider_cost, known_platform_exposure, provider_cost_complete]
properties:
id: {type: string, pattern: '^request-[a-f0-9]{32}$'}
currency: {type: string, enum: [USD]}
maximum_cents: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
state: {type: string, enum: [held, settled, released, reconciliation_required]}
revision: {type: integer, minimum: 1}
created_at: {type: string, format: date-time}
updated_at: {type: string, format: date-time}
authorized_maximum:
$ref: '#/components/schemas/ExactMoney'
resolution_charge_limit:
$ref: '#/components/schemas/ExactMoney'
description: Upper limit for an operator charge after known pricing and prior credits. The decision also requires a current reservation revision.
known_provider_cost:
$ref: '#/components/schemas/ExactMoney'
description: Sum of retained provider costs from fully rated attempts. Missing costs are excluded, not treated as known zero costs.
known_platform_exposure:
$ref: '#/components/schemas/ExactMoney'
description: Known provider costs above the exact request authorization. This lower bound does not change the customer charge.
provider_cost_complete:
type: boolean
description: True when execution is terminal and all attempts have retained known costs.
HostedFundsResolution:
type: object
additionalProperties: false
required: [request_id, currency, customer_charge, settled_cents, reason, created_at]
properties:
request_id: {type: string, pattern: '^request-[a-f0-9]{32}$'}
currency: {type: string, enum: [USD]}
customer_charge:
$ref: '#/components/schemas/ExactMoney'
settled_cents: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
reason: {type: string, pattern: '^[a-z][a-z0-9_]{0,63}$'}
created_at: {type: string, format: date-time}
HostedFundsCredit:
type: object
additionalProperties: false
required: [id, request_id, currency, credit, credited_cents, reason, created_at]
properties:
id: {type: string, minLength: 1, maxLength: 128}
request_id: {type: string, pattern: '^request-[a-f0-9]{32}$'}
currency: {type: string, enum: [USD]}
credit:
$ref: '#/components/schemas/ExactMoney'
credited_cents: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
reason: {type: string, pattern: '^[a-z][a-z0-9_]{0,63}$'}
created_at: {type: string, format: date-time}
HostedTenantFundsLimit:
type: object
additionalProperties: false
required: [tenant_id, currency, limit_cents, remaining_cents, reserved_cents, spent, revision]
properties:
tenant_id: {type: string}
currency: {type: string, enum: [USD]}
limit_cents: {type: [string, 'null'], pattern: '^(0|[1-9][0-9]*)$'}
remaining_cents:
type: [string, 'null']
pattern: '^(0|[1-9][0-9]*)$'
description: Whole cents permitted for new reservations, after net usage and active holds. Null means no tenant limit.
reserved_cents: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
spent:
$ref: '#/components/schemas/ExactMoney'
description: Cumulative net settled usage in USD, including fractional cents and customer credits.
revision: {type: integer, minimum: 0}
HostedFundsBalance:
type: object
additionalProperties: false
required: [currency, state, posted_cents, available_cents, reserved_cents, spent_cents, pending_cents, unsettled_fraction]
properties:
currency:
type: string
enum: [USD]
state:
type: string
enum: [active, suspended, reconciliation_required]
posted_cents:
type: string
pattern: '^-?(0|[1-9][0-9]*)$'
description: Net posted credits and debits, before active reservations.
available_cents:
type: string
pattern: '^-?(0|[1-9][0-9]*)$'
description: Posted cents minus reserved cents.
reserved_cents:
type: string
pattern: '^(0|[1-9][0-9]*)$'
description: Total active Ledger holds, including pending reconciliation.
spent_cents:
type: string
pattern: '^(0|[1-9][0-9]*)$'
description: Cumulative settled usage debits before compensating credits.
pending_cents:
type: string
pattern: '^(0|[1-9][0-9]*)$'
description: Reserved cents awaiting financial reconciliation. This amount is part of reserved cents.
unsettled_fraction:
$ref: '#/components/schemas/ExactMoney'
description: Accumulated usage charge in USD below one cent, retained for later settlement.
HostedCharge:
type: object
additionalProperties: false
required: [id, request_id, attempt_id, observation_id, price_snapshot_id, state, rating, customer_charge, net_customer_charge, customer_adjustments, created_at]
properties:
id: {type: string}
request_id: {type: string}
attempt_id: {type: string}
observation_id: {type: string}
price_snapshot_id: {type: string}
state: {type: string, enum: [rated, usage_unresolved, policy_unresolved, limit_unresolved]}
rating:
$ref: '#/components/schemas/RatedUsage'
customer_charge:
$ref: '#/components/schemas/NullableExactMoney'
net_customer_charge:
$ref: '#/components/schemas/NullableExactMoney'
customer_adjustments:
type: array
items:
$ref: '#/components/schemas/CustomerChargeAdjustment'
created_at: {type: string, format: date-time}
CustomerChargeAdjustment:
type: object
additionalProperties: false
required: [id, credit, reason, created_at]
properties:
id: {type: string}
credit:
$ref: '#/components/schemas/ExactMoney'
reason: {type: string}
created_at: {type: string, format: date-time}
RequestChargeSummary:
type: object
additionalProperties: false
required: [request_id, state, attempt_count, charge_count, provider_cost, customer_charge, customer_credits, net_customer_charge]
properties:
request_id: {type: string}
state:
type: string
enum: [pending, unresolved, rated]
description: Pending requests await completion, result publication, or charge delivery. Unresolved requests lack required usage or policy decisions.
attempt_count: {type: integer, minimum: 0}
charge_count: {type: integer, minimum: 0}
provider_cost:
description: The complete provider cost, when known. Customer credits do not change this amount.
anyOf:
- $ref: '#/components/schemas/ExactMoney'
- type: 'null'
customer_charge:
description: The total customer charge before credits. Only rated requests have this amount.
anyOf:
- $ref: '#/components/schemas/ExactMoney'
- type: 'null'
customer_credits:
description: The total customer credits. Only rated requests have this amount.
anyOf:
- $ref: '#/components/schemas/ExactMoney'
- type: 'null'
net_customer_charge:
description: The customer charge after credits. Only rated requests have this amount.
anyOf:
- $ref: '#/components/schemas/ExactMoney'
- type: 'null'
ChargePage:
type: object
additionalProperties: false
required: [charges, next_cursor]
properties:
charges:
type: array
maxItems: 100
items:
$ref: '#/components/schemas/HostedCharge'
next_cursor: {type: string}
PriceUsageBound:
type: object
additionalProperties: false
required: [dimension, unit, maximum]
properties:
dimension: {type: string}
unit: {type: string}
maximum:
$ref: '#/components/schemas/ExactNonnegativeDecimal'
AuthorizedPriceMaximum:
type: object
additionalProperties: false
required: [attempts, customer_charge, reserved_cents]
properties:
attempts: {type: integer, minimum: 1, maximum: 4294967295}
customer_charge:
$ref: '#/components/schemas/ExactMoney'
reserved_cents: {type: string, pattern: '^(0|[1-9][0-9]*)$', maxLength: 19}
AcceptedPriceRate:
type: object
additionalProperties: false
required: [provider_rate, customer_rate]
properties:
provider_rate:
$ref: '#/components/schemas/PublicPriceRate'
customer_rate:
$ref: '#/components/schemas/ExactMoney'
AcceptedPriceOrigin:
type: object
additionalProperties: false
required: [provider, model, operation, source, last_verified]
properties:
provider: {type: string, minLength: 1}
model: {type: string, minLength: 1, maxLength: 128}
operation: {type: string, enum: [text, image_generation, image_editing]}
source: {type: string, format: uri}
last_verified: {type: string, format: date}
AcceptedPriceComponent:
type: object
additionalProperties: false
required: [dimension, additional_dimension, rates]
properties:
origin:
$ref: '#/components/schemas/AcceptedPriceOrigin'
dimension: {type: string}
additional_dimension: {type: string}
rates:
type: array
minItems: 1
items:
$ref: '#/components/schemas/AcceptedPriceRate'
AcceptedPrices:
type: object
additionalProperties: false
required: [catalog_revision, provider, model, operation, source, last_verified, markup, components, excluded_components, zero_dimensions, minimum_charge, bounds, maximum]
properties:
catalog_revision: {type: string}
provider: {type: string}
model: {type: string}
operation: {type: string}
source: {type: string, format: uri}
last_verified: {type: string, format: date}
markup:
$ref: '#/components/schemas/ExactMoney'
components:
type: array
minItems: 1
items:
$ref: '#/components/schemas/AcceptedPriceComponent'
excluded_components:
type: array
uniqueItems: true
items: {type: string, enum: [cache_storage, web_search_calls]}
zero_dimensions:
type: array
uniqueItems: true
items: {type: string}
minimum_charge:
oneOf:
- $ref: '#/components/schemas/PublicMinimumCharge'
- type: 'null'
bounds:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PriceUsageBound'
maximum:
$ref: '#/components/schemas/AuthorizedPriceMaximum'
HostedPriceSnapshot:
type: object
additionalProperties: false
required: [id, request_id, snapshot, created_at]
properties:
id: {type: string}
request_id: {type: string}
snapshot:
$ref: '#/components/schemas/AcceptedPrices'
created_at: {type: string, format: date-time}
ExactNonnegativeDecimal:
type: string
minLength: 1
maxLength: 128
pattern: '^(0|[1-9][0-9]*)(\.[0-9]*[1-9])?$'
description: Exact decimal amount without an exponent, leading zeros, or trailing fractional zeros.
PublicPriceRate:
type: object
additionalProperties: false
required:
- component
- currency
- rate
- unit
- conditions
properties:
component:
type: string
minLength: 1
currency:
type: string
const: USD
rate:
$ref: '#/components/schemas/ExactNonnegativeDecimal'
unit:
type: string
minLength: 1
conditions:
$ref: '#/components/schemas/PublicPriceConditions'
PublicMinimumCharge:
type: object
additionalProperties: false
required:
- currency
- amount
- unit
properties:
currency:
type: string
const: USD
amount:
$ref: '#/components/schemas/ExactNonnegativeDecimal'
unit:
type: string
minLength: 1
PriceTokenRange:
type: object
additionalProperties: false
description: The minimum is inclusive. A nonzero maximum is exclusive. Zero maximum means unbounded. An unresolved boundary prevents paid admission.
required: [minimum, maximum_exclusive, unresolved_reason]
properties:
minimum: {type: string, pattern: '^(0|[1-9][0-9]*)$', maxLength: 20}
maximum_exclusive: {type: string, pattern: '^(0|[1-9][0-9]*)$', maxLength: 20}
unresolved_reason: {type: string}
PublicPriceConditions:
type: object
additionalProperties: false
required:
- input_tokens
- cache_class
- service_tier
- region
- effective_from
- effective_until
- resolution
- generated_audio
- input_media
- output_media
- duration
- quantity
- quality
- mode
- api_version
- avatar_type
- billing_mode
- billing_outcome
properties:
input_tokens:
$ref: '#/components/schemas/PriceTokenRange'
cache_class: {type: string, enum: ['', read, write, write_5m, write_1h, storage]}
service_tier: {type: string, enum: ['', standard, priority, batch, flex, fast]}
region: {type: string}
effective_from: {type: string}
effective_until: {type: string}
resolution: {type: string}
generated_audio: {type: string}
input_media: {type: string}
output_media: {type: string}
duration: {type: string}
quantity: {type: string}
quality: {type: string}
mode: {type: string}
api_version: {type: string}
avatar_type: {type: string}
billing_mode: {type: string}
billing_outcome: {type: string}
PublicCapabilityCounts:
type: object
additionalProperties: false
required:
- providers
- model_publishers
- model_families
- exact_models
- provider_offerings
properties:
providers:
type: integer
minimum: 1
model_publishers:
type: integer
minimum: 1
model_families:
type: integer
minimum: 1
exact_models:
type: integer
minimum: 1
provider_offerings:
type: integer
minimum: 1
ChatMessage:
type: object
additionalProperties: false
required:
- role
- content
properties:
role:
type: string
enum:
- system
- user
- assistant
content:
type: string
minLength: 1
order:
type: integer
minimum: 0
MessageAttachment:
description: One provider-neutral image or audio input with a MIME type that matches its declared media type. The resolved catalog route determines support. Current Moonshot Kimi image routes accept the image variants.
oneOf:
- $ref: '#/components/schemas/ImageMessageAttachment'
- $ref: '#/components/schemas/AudioMessageAttachment'
- $ref: '#/components/schemas/ImageAssetMessageAttachment'
- $ref: '#/components/schemas/AudioAssetMessageAttachment'
ImageMessageAttachment:
type: object
additionalProperties: false
required:
- type
- mime_type
- data
properties:
type:
type: string
const: image
mime_type:
type: string
enum:
- image/jpeg
- image/png
- image/webp
data:
type: string
minLength: 4
description: Exact nonempty media bytes encoded as canonical padded RFC 4648 base64.
AudioMessageAttachment:
type: object
additionalProperties: false
required:
- type
- mime_type
- data
properties:
type:
type: string
const: audio
mime_type:
type: string
enum:
- audio/m4a
- audio/mpeg
- audio/wav
data:
type: string
minLength: 4
description: Exact nonempty media bytes encoded as canonical padded RFC 4648 base64.
ImageAssetMessageAttachment:
type: object
additionalProperties: false
required:
- type
- mime_type
- asset_id
properties:
type:
type: string
const: image
mime_type:
type: string
enum:
- image/jpeg
- image/png
- image/webp
asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
AudioAssetMessageAttachment:
type: object
additionalProperties: false
required:
- type
- mime_type
- asset_id
properties:
type:
type: string
const: audio
mime_type:
type: string
enum:
- audio/m4a
- audio/mpeg
- audio/wav
asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
ProviderMetadata:
type: object
additionalProperties: false
required: [provider, models]
properties:
provider: {type: string, minLength: 1}
models:
type: array
items:
$ref: '#/components/schemas/ProviderModelMetadata'
ProviderModelMetadata:
type: object
additionalProperties: false
required: [model_id, name, can_do_text_to_speech, can_do_voice_conversion, maximum_text_length_per_request, max_characters_request_free_user, max_characters_request_subscribed_user]
properties:
model_id: {type: string, minLength: 1}
name: {type: string, minLength: 1}
can_do_text_to_speech: {type: [boolean, 'null']}
can_do_voice_conversion: {type: [boolean, 'null']}
maximum_text_length_per_request: {type: [integer, 'null'], minimum: 0}
max_characters_request_free_user: {type: [integer, 'null'], minimum: 0}
max_characters_request_subscribed_user: {type: [integer, 'null'], minimum: 0}
ProviderQuotas:
type: object
additionalProperties: false
required: [provider, subscription]
properties:
provider: {type: string, minLength: 1}
subscription:
$ref: '#/components/schemas/ProviderSubscription'
ProviderSubscription:
type: object
additionalProperties: false
required: [tier, status, character_count, character_limit, credit_extension, can_extend_credit_limit, current_overage, has_open_invoices, currency, next_character_count_reset_unix]
properties:
tier: {type: string, minLength: 1}
status: {type: string, minLength: 1}
character_count: {type: integer, minimum: 0}
character_limit: {type: integer, minimum: 0}
credit_extension:
$ref: '#/components/schemas/ProviderCreditExtension'
can_extend_credit_limit: {type: boolean}
has_open_invoices: {type: boolean}
currency: {type: [string, 'null'], minLength: 1}
next_character_count_reset_unix: {type: [integer, 'null'], minimum: 0}
current_overage:
oneOf:
- type: 'null'
- type: object
additionalProperties: false
required: [amount, currency]
properties:
amount: {type: string, pattern: '^[0-9]+(\.[0-9]+)?$'}
currency: {type: string, minLength: 1}
ProviderCreditExtension:
type: object
additionalProperties: false
required: [unlimited, value]
properties:
unlimited: {type: boolean}
value: {type: [integer, 'null'], minimum: 0}
oneOf:
- properties:
unlimited: {const: true}
value: {type: 'null'}
- properties:
unlimited: {const: false}
value: {type: integer, minimum: 0}
ProviderResourceKind:
type: string
enum: [voices, voice_library, history, pronunciation_dictionaries, metadata, quotas, elements, account]
ProviderResource:
type: object
additionalProperties: false
required: [provider, kind]
properties:
provider:
type: string
minLength: 1
kind:
$ref: '#/components/schemas/ProviderResourceKind'
MediaCapabilityService:
type: object
additionalProperties: false
required: [capability, provider, controls, limits]
properties:
capability:
enum: [audio.align, audio.dictionary.create, video.lipsync, video.translate, avatar.create, avatar.video.generate]
provider:
type: string
minLength: 1
controls:
type: array
items:
$ref: '#/components/schemas/PublicCatalogControl'
limits:
type: array
items:
$ref: '#/components/schemas/PublicCatalogLimit'
MediaCapabilities:
type: object
additionalProperties: false
required: [catalog_revision, routes, resources, services]
properties:
services:
type: array
items:
$ref: '#/components/schemas/MediaCapabilityService'
resources:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/ProviderResource'
catalog_revision:
type: string
minLength: 1
routes:
type: array
items:
type: object
additionalProperties: false
required: [capability, provider, model, controls, limits]
properties:
capability:
type: string
minLength: 1
provider:
type: string
minLength: 1
model:
type: string
minLength: 1
controls:
type: array
items:
type: object
limits:
type: array
items:
type: object
MediaOperationRequest:
oneOf:
- $ref: '#/components/schemas/VideoLipSyncOperationRequest'
- $ref: '#/components/schemas/VideoTranslationOperationRequest'
- $ref: '#/components/schemas/AvatarCreationOperationRequest'
- $ref: '#/components/schemas/AvatarVideoOperationRequest'
- $ref: '#/components/schemas/ImageGenerationOperationRequest'
- $ref: '#/components/schemas/ImageEditingOperationRequest'
- $ref: '#/components/schemas/VideoGenerationOperationRequest'
- $ref: '#/components/schemas/DictatorTranscriptionOperationRequest'
- $ref: '#/components/schemas/DictatorDiarizationOperationRequest'
- $ref: '#/components/schemas/DictatorAlignmentOperationRequest'
- $ref: '#/components/schemas/ProviderAlignmentOperationRequest'
- $ref: '#/components/schemas/ProviderDictionaryOperationRequest'
- $ref: '#/components/schemas/DictatorSubtitleOperationRequest'
- $ref: '#/components/schemas/ProviderSpeechConversionOperationRequest'
- $ref: '#/components/schemas/ProviderSpeechGenerationOperationRequest'
- $ref: '#/components/schemas/DictatorSpeechGenerationOperationRequest'
- $ref: '#/components/schemas/DictatorVoiceExtractionOperationRequest'
discriminator:
propertyName: capability
VideoLipSyncOperationRequest:
type: "object"
additionalProperties: false
required: ["capability", "provider", "input", "controls"]
properties:
capability:
const: "video.lipsync"
provider:
type: "string"
pattern: "\\S"
input:
type: "object"
additionalProperties: false
required: ["video_asset_id", "audio_asset_id"]
properties:
video_asset_id:
type: "string"
pattern: "^ast_[0-9a-f]{32}$"
audio_asset_id:
type: "string"
pattern: "^ast_[0-9a-f]{32}$"
controls:
type: "object"
additionalProperties: false
required: ["mode"]
properties:
mode:
enum: ["speed", "precision"]
title:
type: "string"
maxLength: 1000
fps_mode:
enum: ["vfr", "cfr", "passthrough"]
start_time:
type: "number"
minimum: 0
maximum: 36000
end_time:
type: "number"
minimum: 0
maximum: 36000
disable_music_track:
type: "boolean"
enable_dynamic_duration:
type: "boolean"
enable_speech_enhancement:
type: "boolean"
enable_watermark:
type: "boolean"
keep_the_same_format:
type: "boolean"
VideoTranslationOperationRequest:
type: "object"
additionalProperties: false
required: ["capability", "provider", "input", "controls"]
properties:
capability:
const: "video.translate"
provider:
type: "string"
pattern: "\\S"
input:
type: "object"
additionalProperties: false
required: ["video_asset_id"]
properties:
video_asset_id:
type: "string"
pattern: "^ast_[0-9a-f]{32}$"
audio_asset_id:
type: "string"
pattern: "^ast_[0-9a-f]{32}$"
controls:
type: "object"
additionalProperties: false
required: ["mode", "output_languages"]
properties:
mode:
enum: ["speed", "precision"]
title:
type: "string"
maxLength: 1000
fps_mode:
enum: ["vfr", "cfr", "passthrough"]
start_time:
type: "number"
minimum: 0
maximum: 36000
end_time:
type: "number"
minimum: 0
maximum: 36000
disable_music_track:
type: "boolean"
enable_dynamic_duration:
type: "boolean"
enable_speech_enhancement:
type: "boolean"
enable_watermark:
type: "boolean"
keep_the_same_format:
type: "boolean"
output_languages:
type: "array"
minItems: 1
maxItems: 20
uniqueItems: true
items:
type: "string"
maxLength: 100
pattern: "\\S"
input_language:
type: "string"
maxLength: 100
pattern: "\\S"
speaker_num:
type: "integer"
minimum: 0
maximum: 100
translate_audio_only:
type: "boolean"
allOf:
- if:
properties:
controls:
required: [fps_mode]
then:
properties:
input:
required: [audio_asset_id]
AvatarCreationOperationRequest:
type: "object"
additionalProperties: false
required: ["capability", "provider", "input", "controls"]
properties:
capability:
const: "avatar.create"
provider:
type: "string"
pattern: "\\S"
input:
type: "object"
additionalProperties: false
required: ["name", "image_asset_id"]
properties:
name:
type: "string"
pattern: "\\S"
image_asset_id:
type: "string"
pattern: "^ast_[0-9a-f]{32}$"
controls:
type: "object"
additionalProperties: false
required: []
properties: {}
AvatarVideoOperationRequest:
type: "object"
additionalProperties: false
required: ["capability", "provider", "input", "controls"]
properties:
capability:
const: "avatar.video.generate"
provider:
type: "string"
pattern: "\\S"
input:
type: "object"
additionalProperties: false
required: ["avatar_id", "audio_asset_id"]
properties:
avatar_id:
type: "string"
pattern: "^ava_[0-9a-f]{32}$"
audio_asset_id:
type: "string"
pattern: "^ast_[0-9a-f]{32}$"
controls:
type: "object"
additionalProperties: false
required: ["engine", "aspect_ratio", "resolution"]
properties:
engine:
const: "avatar_iv"
aspect_ratio:
enum: ["16:9", "9:16", "1:1"]
resolution:
enum: ["720p", "1080p"]
title:
type: "string"
motion_prompt:
type: "string"
expressiveness:
enum: ["high", "medium", "low"]
MediaAvatar:
type: "object"
additionalProperties: false
required: ["avatar_id", "provider", "name"]
properties:
avatar_id:
type: "string"
pattern: "^ava_[0-9a-f]{32}$"
provider:
type: "string"
pattern: "\\S"
name:
type: "string"
pattern: "\\S"
ProviderAccount:
type: "object"
additionalProperties: false
required: ["provider", "billing_type", "wallet", "subscription", "usage_based"]
properties:
provider:
type: "string"
pattern: "\\S"
billing_type:
enum: ["wallet", "subscription", "usage_based"]
wallet:
type: ["object", "null"]
additionalProperties: false
required: ["currency"]
properties:
currency:
enum: ["usd", "credits"]
remaining_balance:
type: ["number", "null"]
auto_reload:
type: ["object", "null"]
additionalProperties: false
required: ["enabled"]
properties:
enabled:
type: "boolean"
amount_usd:
type: ["number", "null"]
threshold_usd:
type: ["number", "null"]
subscription:
type: ["object", "null"]
additionalProperties: false
required: ["plan", "credits"]
properties:
plan:
type: "string"
pattern: "\\S"
credits:
type: "object"
additionalProperties: false
required: []
properties:
premium_credits:
type: ["object", "null"]
additionalProperties: false
required: []
properties:
remaining:
type: ["integer", "null"]
resets_at:
type: ["string", "null"]
add_on_credits:
type: ["object", "null"]
additionalProperties: false
required: []
properties:
remaining:
type: ["integer", "null"]
resets_at:
type: ["string", "null"]
usage_based:
type: ["object", "null"]
additionalProperties: false
required: []
properties:
included_credits:
type: ["number", "null"]
remaining_credits:
type: ["number", "null"]
spending_cap_usd:
type: ["number", "null"]
spending_current_usd:
type: ["number", "null"]
oneOf:
- {"properties": {"billing_type": {"const": "wallet"}, "wallet": {"type": "object"}, "subscription": {"type": "null"}, "usage_based": {"type": "null"}}}
- {"properties": {"billing_type": {"const": "subscription"}, "wallet": {"type": "null"}, "subscription": {"type": "object"}, "usage_based": {"type": "null"}}}
- {"properties": {"billing_type": {"const": "usage_based"}, "wallet": {"type": "null"}, "subscription": {"type": "null"}, "usage_based": {"type": "object"}}}
ProviderDictionaryOperationRequest:
type: object
additionalProperties: false
required: [capability, provider, input, controls]
properties:
capability:
const: audio.dictionary.create
provider:
type: string
minLength: 1
input:
$ref: '#/components/schemas/PronunciationDictionaryInput'
controls:
type: object
additionalProperties: false
PronunciationDictionaryInput:
type: object
additionalProperties: false
required: [name, rules]
properties:
name:
type: string
pattern: '\S'
description:
type: [string, 'null']
rules:
type: array
minItems: 1
items:
oneOf:
- type: object
additionalProperties: false
required: [type, string_to_replace, alias]
properties:
type: {const: alias}
string_to_replace: {type: string, pattern: '\S'}
alias: {type: string, pattern: '\S'}
- type: object
additionalProperties: false
required: [type, string_to_replace, phoneme, alphabet]
properties:
type: {const: phoneme}
string_to_replace: {type: string, pattern: '\S'}
phoneme: {type: string, pattern: '\S'}
alphabet: {type: string, pattern: '\S'}
MediaDictionary:
type: object
additionalProperties: false
description: The creation artifact contains owned references and provider observations. Native dictionary and version identifiers remain private.
required: [dictionary_id, version_id, provider, name, created_by, creation_time_unix, version_rules_num, permission_on_resource, description]
properties:
dictionary_id: {type: string, pattern: '^dic_[0-9a-f]{32}$'}
version_id: {type: string, pattern: '^div_[0-9a-f]{32}$'}
provider: {type: string, minLength: 1}
name: {type: string, pattern: '\S'}
created_by: {type: string}
creation_time_unix: {type: integer, minimum: 0}
version_rules_num: {type: integer, minimum: 0}
permission_on_resource: {type: [string, 'null']}
description: {type: [string, 'null']}
ProviderAlignmentOperationRequest:
type: object
additionalProperties: false
required: [capability, provider, input, controls]
properties:
capability:
const: audio.align
provider:
type: string
minLength: 1
description: A provider with an audio_alignment service in the current catalog.
input:
type: object
additionalProperties: false
required: [audio_asset_id, transcript]
properties:
audio_asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
transcript:
type: string
minLength: 1
pattern: '\S'
controls:
type: object
additionalProperties: false
ProviderSpeechGenerationOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- type: object
properties:
capability:
const: audio.speech.generate
input:
type: object
additionalProperties: false
required: [text, voice_id]
properties:
text: {type: string, pattern: '\S'}
voice_id: {type: string, pattern: '^voi_[0-9a-f]{32}$'}
previous_text: {type: [string, 'null']}
next_text: {type: [string, 'null']}
previous_operation_ids:
type: [array, 'null']
maxItems: 3
items: {type: string, pattern: '^mop_[0-9a-f]{32}$'}
next_operation_ids:
type: [array, 'null']
maxItems: 3
items: {type: string, pattern: '^mop_[0-9a-f]{32}$'}
dictionaries:
type: [array, 'null']
maxItems: 3
items:
type: object
additionalProperties: false
required: [dictionary_id, version_id]
properties:
dictionary_id: {type: string, pattern: '^dic_[0-9a-f]{32}$'}
version_id: {type: string, pattern: '^div_[0-9a-f]{32}$'}
controls:
type: object
additionalProperties: false
required: [output_format, timestamps]
properties:
output_format:
type: string
minLength: 1
description: Use a format from the selected catalog offering.
timestamps: {type: boolean}
stability: {type: [number, 'null'], minimum: 0, maximum: 1}
similarity_boost: {type: [number, 'null'], minimum: 0, maximum: 1}
style: {type: [number, 'null'], minimum: 0, maximum: 1}
use_speaker_boost: {type: [boolean, 'null']}
speed: {type: [number, 'null'], minimum: 0.7, maximum: 1.2}
seed: {type: [integer, 'null'], minimum: 0, maximum: 4294967295}
language_code:
type: [string, 'null']
description: Use a language code declared by the selected offering.
text_normalization:
type: [string, 'null']
enum: [auto, 'on', 'off', '', null]
language_text_normalization: {type: [boolean, 'null']}
MediaSpeechTiming:
type: object
additionalProperties: false
required: [alignment, normalized_alignment]
properties:
alignment:
anyOf:
- {type: 'null'}
- {$ref: '#/components/schemas/SpeechCharacterAlignment'}
normalized_alignment:
anyOf:
- {type: 'null'}
- {$ref: '#/components/schemas/SpeechCharacterAlignment'}
SpeechCharacterAlignment:
type: object
additionalProperties: false
required: [characters, character_start_times_seconds, character_end_times_seconds]
properties:
characters:
type: array
items: {type: string, minLength: 1}
character_start_times_seconds:
type: array
items: {type: number, minimum: 0}
character_end_times_seconds:
type: array
items: {type: number, minimum: 0}
ProviderSpeechConversionOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- type: object
properties:
capability:
const: audio.speech.convert
input:
type: object
additionalProperties: false
required: [voice_id, audio_asset_id]
properties:
voice_id:
type: string
pattern: ^voi_[0-9a-f]{32}$
audio_asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
controls:
type: object
additionalProperties: false
required: [input_format, output_format]
properties:
input_format:
enum: [other, pcm_s16le_16]
output_format:
type: string
description: Use a format from the selected catalog offering.
minLength: 1
stability:
type: [number, 'null']
minimum: 0
maximum: 1
similarity_boost:
type: [number, 'null']
minimum: 0
maximum: 1
style:
type: [number, 'null']
minimum: 0
maximum: 1
use_speaker_boost:
type: [boolean, 'null']
seed:
type: [integer, 'null']
minimum: 0
maximum: 4294967295
remove_background_noise:
type: [boolean, 'null']
MediaAudioDescription:
type: object
additionalProperties: false
required: [output_format, mime_type]
properties:
output_format:
type: string
minLength: 1
mime_type:
enum: [audio/mpeg, audio/ogg, audio/wav, application/octet-stream]
raw_audio:
type: object
additionalProperties: false
required: [encoding, sample_rate_hz, channels]
properties:
encoding:
enum: [s16le, alaw, mulaw]
sample_rate_hz:
enum: [8000, 16000, 22050, 24000, 32000, 44100, 48000]
channels:
const: 1
MediaOperationRequestBase:
type: object
additionalProperties: false
required: [capability, provider, model, input, controls]
properties:
capability:
type: string
minLength: 1
provider:
type: string
minLength: 1
model:
type: string
minLength: 1
input:
type: object
controls:
type: object
ImageGenerationOperationRequest:
oneOf:
- $ref: '#/components/schemas/SurfaceImageGenerationOperationRequest'
- $ref: '#/components/schemas/AspectRatioImageGenerationOperationRequest'
AspectRatioImageGenerationOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- type: object
properties:
capability:
const: image.generate
input:
type: object
additionalProperties: false
required: [prompt]
properties:
prompt:
type: string
minLength: 1
maxLength: 4000
pattern: '\S'
controls:
type: object
additionalProperties: false
required: [aspect_ratio, output_format, output_count]
properties:
aspect_ratio:
type: string
description: Use a value from the selected catalog offering.
minLength: 1
output_format:
enum: [png, jpeg, webp]
output_count:
type: integer
minimum: 1
maximum: 4
SurfaceImageGenerationOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- $ref: '#/components/schemas/ImageSurfaceOperationRequest'
- type: object
properties:
capability:
const: image.generate
input:
type: object
additionalProperties: false
required: [prompt]
properties:
previous_operation_id:
type: string
pattern: '^mop_[a-f0-9]{32}$'
prompt:
type: string
minLength: 1
maxLength: 32000
pattern: '\S'
controls:
$ref: '#/components/schemas/ImageGenerationControls'
ImageEditingOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- $ref: '#/components/schemas/ImageSurfaceOperationRequest'
- type: object
properties:
capability:
const: image.edit
input:
type: object
additionalProperties: false
required: [prompt]
anyOf:
- required: [image_asset_ids]
- required: [previous_operation_id]
properties:
previous_operation_id:
type: string
pattern: '^mop_[a-f0-9]{32}$'
prompt:
type: string
minLength: 1
maxLength: 32000
pattern: '\S'
image_asset_ids:
type: array
minItems: 1
maxItems: 16
items:
type: string
pattern: '^ast_[a-f0-9]{32}$'
mask_asset_id:
type: string
pattern: '^ast_[a-f0-9]{32}$'
controls:
$ref: '#/components/schemas/ImageGenerationControls'
ImageSurfaceOperationRequest:
if:
properties:
controls:
properties:
surface:
const: responses
then:
properties:
input:
not:
required: [mask_asset_id]
else:
properties:
input:
not:
required: [previous_operation_id]
ImageGenerationControls:
type: object
description: Explicit generation choices. The selected catalog route supplies exact dimension and control limits. JPEG and WebP require compression, including explicit zero. PNG omits compression.
additionalProperties: false
required: [surface, quality, size, background, output_format, output_count]
properties:
surface:
enum: [images, responses]
responses_model:
type: string
minLength: 1
description: Catalog-selected text model for the Responses surface.
quality:
enum: [low, medium, high, auto]
size:
type: string
pattern: '^(auto|[1-9][0-9]*x[1-9][0-9]*)$'
background:
enum: [opaque, transparent, auto]
output_format:
enum: [png, jpeg, webp]
output_compression:
type: integer
minimum: 0
maximum: 100
output_count:
type: integer
minimum: 1
maximum: 10
stream:
type: boolean
description: Request progressive output. The current Images stream has one final image.
partial_images:
type: integer
minimum: 0
maximum: 3
description: Maximum preview count. Requires streaming when greater than zero. The provider can return fewer previews.
allOf:
- if:
properties:
surface:
const: responses
then:
required: [responses_model]
properties:
output_count:
const: 1
else:
not:
required: [responses_model]
- if:
required: [stream]
properties:
stream:
const: true
then:
properties:
output_count:
const: 1
else:
properties:
partial_images:
const: 0
- if:
properties:
output_format:
const: png
then:
not:
required: [output_compression]
else:
required: [output_compression]
- if:
properties:
output_format:
const: jpeg
then:
properties:
background:
enum: [opaque, auto]
VideoGenerationOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- type: object
properties:
capability:
const: video.generate
DictatorTranscriptionOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- type: object
properties:
capability:
const: audio.transcribe
provider:
const: dictator
model:
enum: [whisper-tiny, whisper-base, whisper-small, whisper-medium, whisper-large-v3]
input:
$ref: '#/components/schemas/DictatorAudioInput'
controls:
$ref: '#/components/schemas/DictatorLanguageControls'
DictatorDiarizationOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- type: object
properties:
capability:
const: audio.diarize
provider:
const: dictator
model:
enum: [whisper-tiny, whisper-base, whisper-small, whisper-medium, whisper-large-v3]
input:
$ref: '#/components/schemas/DictatorAudioInput'
controls:
type: object
additionalProperties: false
properties:
language:
type: string
minLength: 1
detect_language:
const: true
model_size:
type: string
minLength: 1
utterance_gap_seconds:
type: number
minimum: 0
description: An explicit zero remains zero. Omission uses the Dictator default.
oneOf:
- required: [language]
not:
required: [detect_language]
- required: [detect_language]
not:
required: [language]
DictatorAlignmentOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- type: object
properties:
capability:
const: audio.align
provider:
const: dictator
model:
enum: [whisper-tiny, whisper-base, whisper-small, whisper-medium, whisper-large-v3]
input:
type: object
additionalProperties: false
required: [audio_asset_id, transcript]
properties:
audio_asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
transcript:
type: string
minLength: 1
controls:
type: object
additionalProperties: false
required: [language]
properties:
language:
type: string
minLength: 1
remove_punctuation:
type: boolean
DictatorSubtitleOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- type: object
properties:
capability:
const: subtitles.create
provider:
const: dictator
model:
enum: [whisper-tiny, whisper-base, whisper-small, whisper-medium, whisper-large-v3]
input:
type: object
additionalProperties: false
required: [audio_asset_id]
properties:
audio_asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
transcript:
type: string
minLength: 1
controls:
type: object
additionalProperties: false
required: [granularity, group_size]
properties:
language:
type: string
minLength: 1
detect_language:
const: true
granularity:
type: string
enum: [word, sentence]
group_size:
type: integer
minimum: 1
oneOf:
- required: [language]
not:
required: [detect_language]
- required: [detect_language]
not:
required: [language]
DictatorSpeechGenerationOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- type: object
properties:
capability:
const: audio.speech.generate
provider:
const: dictator
model:
enum: [qwen3-tts, silero-ru]
input:
type: object
additionalProperties: false
required: [text, voice_id]
properties:
text:
type: string
minLength: 1
voice_id:
type: string
pattern: ^voi_[0-9a-f]{32}$
controls:
type: object
additionalProperties: false
required: [language, text_format, sample_rate_hz]
properties:
language:
type: string
minLength: 1
text_format:
type: string
enum: [plain, ssml]
sample_rate_hz:
type: integer
enum: [24000, 48000]
max_duration_seconds:
type: number
minimum: 0
include_timeline:
type: boolean
DictatorVoiceExtractionOperationRequest:
allOf:
- $ref: '#/components/schemas/MediaOperationRequestBase'
- type: object
properties:
capability:
const: audio.voice.extract
provider:
const: dictator
model:
enum: [whisper-tiny, whisper-base, whisper-small, whisper-medium, whisper-large-v3]
input:
type: object
additionalProperties: false
required: [audio_asset_id, transcript, display_name, language]
properties:
audio_asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
transcript:
type: string
minLength: 1
display_name:
type: string
minLength: 1
language:
type: string
minLength: 1
controls:
type: object
additionalProperties: false
properties:
duration_seconds:
type: number
exclusiveMinimum: 0
default: 20
model_size:
type: string
minLength: 1
DictatorAudioInput:
type: object
additionalProperties: false
required: [audio_asset_id]
properties:
audio_asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
DictatorLanguageControls:
type: object
additionalProperties: false
properties:
language:
type: string
minLength: 1
detect_language:
const: true
oneOf:
- required: [language]
not:
required: [detect_language]
- required: [detect_language]
not:
required: [language]
MediaOperation:
type: object
additionalProperties: false
required: [operation_id, capability, provider, catalog_revision, state, cancellation_state, outputs, cost, accepted_at, updated_at, deadline_at]
properties:
previous_operation_id:
type: string
pattern: ^mop_[0-9a-f]{32}$
description: The successful tenant operation used as the Responses chain parent.
operation_id:
type: string
pattern: ^mop_[0-9a-f]{32}$
capability:
type: string
minLength: 1
provider:
type: string
minLength: 1
model:
type: string
minLength: 1
catalog_revision:
type: string
minLength: 1
state:
type: string
enum: [queued, running, succeeded, failed, cancelled, uncertain]
cancellation_state:
type: string
enum: [not_requested, requested, confirmed, unsupported]
outputs:
type: array
items:
type: object
additionalProperties: false
required: [asset_id, mime_type, size_bytes, ordinal]
properties:
asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
mime_type:
type: string
minLength: 1
size_bytes:
type: integer
format: int64
minimum: 1
ordinal:
type: integer
minimum: 0
partial_outputs:
type: array
description: Verified preview assets in output and partial order. Available during execution and retained with the operation.
items:
type: object
additionalProperties: false
required: [asset_id, mime_type, size_bytes, output_ordinal, partial_ordinal]
properties:
asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
mime_type:
type: string
minLength: 1
size_bytes:
type: integer
format: int64
minimum: 1
output_ordinal:
type: integer
minimum: 0
partial_ordinal:
type: integer
minimum: 0
error:
type: object
additionalProperties: false
required: [code]
properties:
code:
type: string
enum: [provider_error, provider_rate_limited, operation_deadline_exceeded, provider_outcome_unknown, worker_claim_lost, worker_shutdown, asset_publication_failed, provider_result_invalid, media_operation_unavailable, usage_journal_unavailable]
cost:
type: object
additionalProperties: false
required: [available]
properties:
available:
type: boolean
reason:
type: string
minLength: 1
accepted_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
deadline_at:
type: string
format: date-time
MediaOperationErrorEnvelope:
type: object
additionalProperties: false
required: [error]
properties:
error:
type: object
additionalProperties: false
required: [code]
properties:
code:
type: string
enum: [media_operation_invalid, media_operation_unavailable, media_operation_not_found, media_operation_intent_conflict, media_operation_capacity_exceeded, media_operation_store_error, insufficient_funds, financial_admission_unavailable, hosted_authority_denied]
MediaOperationExpired:
type: object
additionalProperties: false
required: [operation_id, state, error]
properties:
operation_id:
type: string
pattern: ^mop_[0-9a-f]{32}$
state:
type: string
enum: [succeeded, failed, cancelled]
error:
type: object
additionalProperties: false
required: [code]
properties:
code:
const: media_operation_expired
MediaVoice:
type: object
additionalProperties: false
required: [voice_id, provider, mode, language, display_name, default, sample_rates, default_sample_rate, description, category, labels, high_quality_base_model_ids, verified_languages, preview]
properties:
voice_id:
type: string
pattern: ^voi_[0-9a-f]{32}$
provider:
type: string
minLength: 1
mode:
type: string
enum: [preset, extracted]
language:
type: [string, "null"]
minLength: 1
display_name:
type: string
minLength: 1
default:
type: boolean
sample_rates:
type: array
uniqueItems: true
items:
type: integer
minimum: 1
default_sample_rate:
type: [integer, "null"]
minimum: 1
description:
type: [string, "null"]
category:
type: [string, "null"]
labels:
type: object
additionalProperties: {type: string}
high_quality_base_model_ids:
type: array
items: {type: string, minLength: 1}
verified_languages:
type: array
items:
$ref: '#/components/schemas/MediaVoiceLanguage'
preview:
type: [string, "null"]
pattern: ^/model/v1/voices/voi_[0-9a-f]{32}/previews/0$
MediaVoiceLanguage:
type: object
additionalProperties: false
required: [language, model_id, accent, locale, preview]
properties:
language: {type: string, minLength: 1}
model_id: {type: string, minLength: 1}
accent: {type: [string, "null"]}
locale: {type: [string, "null"]}
preview:
type: [string, "null"]
pattern: ^/model/v1/voices/voi_[0-9a-f]{32}/previews/[1-9][0-9]*$
MediaVoiceCollection:
type: object
additionalProperties: false
required: [voices, has_more, total_count, next_cursor]
properties:
voices:
type: array
items:
$ref: '#/components/schemas/MediaVoice'
has_more: {type: boolean}
total_count: {type: [integer, "null"], minimum: 0}
next_cursor: {type: [string, "null"], minLength: 1}
ProviderDiagnostics:
type: object
additionalProperties: false
required: [provider, scope, operations_total, queued, running, succeeded, failed, cancelled, uncertain]
properties:
provider:
type: string
pattern: ^[a-z][a-z0-9_-]*$
scope:
type: string
const: tenant
operations_total:
type: integer
format: int64
minimum: 0
queued:
type: integer
format: int64
minimum: 0
running:
type: integer
format: int64
minimum: 0
succeeded:
type: integer
format: int64
minimum: 0
failed:
type: integer
format: int64
minimum: 0
cancelled:
type: integer
format: int64
minimum: 0
uncertain:
type: integer
format: int64
minimum: 0
MediaVoiceErrorEnvelope:
type: object
additionalProperties: false
required: [error]
properties:
error:
type: object
additionalProperties: false
required: [code]
properties:
code:
type: string
enum: [media_voice_invalid, media_voice_not_found, media_voice_provider_error, media_voice_store_error]
TenantAsset:
type: object
additionalProperties: false
required:
- asset_id
- mime_type
- size_bytes
- state
- created_at
- expires_at
properties:
asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
mime_type:
type: string
enum:
- application/octet-stream
- application/json
- application/x-subrip
- image/jpeg
- image/png
- image/webp
- audio/m4a
- audio/mpeg
- audio/wav
- audio/flac
- audio/ogg
- video/mp4
- video/webm
size_bytes:
type: integer
format: int64
minimum: 1
state:
type: string
const: available
created_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
AssetErrorEnvelope:
type: object
additionalProperties: false
required:
- error
properties:
error:
type: object
additionalProperties: false
required:
- code
properties:
code:
type: string
enum:
- asset_invalid
- asset_not_found
- asset_expired
- asset_deleted
- asset_in_use
- asset_mime_mismatch
- asset_too_large
- asset_store_error
V2ChatMessage:
description: A text message, user media message, assistant function call, or matched tool result.
oneOf:
- $ref: '#/components/schemas/V2UserChatMessage'
- $ref: '#/components/schemas/V2SystemOrAssistantChatMessage'
- $ref: '#/components/schemas/V2AssistantToolMessage'
- $ref: '#/components/schemas/V2ToolMessage'
V2UserChatMessage:
type: object
additionalProperties: false
required:
- role
- content
properties:
role:
const: user
content:
type: string
minLength: 1
attachments:
type: array
minItems: 1
items:
$ref: '#/components/schemas/MessageAttachment'
order:
type: integer
minimum: 0
V2SystemOrAssistantChatMessage:
type: object
additionalProperties: false
required:
- role
- content
properties:
role:
enum:
- system
- assistant
content:
type: string
minLength: 1
order:
type: integer
minimum: 0
V2AssistantToolMessage:
type: object
additionalProperties: false
required:
- role
- content
- tool_calls
properties:
role:
const: assistant
content:
type: string
tool_calls:
type: array
minItems: 1
items:
$ref: '#/components/schemas/ClientFunctionCall'
order:
type: integer
minimum: 0
V2ToolMessage:
type: object
additionalProperties: false
required:
- role
- content
- tool_call_id
properties:
role:
const: tool
content:
type: string
tool_call_id:
type: string
minLength: 1
order:
type: integer
minimum: 0
TextRequest:
type: object
additionalProperties: false
properties:
prompt:
type: string
minLength: 1
messages:
type: array
minItems: 1
description: >-
Each Gemini Interactions route rejects assistant history. Other
routes retain their declared message behavior.
items:
$ref: '#/components/schemas/ChatMessage'
model:
type: string
minLength: 1
web_search:
type: boolean
speech_provider:
type: string
description: Selected speech provider. An empty value clears the selection.
speech_model:
type: string
description: Selected speech model. An empty value clears the selection.
system_prompt:
type: string
max_tokens:
type: integer
minimum: 1
description: Initial output budget. A transport that declares continuation actions reuses it for missing-suffix attempts.
reasoning_effort:
type: string
minLength: 1
description: >-
Omission selects the tenant or route default. An explicit value
must be non-blank and supported by the resolved provider/model
route.
V2Request:
type: object
additionalProperties: false
required:
- messages
properties:
tools:
type: array
items:
$ref: "#/components/schemas/ClientFunction"
tool_choice:
$ref: "#/components/schemas/ClientToolChoice"
parallel_tool_calls:
type: boolean
messages:
type: array
minItems: 1
description: >-
Each message must have an allowed role and non-blank content. The
request must include at least one user message. All messages must
omit order, or all must have unique non-negative order values. Only
user messages can have attachments. Message and attachment order
are preserved. Each Gemini Interactions route rejects assistant
history.
items:
$ref: '#/components/schemas/V2ChatMessage'
model:
type: string
minLength: 1
description: Omission selects the resolved provider default.
web_search:
type: boolean
description: The resolved route must declare web-search capability when true.
max_tokens:
type: integer
minimum: 1
description: Initial output budget. A transport that declares continuation actions reuses it for missing-suffix attempts.
reasoning_effort:
type: string
minLength: 1
description: >-
Omission selects the tenant or route default. An explicit value
must be non-blank and supported by the resolved provider/model
route. Kimi K3 accepts low, high, or max.
structured_output:
$ref: '#/components/schemas/StructuredOutput'
StructuredOutput:
type: object
additionalProperties: false
required:
- schema
properties:
schema:
type: object
description: JSON Schema admitted against the selected provider subset, enforced by that provider, and revalidated by llm-proxy before durable success.
StructuredRequestStatus:
type: object
additionalProperties: false
required:
- state
- proxy_request_id
- started_at
- updated_at
- elapsed_seconds
properties:
state:
type: string
enum:
- not_dispatched
- dispatched
proxy_request_id:
type: string
minLength: 1
started_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
elapsed_seconds:
type: integer
format: int64
minimum: 0
StructuredRequestErrorEnvelope:
type: object
additionalProperties: false
required:
- error
properties:
error:
$ref: '#/components/schemas/StructuredRequestError'
StructuredRequestError:
type: object
additionalProperties: false
required:
- code
properties:
code:
type: string
enum:
- hosted_result_expired
- invalid_idempotency_key
- structured_request_not_found
- structured_request_intent_conflict
- structured_request_outcome_unknown
- structured_request_failed
- structured_request_invalid
- structured_request_store_error
state:
type: string
enum:
- succeeded
- failed
- uncertain
cause:
type: string
minLength: 1
proxy_request_id:
type: string
minLength: 1
DictationRequest:
type: object
additionalProperties: false
required:
- audio
properties:
audio:
type: string
format: binary
description: The canonical incoming audio file part.
DictationResponse:
type: object
additionalProperties: false
required:
- text
properties:
text:
type: string
TokenUsage:
type: object
additionalProperties: false
required:
- request_tokens
- response_tokens
- total_tokens
properties:
request_tokens:
type: integer
minimum: 0
response_tokens:
type: integer
minimum: 0
total_tokens:
type: integer
minimum: 0
TextJSONResponse:
type: object
additionalProperties: false
required:
- request
- response
- object
- model
- choices
- messages
properties:
request:
type: string
response:
type: string
object:
type: string
const: chat.completion
model:
type: string
choices:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Choice'
messages:
type: array
items:
$ref: '#/components/schemas/ResponseMessage'
usage:
$ref: '#/components/schemas/TokenUsage'
Choice:
type: object
additionalProperties: false
required:
- index
- finish_reason
- message
properties:
index:
type: integer
minimum: 0
finish_reason:
type: string
const: stop
message:
$ref: '#/components/schemas/ResponseMessage'
ResponseMessage:
type: object
additionalProperties: false
required:
- role
- content
properties:
role:
type: string
enum:
- system
- user
- assistant
content:
type: string
order:
type: integer
minimum: 0
ProxyErrorEnvelope:
type: object
additionalProperties: false
required:
- error
properties:
error:
type: object
additionalProperties: false
required:
- code
properties:
code:
type: string
enum:
- invalid_request_timeout
- request_timeout
max_request_timeout_seconds:
type: integer
minimum: 1
request_timeout_seconds:
type: integer
minimum: 1
ProviderErrorEnvelope:
type: object
additionalProperties: false
required:
- error
properties:
error:
type: object
additionalProperties: false
required:
- code
- provider
- upstream_status
- retryable
- request_id
- retry_after
properties:
code:
type: string
enum:
- insufficient_funds
- financial_admission_unavailable
- hosted_authority_denied
- hosted_result_expired
- usage_journal_conflict
- usage_journal_claim_lost
- provider_error
- provider_media_limit_exceeded
- provider_rate_limited
provider:
type: string
minLength: 1
description: Canonical provider selector resolved for the request.
upstream_status:
oneOf:
- type: integer
minimum: 100
maximum: 599
- type: 'null'
description: Exact provider HTTP status when an upstream response was received. The value is null for transport, request-construction, and response-protocol failures without a usable unsuccessful HTTP response.
retryable:
type: boolean
description: True for upstream HTTP 408, 425, 429, 500, 502, 503, or 504. Failed Gemini Interactions use validated URI codes. The value is true only when each URI has a documented retryable final path segment. The retryable segments are aborted, api_error, deadline_exceeded, rate_limit_exceeded, service_unavailable, and too_many_requests. An empty list or unknown final path segment produces false. This value does not make a request idempotent or remove duplicate-work and billing risk.
request_id:
type: string
minLength: 1
description: Proxy-owned correlation identifier also returned in X-LLM-Proxy-Request-ID and recorded in structured proxy logs.
retry_after:
oneOf:
- type: string
minLength: 1
- type: 'null'
description: Validated and normalized provider Retry-After value, or null when the provider omitted it or supplied an invalid value. A non-null value is also returned in the Retry-After response header.
TenantNameRequest:
type: object
additionalProperties: false
required:
- name
properties:
name:
type: string
minLength: 1
DefaultsRequest:
type: object
additionalProperties: false
required:
- provider
- model
- transcription_provider
- transcription_model
- system_prompt
- reasoning_effort
properties:
provider:
type: string
description: Canonical configured text provider, or empty with model when no provider connection exists.
model:
type: string
description: Canonical model for provider, or empty with provider when no provider connection exists.
transcription_provider:
type: string
description: Canonical configured transcription provider, or empty with transcription_model for an unset selection.
transcription_model:
type: string
description: Canonical transcription model, or empty with transcription_provider for an unset selection.
speech_provider:
type: string
description: Selected speech provider. An empty value clears the selection.
speech_model:
type: string
description: Selected speech model. An empty value clears the selection.
system_prompt:
type: string
reasoning_effort:
type: string
EmptyObject:
type: object
additionalProperties: false
properties: {}
FundingOffer:
type: object
additionalProperties: false
required: [code, funding_cents, currency]
properties:
code: {type: string, minLength: 1, maxLength: 64}
funding_cents:
type: string
pattern: '^[0-9]+$'
description: Server-selected customer credit in USD cents. The minimum is 500 cents.
currency: {type: string, enum: [USD]}
FundingOffers:
type: object
additionalProperties: false
required: [provider, environment, client_token, offers]
properties:
provider: {type: string, enum: [paddle]}
environment: {type: string, enum: [sandbox, production]}
client_token: {type: string, pattern: '^(test|live)_[a-zA-Z0-9]+$'}
offers:
type: array
items: {$ref: '#/components/schemas/FundingOffer'}
PaymentReceipt:
type: object
additionalProperties: false
required: [funding_order_id, environment, currency, state, credit_cents, gross_cents, tax_cents, adjusted_gross_cents, adjusted_tax_cents, reversed_cents, pending_refund_cents, invoice_number, paid_at]
properties:
funding_order_id: {type: string, pattern: '^funding-[a-f0-9]{32}$'}
environment: {type: string, enum: [sandbox, production]}
currency: {type: string, enum: [USD]}
state: {type: string, enum: [paid, partially_refunded, refunded, disputed]}
credit_cents: {type: string, pattern: '^[0-9]+$'}
gross_cents: {type: string, pattern: '^[0-9]+$'}
tax_cents: {type: string, pattern: '^[0-9]+$'}
adjusted_gross_cents: {type: string, pattern: '^[0-9]+$'}
adjusted_tax_cents: {type: string, pattern: '^[0-9]+$'}
reversed_cents:
type: string
pattern: '^[0-9]+$'
description: Cumulative customer credit removed after verified processor adjustments.
pending_refund_cents:
type: string
pattern: '^[0-9]+$'
description: Customer credit allocated to pending processor adjustments.
invoice_number: {type: string, nullable: true}
paid_at: {type: string, format: date-time}
PaymentPortalSession:
type: object
additionalProperties: false
required: [provider, environment, url]
properties:
provider: {type: string, enum: [paddle]}
environment: {type: string, enum: [sandbox, production]}
url: {type: string, format: uri, pattern: '^https://'}
PaymentCheckout:
type: object
additionalProperties: false
required: [provider, environment, transaction_id]
properties:
provider: {type: string, enum: [paddle]}
environment: {type: string, enum: [sandbox, production]}
transaction_id: {type: string, pattern: '^txn_[a-z0-9]{26}$'}
FundingOrder:
type: object
additionalProperties: false
required: [id, offer_code, funding_cents, currency, environment, state, created_at]
properties:
id: {type: string, pattern: '^funding-[a-f0-9]{32}$'}
offer_code: {type: string, minLength: 1, maxLength: 64}
funding_cents: {type: string, pattern: '^[0-9]+$'}
currency: {type: string, enum: [USD]}
environment: {type: string, enum: [sandbox, production]}
state:
type: string
enum: [created, pending, paid, failed, partially_refunded, refunded, disputed]
created_at: {type: string, format: date-time}
FundingOrders:
type: object
additionalProperties: false
required: [orders, next_cursor]
properties:
orders:
type: array
items: {$ref: '#/components/schemas/FundingOrder'}
next_cursor: {type: string}
BillingAccount:
type: object
additionalProperties: false
required: [id, currency, created_at]
properties:
id:
type: string
pattern: '^billing-[a-f0-9]{32}$'
currency:
type: string
enum: [USD]
created_at:
type: string
format: date-time
JournalRequest:
type: object
additionalProperties: false
required: [id, tenant_id, grant_id, grant_revision, provider, operation, catalog_revision, execution_kind, execution_id, state, usage_state, created_at, updated_at]
anyOf:
- required: [model]
- properties:
execution_kind:
const: media_operation
properties:
id:
type: string
pattern: '^request-[a-f0-9]{32}$'
tenant_id:
type: string
grant_id:
type: string
pattern: '^grant-[a-f0-9]{32}$'
grant_revision:
type: integer
minimum: 1
provider:
type: string
model:
type: string
minLength: 1
description: Omitted for provider services that do not select a model.
operation:
type: string
catalog_revision:
type: string
execution_kind:
type: string
enum: [text_request, media_operation, dictation_request]
execution_id:
type: string
description: The identity retained by the execution owner.
state:
type: string
enum: [accepted, executing, completed, failed, uncertain]
usage_state:
type: string
enum: [pending, complete, unknown]
description: Execution completion does not establish usage completeness or charge eligibility.
failure_code:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
JournalAttempt:
type: object
additionalProperties: false
required: [id, number, state, created_at, updated_at]
properties:
id:
type: string
pattern: '^attempt-[a-f0-9]{32}$'
number:
type: integer
minimum: 1
state:
type: string
enum: [prepared, dispatched, observed, uncertain]
dispatched_at:
type: string
format: date-time
observed_at:
type: string
format: date-time
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
JournalQuantity:
type: object
additionalProperties: false
required: [dimension, unit]
oneOf:
- required: [value]
- required: [unknown_reason]
properties:
dimension:
type: string
pattern: '^[a-z][a-z0-9_]{0,63}$'
unit:
type: string
pattern: '^[a-z][a-z0-9_]{0,63}$'
value:
type: string
pattern: '^(0|[1-9][0-9]*)(\.[0-9]+)?$'
description: An exact nonnegative decimal measurement. An unknown measurement has no value.
unknown_reason:
type: string
enum: [not_reported, invalid_quantity, unsupported_meter]
included_in:
type: string
pattern: '^[a-z][a-z0-9_]{0,63}$'
description: The parent dimension that already includes this quantity. Do not add it to the parent again.
JournalObservation:
type: object
additionalProperties: false
required: [id, attempt_id, quantities, completeness, outcome, observed_at, created_at]
properties:
id:
type: string
pattern: '^observation-[a-f0-9]{32}$'
attempt_id:
type: string
pattern: '^attempt-[a-f0-9]{32}$'
quantities:
type: array
minItems: 1
items:
$ref: '#/components/schemas/JournalQuantity'
completeness:
type: string
enum: [complete, unknown]
outcome:
type: string
enum: [continue, complete, fail]
failure_code:
type: string
observed_at:
type: string
format: date-time
created_at:
type: string
format: date-time
JournalReconciliationCase:
type: object
additionalProperties: false
required: [id, reason, state, created_at]
properties:
id:
type: string
pattern: '^case-[a-f0-9]{32}$'
reason:
type: string
enum: [usage_unknown, dispatch_outcome_unknown, execution_outcome_unknown, execution_result_unknown, usage_unresolved, policy_unresolved, limit_unresolved, platform_exposure]
state:
type: string
enum: [open, resolved]
resolved_at:
type: string
format: date-time
created_at:
type: string
format: date-time
PlatformConnection:
type: object
additionalProperties: false
required: [id, name, provider, version, qualified, created_at, updated_at]
properties:
id:
type: string
pattern: '^platform-[a-f0-9]{32}$'
name:
type: string
minLength: 1
maxLength: 80
provider:
type: string
minLength: 1
version:
type: integer
minimum: 1
qualified:
type: boolean
const: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
PlatformConnectionWrite:
type: object
additionalProperties: false
required: [name, provider, fields]
description: >-
Creation requires version zero or omission. Replacement requires the current version and all required connection fields.
Successful verification stores a new immutable credential version. Existing versions remain available for accepted work.
properties:
name:
type: string
minLength: 1
maxLength: 80
provider:
type: string
minLength: 1
fields:
type: object
additionalProperties:
type: string
version:
type: integer
minimum: 0
HostedGrantState:
type: string
enum: [active, suspended, revoked]
HostedGrantReason:
type: string
minLength: 1
maxLength: 500
description: Operator reason without leading or trailing whitespace. Customer responses omit this field.
HostedGrantOfferings:
type: array
minItems: 1
description: Exact models or explicit services from one provider. An omitted model selects services, never all models.
items:
type: object
additionalProperties: false
required: [operations]
properties:
model:
type: string
minLength: 1
operations:
type: array
minItems: 1
uniqueItems: true
items:
type: string
minLength: 1
HostedAccessGrantCreate:
type: object
additionalProperties: false
required: [billing_account_id, tenant_id, platform_connection_id, catalog_revision, offerings, reason]
properties:
billing_account_id:
type: string
pattern: '^billing-[a-f0-9]{32}$'
tenant_id:
type: string
minLength: 1
platform_connection_id:
type: string
pattern: '^platform-[a-f0-9]{32}$'
catalog_revision:
type: string
minLength: 1
offerings:
$ref: '#/components/schemas/HostedGrantOfferings'
reason:
$ref: '#/components/schemas/HostedGrantReason'
HostedAccessGrant:
type: object
additionalProperties: false
required: [id, billing_account_id, tenant_id, provider, catalog_revision, offerings, state, revision, created_at, updated_at]
properties:
id:
type: string
pattern: '^grant-[a-f0-9]{32}$'
billing_account_id:
type: string
pattern: '^billing-[a-f0-9]{32}$'
tenant_id:
type: string
minLength: 1
platform_connection_id:
type: string
pattern: '^platform-[a-f0-9]{32}$'
description: Operator responses only.
provider:
type: string
minLength: 1
catalog_revision:
type: string
minLength: 1
offerings:
$ref: '#/components/schemas/HostedGrantOfferings'
state:
$ref: '#/components/schemas/HostedGrantState'
revision:
type: integer
minimum: 1
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
HostedAccessGrantRevision:
type: object
additionalProperties: false
required: [revision, state, actor_user_id, reason, created_at]
properties:
revision:
type: integer
minimum: 1
state:
$ref: '#/components/schemas/HostedGrantState'
actor_user_id:
type: string
minLength: 1
reason:
$ref: '#/components/schemas/HostedGrantReason'
created_at:
type: string
format: date-time
ManagementAccount:
type: object
additionalProperties: false
required:
- user
- tenants
properties:
user:
$ref: '#/components/schemas/ManagementUser'
tenants:
type: array
items:
$ref: '#/components/schemas/TenantSummary'
ManagementUser:
type: object
additionalProperties: false
required:
- id
- is_admin
properties:
id:
type: string
minLength: 1
email:
type: string
display_name:
type: string
avatar_url:
type: string
is_admin:
type: boolean
TenantIdentity:
type: object
additionalProperties: false
required:
- tenant_id
properties:
tenant_id:
type: string
minLength: 1
TenantSummary:
type: object
additionalProperties: false
required:
- id
- name
- has_secret
- created_at
- updated_at
properties:
id:
type: string
name:
type: string
has_secret:
type: boolean
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
TenantProfile:
type: object
additionalProperties: false
required:
- tenant
- providers
- proxy
properties:
tenant:
$ref: '#/components/schemas/Tenant'
providers:
type: array
items:
$ref: '#/components/schemas/ProviderProfile'
proxy:
$ref: '#/components/schemas/ProxyPaths'
Tenant:
type: object
additionalProperties: false
required:
- id
- name
- has_secret
- defaults
- created_at
- updated_at
properties:
id:
type: string
name:
type: string
has_secret:
type: boolean
defaults:
$ref: '#/components/schemas/TenantDefaults'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
TenantDefaults:
type: object
additionalProperties: false
required:
- provider
- model
- transcription_provider
- transcription_model
- speech_provider
- speech_model
- system_prompt
- reasoning_effort
properties:
provider:
type: string
description: Canonical configured text provider, or empty for an unset selection.
model:
type: string
description: Canonical text model paired with provider, or empty when provider is empty.
transcription_provider:
type: string
description: Canonical configured transcription provider, or empty for an unset selection.
transcription_model:
type: string
description: Canonical transcription model paired with transcription_provider, or empty when transcription_provider is empty.
speech_provider:
type: string
description: Selected speech provider, or an empty value when no selection exists.
speech_model:
type: string
description: Selected speech model, or an empty value when no selection exists.
system_prompt:
type: string
reasoning_effort:
type: string
ProviderProfile:
type: object
additionalProperties: false
required:
- id
- label
- api_service_label
- key_acquisition_url
- aliases
- capabilities
- resources
- services
- model_families
- configured
- fields
- text_model
- system_prompt
- text_default_model
- text_models
- supports_dictation
- transcription_models
- supports_speech
- speech_models
properties:
services:
type: array
items:
$ref: '#/components/schemas/PublicProviderService'
resources:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/ProviderResourceKind'
id:
type: string
label:
type: string
api_service_label:
type: string
minLength: 1
description: Catalog-owned provider API label for the authenticated provider card.
key_acquisition_url:
type: string
format: uri
pattern: '^https://[^?#]+$'
aliases:
type: array
items:
type: string
capabilities:
type: array
uniqueItems: true
items:
type: string
enum:
- text
- image_input
- audio_input
- dictation
- image_generation
- image_editing
- video_generation
- audio_transcription
- audio_diarization
- audio_alignment
- pronunciation_dictionary_creation
- subtitle_creation
- speech_generation
- speech_conversion
- voice_extraction
- video_lipsync
- video_translation
- avatar_creation
- avatar_video_generation
model_families:
type: array
items:
$ref: '#/components/schemas/ManagementCatalogIdentity'
configured:
type: boolean
fields:
type: array
minItems: 1
items:
$ref: '#/components/schemas/ProviderField'
text_model:
type: string
system_prompt:
type: string
text_default_model:
type: string
text_models:
type: array
items:
$ref: '#/components/schemas/TextModel'
supports_dictation:
type: boolean
transcription_default_model:
type: string
transcription_models:
type: array
items:
type: string
supports_speech:
type: boolean
speech_default_model:
type: string
speech_models:
type: array
description: Models available for speech synthesis defaults. Voice extraction alone does not qualify a model.
items:
type: string
ManagementCatalogIdentity:
type: object
additionalProperties: false
required:
- id
- label
properties:
id:
type: string
minLength: 1
label:
type: string
minLength: 1
ProviderField:
type: object
additionalProperties: false
allOf:
- if:
properties:
secret:
const: false
required:
- secret
then:
required:
- value
not:
required:
- masked_value
- if:
properties:
secret:
const: true
configured:
const: true
required:
- secret
- configured
then:
required:
- masked_value
not:
required:
- value
- if:
properties:
secret:
const: true
configured:
const: false
required:
- secret
- configured
then:
not:
anyOf:
- required:
- value
- required:
- masked_value
required:
- id
- label
- kind
- type
- required
- default
- secret
- validation
- configured
properties:
id:
type: string
minLength: 1
label:
type: string
minLength: 1
kind:
type: string
enum:
- credential
- setting
type:
type: string
enum:
- opaque
- url
- grpc_target
- boolean
required:
type: boolean
default:
type: string
secret:
type: boolean
validation:
$ref: '#/components/schemas/ProviderFieldValidation'
configured:
type: boolean
value:
type: string
description: Current nonsecret value. Secret fields never expose this property in profile responses.
masked_value:
type: string
description: Safe placeholder for a configured secret. Nonsecret and unconfigured secret fields omit this property.
ProviderFieldValidation:
type: object
additionalProperties: false
properties:
minimum_length:
type: integer
minimum: 1
pattern:
type: string
minLength: 1
allowed_schemes:
type: array
minItems: 1
items:
type: string
minLength: 1
TextModel:
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
reasoning_effort:
$ref: '#/components/schemas/ReasoningEffortCapability'
ReasoningEffortCapability:
type: object
additionalProperties: false
required:
- adapter
- efforts
properties:
adapter:
type: string
efforts:
type: array
items:
type: string
ProxyPaths:
type: object
additionalProperties: false
required:
- text_path
- v2_path
- dictation_path
properties:
text_path:
type: string
const: /
v2_path:
type: string
const: /v2
dictation_path:
type: string
const: /dictate
TenantSecret:
type: object
additionalProperties: false
required:
- secret
- profile
properties:
secret:
type: string
minLength: 1
profile:
$ref: '#/components/schemas/TenantProfile'
TokenMeasurementCoverage:
type: object
additionalProperties: false
required: [measured_requests, partial_requests, unknown_requests, historical_requests]
properties:
measured_requests:
type: integer
minimum: 0
partial_requests:
type: integer
minimum: 0
unknown_requests:
type: integer
minimum: 0
historical_requests:
type: integer
minimum: 0
TokenMeasurementCoverageSet:
type: object
additionalProperties: false
required: [request_tokens, response_tokens, total_tokens]
properties:
request_tokens:
$ref: '#/components/schemas/TokenMeasurementCoverage'
response_tokens:
$ref: '#/components/schemas/TokenMeasurementCoverage'
total_tokens:
$ref: '#/components/schemas/TokenMeasurementCoverage'
UsageAggregate:
type: object
additionalProperties: false
required:
- requests
- successful_requests
- failed_requests
- text_requests
- dictation_requests
- request_tokens
- response_tokens
- total_tokens
- average_latency_ms
- token_coverage
properties:
token_coverage:
$ref: '#/components/schemas/TokenMeasurementCoverageSet'
requests:
type: integer
minimum: 0
successful_requests:
type: integer
minimum: 0
failed_requests:
type: integer
minimum: 0
text_requests:
type: integer
minimum: 0
dictation_requests:
type: integer
minimum: 0
request_tokens:
type: integer
minimum: 0
response_tokens:
type: integer
minimum: 0
total_tokens:
type: integer
minimum: 0
average_latency_ms:
type: integer
minimum: 0
UsageBucket:
type: object
additionalProperties: false
required:
- start
- data
properties:
start:
type: string
format: date-time
data:
$ref: '#/components/schemas/UsageAggregate'
UsageProvider:
type: object
additionalProperties: false
required:
- provider
- data
properties:
provider:
type: string
minLength: 1
description: Exact provider identifier from a resolved typed route.
data:
$ref: '#/components/schemas/UsageAggregate'
UsageModel:
type: object
additionalProperties: false
required:
- provider
- model
- data
properties:
provider:
type: string
minLength: 1
description: Exact provider identifier from a resolved typed route.
model:
type: string
minLength: 1
description: Exact model identifier from the same resolved typed route.
data:
$ref: '#/components/schemas/UsageAggregate'
UsageStatus:
type: object
additionalProperties: false
required:
- status_code
- requests
properties:
status_code:
type: integer
minimum: 100
requests:
type: integer
minimum: 0
UsageSummary:
type: object
additionalProperties: false
required:
- interval
- bucket_unit
- rejected_requests
- totals
- buckets
- providers
- models
- status_codes
properties:
interval:
type: string
enum:
- 1d
- 7d
- 30d
- all
bucket_unit:
type: string
enum:
- hour
- day
- month
rejected_requests:
type: integer
minimum: 0
description: Requests rejected before provider dispatch. These requests are excluded from totals, buckets, provider and model dimensions, status codes, and success rate.
totals:
$ref: '#/components/schemas/UsageAggregate'
buckets:
type: array
items:
$ref: '#/components/schemas/UsageBucket'
providers:
type: array
items:
$ref: '#/components/schemas/UsageProvider'
models:
type: array
items:
$ref: '#/components/schemas/UsageModel'
status_codes:
type: array
items:
$ref: '#/components/schemas/UsageStatus'
UsageFailureOutcomeCode:
type: string
enum:
- rate_limited
- service_unavailable
- request_timeout
- upstream_error
- proxy_error
UsageRejectionOutcomeCode:
type: string
enum:
- invalid_request
- payload_too_large
- provider_not_configured
UsageFailure:
type: object
additionalProperties: false
required:
- occurred_at
- endpoint
- provider
- model
- status_code
- outcome_code
- latency_ms
properties:
occurred_at:
type: string
format: date-time
endpoint:
type: string
provider:
type: string
description: Exact resolved provider identifier, or blank when the request failed before route resolution.
model:
type: string
description: Exact resolved model identifier, or blank when the request failed before route resolution.
status_code:
type: integer
minimum: 100
maximum: 599
outcome_code:
$ref: '#/components/schemas/UsageFailureOutcomeCode'
latency_ms:
type: integer
minimum: 0
UsageFailurePage:
type: object
additionalProperties: false
required:
- interval
- failures
properties:
interval:
type: string
enum:
- 1d
- 7d
- 30d
- all
failures:
type: array
items:
$ref: '#/components/schemas/UsageFailure'
next_cursor:
type: string
minLength: 1
AccountUsageFailure:
type: object
additionalProperties: false
required:
- tenant_id
- tenant_name
- occurred_at
- endpoint
- provider
- model
- status_code
- outcome_code
- latency_ms
properties:
tenant_id:
type: string
minLength: 1
tenant_name:
type: string
minLength: 1
occurred_at:
type: string
format: date-time
endpoint:
type: string
provider:
type: string
description: Exact resolved provider identifier, or blank when the request failed before route resolution.
model:
type: string
description: Exact resolved model identifier, or blank when the request failed before route resolution.
status_code:
type: integer
minimum: 100
maximum: 599
outcome_code:
$ref: '#/components/schemas/UsageFailureOutcomeCode'
latency_ms:
type: integer
minimum: 0
AccountUsageFailurePage:
type: object
additionalProperties: false
required:
- interval
- failures
properties:
interval:
type: string
enum:
- 1d
- 7d
- 30d
- all
failures:
type: array
items:
$ref: '#/components/schemas/AccountUsageFailure'
next_cursor:
type: string
minLength: 1
UsageRejection:
type: object
additionalProperties: false
required:
- occurred_at
- endpoint
- provider
- model
- status_code
- outcome_code
- latency_ms
properties:
occurred_at:
type: string
format: date-time
endpoint:
type: string
provider:
type: string
description: Exact resolved provider identifier, or blank when rejection occurred before route resolution.
model:
type: string
description: Exact resolved model identifier, or blank when rejection occurred before route resolution.
status_code:
type: integer
minimum: 100
maximum: 599
outcome_code:
$ref: '#/components/schemas/UsageRejectionOutcomeCode'
latency_ms:
type: integer
minimum: 0
UsageRejectionPage:
type: object
additionalProperties: false
required:
- interval
- rejections
properties:
interval:
type: string
enum:
- 1d
- 7d
- 30d
- all
rejections:
type: array
items:
$ref: '#/components/schemas/UsageRejection'
next_cursor:
type: string
minLength: 1
AccountUsageRejection:
type: object
additionalProperties: false
required:
- tenant_id
- tenant_name
- occurred_at
- endpoint
- provider
- model
- status_code
- outcome_code
- latency_ms
properties:
tenant_id:
type: string
minLength: 1
tenant_name:
type: string
minLength: 1
occurred_at:
type: string
format: date-time
endpoint:
type: string
provider:
type: string
description: Exact resolved provider identifier, or blank when rejection occurred before route resolution.
model:
type: string
description: Exact resolved model identifier, or blank when rejection occurred before route resolution.
status_code:
type: integer
minimum: 100
maximum: 599
outcome_code:
$ref: '#/components/schemas/UsageRejectionOutcomeCode'
latency_ms:
type: integer
minimum: 0
AccountUsageRejectionPage:
type: object
additionalProperties: false
required:
- interval
- rejections
properties:
interval:
type: string
enum:
- 1d
- 7d
- 30d
- all
rejections:
type: array
items:
$ref: '#/components/schemas/AccountUsageRejection'
next_cursor:
type: string
minLength: 1
AdminUsageSummary:
type: object
additionalProperties: false
required:
- period_days
- rejected_requests
- totals
- daily
- providers
- models
- status_codes
properties:
period_days:
type: integer
minimum: 1
rejected_requests:
type: integer
minimum: 0
totals:
$ref: '#/components/schemas/UsageAggregate'
daily:
type: array
items:
type: object
additionalProperties: false
required:
- date
- data
properties:
date:
type: string
format: date
data:
$ref: '#/components/schemas/UsageAggregate'
providers:
type: array
items:
$ref: '#/components/schemas/UsageProvider'
models:
type: array
items:
$ref: '#/components/schemas/UsageModel'
status_codes:
type: array
items:
$ref: '#/components/schemas/UsageStatus'
AdminTenant:
type: object
additionalProperties: false
required:
- id
- name
- has_secret
- created_at
- updated_at
- usage
properties:
id:
type: string
name:
type: string
has_secret:
type: boolean
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
usage:
$ref: '#/components/schemas/AdminUsageSummary'
AdminUser:
type: object
additionalProperties: false
required:
- user
- tenant_count
- tenants
properties:
user:
$ref: '#/components/schemas/ManagementUser'
tenant_count:
type: integer
minimum: 0
tenants:
type: array
items:
$ref: '#/components/schemas/AdminTenant'
AdminUsersSummary:
type: object
additionalProperties: false
required:
- period_days
- users
properties:
period_days:
type: integer
minimum: 1
users:
type: array
items:
$ref: '#/components/schemas/AdminUser'
OpenAIChatChunk:
type: object
additionalProperties: false
required:
- id
- object
- created
- model
- choices
- usage
properties:
id:
type: string
pattern: ^chatcmpl-
object:
const: chat.completion.chunk
created:
type: integer
minimum: 0
model:
type: string
choices:
type: array
maxItems: 1
items:
type: object
additionalProperties: false
required:
- index
- delta
- finish_reason
- logprobs
properties:
index:
const: 0
delta:
type: object
additionalProperties: false
required: []
properties:
role:
const: assistant
content:
type: string
tool_calls:
type: array
items:
type: object
additionalProperties: false
required:
- index
- id
- type
- function
properties:
index:
type: integer
minimum: 0
id:
type: string
type:
const: function
function:
type: object
additionalProperties: false
required:
- name
- arguments
properties:
name:
type: string
arguments:
type: string
finish_reason:
enum:
- null
- stop
- tool_calls
logprobs:
type: 'null'
usage:
anyOf:
- $ref: '#/components/schemas/OpenAIChatUsage'
- type: 'null'
OpenAIResponsePending:
type: object
additionalProperties: false
required:
- id
- object
- created_at
- completed_at
- status
- model
- output
- error
- incomplete_details
- store
- usage
properties:
id:
type: string
pattern: ^resp_
object:
const: response
created_at:
type: integer
minimum: 0
completed_at:
type: 'null'
status:
const: in_progress
model:
type: string
output:
type: array
maxItems: 0
error:
type: 'null'
incomplete_details:
type: 'null'
instructions:
anyOf:
- type: string
- type: 'null'
max_output_tokens:
anyOf:
- type: integer
minimum: 1
- type: 'null'
parallel_tool_calls:
type: boolean
previous_response_id:
type: 'null'
store:
const: false
tools:
type: array
items:
$ref: '#/components/schemas/OpenAIResponsesTool'
tool_choice:
anyOf:
- enum:
- auto
- none
- required
- type: object
additionalProperties: false
required:
- type
- name
properties:
type:
const: function
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
truncation:
const: disabled
metadata:
type: object
additionalProperties: false
properties: {}
usage:
type: 'null'
temperature:
type: 'null'
top_p:
type: 'null'
OpenAIResponsePendingItem:
oneOf:
- type: object
additionalProperties: false
required:
- type
- id
- status
- role
- content
properties:
type:
const: message
id:
type: string
status:
const: in_progress
role:
const: assistant
content:
type: array
items:
$ref: '#/components/schemas/OpenAIResponseContentPart'
- type: object
additionalProperties: false
required:
- type
- id
- status
- call_id
- name
- arguments
properties:
type:
const: function_call
id:
type: string
status:
const: in_progress
call_id:
type: string
name:
type: string
pattern: ^[A-Za-z0-9_-]{1,64}$
arguments:
type: string
OpenAIResponseEvent:
oneOf:
- type: object
additionalProperties: false
required:
- type
- sequence_number
- response
properties:
type:
const: response.created
sequence_number:
type: integer
minimum: 0
response:
$ref: '#/components/schemas/OpenAIResponsePending'
- type: object
additionalProperties: false
required:
- type
- sequence_number
- response
properties:
type:
const: response.in_progress
sequence_number:
type: integer
minimum: 0
response:
$ref: '#/components/schemas/OpenAIResponsePending'
- type: object
additionalProperties: false
required:
- type
- sequence_number
- response
properties:
type:
const: response.completed
sequence_number:
type: integer
minimum: 0
response:
$ref: '#/components/schemas/OpenAIResponse'
- type: object
additionalProperties: false
required:
- type
- sequence_number
- output_index
- item
properties:
type:
const: response.output_item.added
sequence_number:
type: integer
minimum: 0
output_index:
type: integer
minimum: 0
item:
$ref: '#/components/schemas/OpenAIResponsePendingItem'
- type: object
additionalProperties: false
required:
- type
- sequence_number
- output_index
- item
properties:
type:
const: response.output_item.done
sequence_number:
type: integer
minimum: 0
output_index:
type: integer
minimum: 0
item:
$ref: '#/components/schemas/OpenAIResponseOutputItem'
- type: object
additionalProperties: false
required:
- type
- sequence_number
- item_id
- output_index
- content_index
- part
properties:
type:
const: response.content_part.added
sequence_number:
type: integer
minimum: 0
item_id:
type: string
output_index:
type: integer
minimum: 0
content_index:
type: integer
minimum: 0
part:
$ref: '#/components/schemas/OpenAIResponseContentPart'
- type: object
additionalProperties: false
required:
- type
- sequence_number
- item_id
- output_index
- content_index
- part
properties:
type:
const: response.content_part.done
sequence_number:
type: integer
minimum: 0
item_id:
type: string
output_index:
type: integer
minimum: 0
content_index:
type: integer
minimum: 0
part:
$ref: '#/components/schemas/OpenAIResponseContentPart'
- type: object
additionalProperties: false
required:
- type
- sequence_number
- item_id
- output_index
- content_index
- delta
- logprobs
properties:
type:
const: response.output_text.delta
sequence_number:
type: integer
minimum: 0
item_id:
type: string
output_index:
type: integer
minimum: 0
content_index:
type: integer
minimum: 0
delta:
type: string
logprobs:
type: array
maxItems: 0
- type: object
additionalProperties: false
required:
- type
- sequence_number
- item_id
- output_index
- content_index
- text
- logprobs
properties:
type:
const: response.output_text.done
sequence_number:
type: integer
minimum: 0
item_id:
type: string
output_index:
type: integer
minimum: 0
content_index:
type: integer
minimum: 0
text:
type: string
logprobs:
type: array
maxItems: 0
- type: object
additionalProperties: false
required:
- type
- sequence_number
- item_id
- output_index
- delta
properties:
type:
const: response.function_call_arguments.delta
sequence_number:
type: integer
minimum: 0
item_id:
type: string
output_index:
type: integer
minimum: 0
delta:
type: string
- type: object
additionalProperties: false
required:
- type
- sequence_number
- item_id
- output_index
- arguments
- name
properties:
type:
const: response.function_call_arguments.done
sequence_number:
type: integer
minimum: 0
item_id:
type: string
output_index:
type: integer
minimum: 0
arguments:
type: string
name:
type: string
Operations
GET
/Generate text from a query prompt
POST/Generate text from a prompt or messages JSON body
GET/.well-known/oauth-protected-resource/mcpRead OAuth metadata for the MCP resource.
GET/api/management/accountRead the authenticated user and owned tenant summaries
GET/api/management/admin/usersRead the administrative user and tenant usage summary
GET/api/management/billing-accountsRead the authenticated owner's billing account
POST/api/management/billing-accountsCreate one USD billing account for the authenticated owner
GET/api/management/billing-accounts/{billing_account_id}Read an owned billing account
GET/api/management/billing-accounts/{billing_account_id}/balanceRead the funds of an owned billing account
GET/api/management/billing-accounts/{billing_account_id}/chargesRead charges for an owned billing account
GET/api/management/billing-accounts/{billing_account_id}/charges/{charge_id}Read one charge from an owned billing account
GET/api/management/billing-accounts/{billing_account_id}/funding-offersList server funding offers
GET/api/management/billing-accounts/{billing_account_id}/funding-ordersList owned funding orders
POST/api/management/billing-accounts/{billing_account_id}/funding-ordersCreate an owned funding order
GET/api/management/billing-accounts/{billing_account_id}/funding-orders/{order_id}Read an owned funding order
GET/api/management/billing-accounts/{billing_account_id}/funding-orders/{order_id}/checkoutRead the checkout for an owned funding order
GET/api/management/billing-accounts/{billing_account_id}/funding-orders/{order_id}/receiptRead the receipt for an owned funding order
GET/api/management/billing-accounts/{billing_account_id}/ledger-entriesRead Ledger entries of an owned billing account
POST/api/management/billing-accounts/{billing_account_id}/payment-portal-sessionsCreate a temporary Paddle customer portal session
GET/api/management/billing-accounts/{billing_account_id}/price-snapshots/{price_snapshot_id}Read the prices retained for an accepted request
GET/api/management/billing-accounts/{billing_account_id}/requestsRead the usage journal for an owned billing account
GET/api/management/billing-accounts/{billing_account_id}/requests/{request_id}Read one request from an owned usage journal
GET/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/attemptsRead attempts for an owned journal request
GET/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/charge-summaryRead the charge totals for an owned request
GET/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/funds-credits/{credit_id}Read an audited request credit
PUT/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/funds-credits/{credit_id}Record an operator credit for a settled request
GET/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/funds-resolutionRead an audited financial resolution
PUT/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/funds-resolutionRecord an operator decision for an uncertain hold
GET/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/observationsRead usage observations for an owned journal request
GET/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/reconciliation-casesRead reconciliation cases for an owned journal request
GET/api/management/billing-accounts/{billing_account_id}/reservationsRead reservations of an owned billing account
GET/api/management/billing-accounts/{billing_account_id}/reservations/{request_id}Read a reservation and its exact authorization
GET/api/management/billing-accounts/{billing_account_id}/tenant-limits/{tenant_id}Read the cumulative spending limit of an owned tenant
PUT/api/management/billing-accounts/{billing_account_id}/tenant-limits/{tenant_id}Set the cumulative spending limit of an owned tenant
GET/api/management/connectionsList account connections and provider definitions
POST/api/management/connectionsVerify credentials and create an account connection
DELETE/api/management/connections/{connection_id}Delete an unassigned connection
GET/api/management/connections/{connection_id}Read a connection with masked credentials
PUT/api/management/connections/{connection_id}Update a connection at its expected version
GET/api/management/hosted-access-grantsRead hosted access grants for the authenticated account
POST/api/management/hosted-access-grantsCreate a hosted access grant as an operator
GET/api/management/hosted-access-grants/{grant_id}Read one hosted access grant
PATCH/api/management/hosted-access-grants/{grant_id}Change grant state with a revision precondition
GET/api/management/hosted-access-grants/{grant_id}/revisionsRead the grant audit as an operator
GET/api/management/platform-connectionsRead platform connection metadata as an operator
POST/api/management/platform-connectionsVerify and create a platform connection as an operator
GET/api/management/platform-connections/{platform_connection_id}Read platform connection metadata as an operator
PUT/api/management/platform-connections/{platform_connection_id}Replace platform credentials while retaining accepted versions
POST/api/management/tenantsCreate an owned tenant
DELETE/api/management/tenants/{tenant_id}Delete an owned non-final tenant
GET/api/management/tenants/{tenant_id}Read an owned tenant profile
PUT/api/management/tenants/{tenant_id}Rename an owned tenant
GET/api/management/tenants/{tenant_id}/connectionsRead the tenant's explicit provider assignments
DELETE/api/management/tenants/{tenant_id}/connections/{provider}Detach the selected provider resource and optionally clear dependent defaults
PUT/api/management/tenants/{tenant_id}/connections/{provider}Select an account connection or hosted access grant for one provider
PUT/api/management/tenants/{tenant_id}/defaultsReplace the tenant routing defaults
PUT/api/management/tenants/{tenant_id}/provider-profiles/{provider}Save the tenant provider model and system prompt
POST/api/management/tenants/{tenant_id}/secretsGenerate and replace the tenant client secret
GET/api/management/tenants/{tenant_id}/usageRead interval-scoped usage for an owned tenant
GET/api/management/tenants/{tenant_id}/usage/failuresRead safe failure details for an owned tenant and interval
GET/api/management/tenants/{tenant_id}/usage/rejectionsRead safe rejected-request details for an owned tenant and interval
GET/api/management/usageRead interval-scoped usage across every owned tenant
GET/api/management/usage/failuresRead safe failure details across every owned tenant and interval
GET/api/management/usage/rejectionsRead safe rejected-request details across every owned tenant and interval
POST/api/payments/paddle/eventsRetain a verified Paddle event
GET/api/public/capabilitiesRead the public normalized model capability catalog
GET/config-ui.yamlRead the browser runtime configuration
POST/dictateTranscribe an audio upload
GET/healthzRead local datastore readiness without authentication or provider work.
POST/mcpUse an owned tenant through MCP.
POST/model/v1/assetsUpload exact tenant media bytes
DELETE/model/v1/assets/{asset_id}Delete one tenant asset
GET/model/v1/assets/{asset_id}Read one tenant asset metadata record
GET/model/v1/assets/{asset_id}/contentDownload exact tenant asset bytes
GET/model/v1/capabilitiesRead tenant-available durable media routes
POST/model/v1/operationsAccept one durable tenant media operation
GET/model/v1/operations/{operation_id}Read one durable tenant media operation
PUT/model/v1/operations/{operation_id}/cancellationRequest cancellation of one durable tenant media operation
GET/model/v1/provider-diagnostics/{provider}Read retained tenant operation counts for a provider
HEAD/model/v1/provider-diagnostics/{provider}Read diagnostic response headers without a response body
GET/model/v1/provider-resources/{provider}/{kind}Read assigned provider account metadata or quota
GET/model/v1/voicesDiscover and list tenant-owned provider voices
GET/model/v1/voices/{voice_id}Read one tenant-owned voice
GET/model/v1/voices/{voice_id}/previews/{preview}Read one account-bound voice preview
POST/v1/audio/transcriptionscreateTranscription
POST/v1/chat/completionscreateChatCompletion
GET/v1/modelslistClientModels
POST/v1/responsescreateResponse
POST/v2Generate text from canonical messages
GET/v2/identityRead the authenticated tenant identity
GET/v2/requestsReconcile a durable text request
/
getText
Generate text from a query prompt
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
prompt | query | Yes | string | User prompt. |
provider | query | No | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. Omission uses the tenant default. |
model | query | No | string | Model identifier. Omission uses the resolved provider default. |
web_search | query | No | boolean | Exact boolean query parameter. Use true or false; omission disables web search. Any other supplied spelling is invalid and returns HTTP 400. |
system_prompt | query | No | string | |
max_tokens | query | No | integer | Initial per-attempt output budget. A transport that declares continuation actions reuses this budget for a missing suffix. |
reasoning_effort | query | No | string | Non-blank effort supported by the resolved route. Omission selects the tenant or route default. |
format | query | No | string | Preferred response media type. Unknown values select text/plain. |
Accept | header | No | string | Response media preference used when format is omitted. |
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Idempotency-Key | header | No | string | Required for hosted text and dictation. The key identifies one tenant request across native and client protocols. An identical request returns its saved result or active receipt. Changed intent returns 409. Expired hosted results return 410. A hosted replay never starts another execution. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | text/plain, application/json, application/xml, text/csv | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-Tokens, X-LLM-Proxy-Response-Tokens, X-LLM-Proxy-Total-Tokens | Complete generated text in the selected representation. Each provider offering publishes one validated wire contract and an execution lifecycle for text-only requests. A media-capable offering also publishes media_execution_lifecycle for requests that contain image or audio input. The proxy does not infer a lifecycle from an endpoint or an upstream identifier. The proxy observes queued and in_progress states only for a pollable lifecycle. Each public operation remains blocking. Gemini media requests use synchronous completion and do not poll an Interaction resource. Transports with continuation actions continue exact output-budget stops through new provider calls. These transports are OpenAI Responses incomplete/max_output_tokens, OpenAI-compatible Chat Completions length, and Anthropic max_tokens. Gemini Interactions has no continuation actions. An incomplete result returns a provider error after cleanup. The adapter returns HTTP 200 only after the provider reports its complete signal. These signals are OpenAI or Gemini completed, Chat stop, or Anthropic end_turn or stop_sequence. Intermediate, safety, refusal, tool, malformed, missing, and unknown states do not return text as success. |
202 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | The durable request has not reached a terminal state. Reconcile the same key again. |
400 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The request is malformed, names an invalid route/capability, or supplies an invalid timeout. Text validation failures use the canonical plain-text error. Timeout-header validation uses the canonical JSON error. |
402 | application/json | none | The available funds cannot cover the accepted maximum cost. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
409 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The provider is not configured, or the key identifies a different intent or an uncertain provider outcome. |
410 | application/json | none | The saved hosted result expired. The journal keeps the request identity and prevents another execution. |
429 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider returned HTTP 429. The proxy preserves 429 at its public boundary and returns only sanitized provider metadata; it never exposes the raw provider body or message. |
499 | none | none | The caller canceled or closed the request. |
502 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The provider failed or returned an unusable response. A retained request failure uses the durable error representation. The proxy continues output-budget stops only when the execution contract permits another attempt. Errors exclude partial text, token-count headers, and raw provider errors. The journal can retain available usage after failure. |
503 | application/json, text/plain | X-LLM-Proxy-Request-Timeout-Seconds | The request queue is full or financial admission is unavailable. |
504 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The proxy request budget or upstream operation timed out. |
/
postText
Generate text from a prompt or messages JSON body
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
provider | query | No | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. Omission uses the tenant default. |
model | query | No | string | Model identifier. Omission uses the resolved provider default. |
format | query | No | string | Preferred response media type. Unknown values select text/plain. |
Accept | header | No | string | Response media preference used when format is omitted. |
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Idempotency-Key | header | No | string | Required for hosted text and dictation. The key identifies one tenant request across native and client protocols. An identical request returns its saved result or active receipt. Changed intent returns 409. Expired hosted results return 410. A hosted replay never starts another execution. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
prompt | No | string | |
messages | No | array<ChatMessage> | Each Gemini Interactions route rejects assistant history. Other routes retain their declared message behavior. |
model | No | string | |
web_search | No | boolean | |
speech_provider | No | string | Selected speech provider. An empty value clears the selection. |
speech_model | No | string | Selected speech model. An empty value clears the selection. |
system_prompt | No | string | |
max_tokens | No | integer | Initial output budget. A transport that declares continuation actions reuses it for missing-suffix attempts. |
reasoning_effort | No | string | Omission selects the tenant or route default. An explicit value must be non-blank and supported by the resolved provider/model route. |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | text/plain, application/json, application/xml, text/csv | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-Tokens, X-LLM-Proxy-Response-Tokens, X-LLM-Proxy-Total-Tokens | Complete generated text in the selected representation. Each provider offering publishes one validated wire contract and an execution lifecycle for text-only requests. A media-capable offering also publishes media_execution_lifecycle for requests that contain image or audio input. The proxy does not infer a lifecycle from an endpoint or an upstream identifier. The proxy observes queued and in_progress states only for a pollable lifecycle. Each public operation remains blocking. Gemini media requests use synchronous completion and do not poll an Interaction resource. Transports with continuation actions continue exact output-budget stops through new provider calls. These transports are OpenAI Responses incomplete/max_output_tokens, OpenAI-compatible Chat Completions length, and Anthropic max_tokens. Gemini Interactions has no continuation actions. An incomplete result returns a provider error after cleanup. The adapter returns HTTP 200 only after the provider reports its complete signal. These signals are OpenAI or Gemini completed, Chat stop, or Anthropic end_turn or stop_sequence. Intermediate, safety, refusal, tool, malformed, missing, and unknown states do not return text as success. |
202 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | The durable request has not reached a terminal state. Reconcile the same key again. |
400 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The request is malformed, names an invalid route/capability, or supplies an invalid timeout. Text validation failures use the canonical plain-text error. Timeout-header validation uses the canonical JSON error. |
402 | application/json | none | The available funds cannot cover the accepted maximum cost. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
409 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The provider is not configured, or the key identifies a different intent or an uncertain provider outcome. |
410 | application/json | none | The saved hosted result expired. The journal keeps the request identity and prevents another execution. |
413 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The compatibility JSON request limit, dictation audio limit, tenant asset limit, or selected provider media limit was exceeded. |
429 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider returned HTTP 429. The proxy preserves 429 at its public boundary and returns only sanitized provider metadata; it never exposes the raw provider body or message. |
499 | none | none | The caller canceled or closed the request. |
502 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The provider failed or returned an unusable response. A retained request failure uses the durable error representation. The proxy continues output-budget stops only when the execution contract permits another attempt. Errors exclude partial text, token-count headers, and raw provider errors. The journal can retain available usage after failure. |
503 | application/json, text/plain | X-LLM-Proxy-Request-Timeout-Seconds | The request queue is full or financial admission is unavailable. |
504 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The proxy request budget or upstream operation timed out. |
/.well-known/oauth-protected-resource/mcp
getMCPResourceMetadata
Read OAuth metadata for the MCP resource.
Authentication: None
Parameters
None.
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | none | The metadata identifies the TAuth issuer and required scope. |
/api/management/account
getManagementAccount
Read the authenticated user and owned tenant summaries
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Authenticated account snapshot. |
401 | none | none | The TAuth session is absent or invalid. |
500 | text/plain | none | The management operation failed internally. |
/api/management/admin/users
getManagementAdminUsers
Read the administrative user and tenant usage summary
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | none | Administrative user and tenant usage summary. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
500 | text/plain | none | The management operation failed internally. |
/api/management/billing-accounts
listBillingAccounts
Read the authenticated owner's billing account
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
None.
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The account list. A read does not create an account. |
401 | none | none | The TAuth session is absent or invalid. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts
createBillingAccount
Create one USD billing account for the authenticated owner
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Idempotency-Key | header | Yes | string | A creation key scoped to the authenticated actor and resource kind. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
currency | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
201 | application/json | Cache-Control, Location | The immutable account creation response, including on a retry with the same key. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
409 | application/json | Cache-Control | The hosted resource request failed. |
415 | none | none | A management mutation did not supply application/json. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}
getBillingAccount
Read an owned billing account
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The owned account. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/balance
getFundsBalance
Read the funds of an owned billing account
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Funds from one database snapshot. This read creates no financial records. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/charges
listCharges
Read charges for an owned billing account
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
limit | query | No | integer | |
cursor | query | No | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The retained account resource. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/charges/{charge_id}
getCharge
Read one charge from an owned billing account
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
charge_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The retained account resource. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/funding-offers
listFundingOffers
List server funding offers
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The owned funding resource. |
400 | application/json | Cache-Control | The funding request failed without a financial effect. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The funding request failed without a financial effect. |
500 | application/json | Cache-Control | The hosted resource request failed. |
503 | application/json | Cache-Control | The funding request failed without a financial effect. |
/api/management/billing-accounts/{billing_account_id}/funding-orders
listFundingOrders
List owned funding orders
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
limit | query | No | integer | |
cursor | query | No | string | Continue after this identifier in ascending identifier order. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The owned funding resource. |
400 | application/json | Cache-Control | The funding request failed without a financial effect. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The funding request failed without a financial effect. |
500 | application/json | Cache-Control | The hosted resource request failed. |
503 | application/json | Cache-Control | The funding request failed without a financial effect. |
/api/management/billing-accounts/{billing_account_id}/funding-orders
createFundingOrder
Create an owned funding order
Select one server offer. Commit its immutable price, USD funding amount, processor identity, and checkout delivery intent in one transaction. The account and creation key identify one order. A repeated key returns that order. A changed offer or processor identity returns 409. Order creation does not grant funds or confirm payment.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Idempotency-Key | header | Yes | string | A creation key scoped to the authenticated actor and resource kind. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
offer_code | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
201 | application/json | Cache-Control, Location | The owned funding resource. |
400 | application/json | Cache-Control | The funding request failed without a financial effect. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The funding request failed without a financial effect. |
409 | application/json | Cache-Control | The funding request failed without a financial effect. |
415 | none | none | A management mutation did not supply application/json. |
500 | application/json | Cache-Control | The hosted resource request failed. |
503 | application/json | Cache-Control | The funding request failed without a financial effect. |
/api/management/billing-accounts/{billing_account_id}/funding-orders/{order_id}
getFundingOrder
Read an owned funding order
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
order_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The owned funding resource. |
400 | application/json | Cache-Control | The funding request failed without a financial effect. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The funding request failed without a financial effect. |
500 | application/json | Cache-Control | The hosted resource request failed. |
503 | application/json | Cache-Control | The funding request failed without a financial effect. |
/api/management/billing-accounts/{billing_account_id}/funding-orders/{order_id}/checkout
getPaymentCheckout
Read the checkout for an owned funding order
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
order_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The owned funding resource. |
400 | application/json | Cache-Control | The funding request failed without a financial effect. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The funding request failed without a financial effect. |
500 | application/json | Cache-Control | The hosted resource request failed. |
503 | application/json | Cache-Control | The funding request failed without a financial effect. |
/api/management/billing-accounts/{billing_account_id}/funding-orders/{order_id}/receipt
getPaymentReceipt
Read the receipt for an owned funding order
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
order_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The owned funding resource. |
400 | application/json | Cache-Control | The funding request failed without a financial effect. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The funding request failed without a financial effect. |
500 | application/json | Cache-Control | The hosted resource request failed. |
503 | application/json | Cache-Control | The funding request failed without a financial effect. |
/api/management/billing-accounts/{billing_account_id}/ledger-entries
listFundsEntries
Read Ledger entries of an owned billing account
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
limit | query | No | integer | |
cursor | query | No | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Entries in ascending identifier order. The cursor is the last identifier of a nonfinal page. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/payment-portal-sessions
createPaymentPortalSession
Create a temporary Paddle customer portal session
Each request creates a temporary link without a financial effect. Do not cache or store the link.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
201 | application/json | Location, Cache-Control | The temporary portal session. |
400 | application/json | Cache-Control | The funding request failed without a financial effect. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The funding request failed without a financial effect. |
415 | none | none | A management mutation did not supply application/json. |
500 | application/json | Cache-Control | The hosted resource request failed. |
503 | application/json | Cache-Control | The funding request failed without a financial effect. |
/api/management/billing-accounts/{billing_account_id}/price-snapshots/{price_snapshot_id}
getPriceSnapshot
Read the prices retained for an accepted request
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
price_snapshot_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The retained account resource. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/requests
listJournalRequests
Read the usage journal for an owned billing account
Results use ascending request identifiers. Each response contains at most 100 requests. Credentials and request content are omitted.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
limit | query | No | integer | |
cursor | query | No | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The account usage journal page. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}
getJournalRequest
Read one request from an owned usage journal
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
request_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The retained request and its usage completeness. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/attempts
listJournalAttempts
Read attempts for an owned journal request
Results use ascending opaque identifiers. Each response contains at most 100 records. Private provider identifiers and source content are omitted.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
request_id | path | Yes | string | |
limit | query | No | integer | |
cursor | query | No | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The owned request collection page. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/charge-summary
getRequestChargeSummary
Read the charge totals for an owned request
Totals include all attempts and customer credits from one database snapshot. Pending or unresolved customer totals are null.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
request_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The current request totals. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/funds-credits/{credit_id}
getFundsCredit
Read an audited request credit
The account owner or an operator can read this receipt. Private operator identity and evidence references remain in the audit record.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
None.
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The retained credit. Provider evidence remains unchanged. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/funds-credits/{credit_id}
createFundsCredit
Record an operator credit for a settled request
Requires an operator session. Total credits cannot exceed the settled request charge. An identical repeat has one financial effect.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
None.
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
credit | Yes | object | An exact nonnegative USD amount expressed as a reduced fraction. |
reason | Yes | string | |
evidence_reference | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The immutable credit and returned whole cents. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The hosted resource request failed. |
409 | application/json | Cache-Control | The hosted resource request failed. |
415 | none | none | A management mutation did not supply application/json. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/funds-resolution
getFundsResolution
Read an audited financial resolution
The account owner or an operator can read this receipt. Private operator identity and evidence references remain in the audit record.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
None.
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The retained financial decision. Provider evidence remains unchanged. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/funds-resolution
createFundsResolution
Record an operator decision for an uncertain hold
Requires an operator session and the current reservation revision. Authorization, known pricing, and prior credits bound the final net charge. An identical repeat has one financial effect.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
None.
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
revision | Yes | integer | |
customer_charge | Yes | object | An exact nonnegative USD amount expressed as a reduced fraction. |
reason | Yes | string | |
evidence_reference | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The immutable decision and settled amount. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The hosted resource request failed. |
409 | application/json | Cache-Control | The hosted resource request failed. |
415 | none | none | A management mutation did not supply application/json. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/observations
listJournalObservations
Read usage observations for an owned journal request
Results use ascending opaque identifiers. Each response contains at most 100 records. Private provider identifiers and source content are omitted.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
request_id | path | Yes | string | |
limit | query | No | integer | |
cursor | query | No | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The owned request collection page. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/requests/{request_id}/reconciliation-cases
listJournalReconciliationCases
Read reconciliation cases for an owned journal request
Results use ascending opaque identifiers. Each response contains at most 100 records. Private provider identifiers and source content are omitted.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
request_id | path | Yes | string | |
limit | query | No | integer | |
cursor | query | No | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The owned request collection page. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/reservations
listFundsReservations
Read reservations of an owned billing account
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
limit | query | No | integer | |
cursor | query | No | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Reservations in ascending identifier order. The cursor is the last identifier of a nonfinal page. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/reservations/{request_id}
getFundsReservation
Read a reservation and its exact authorization
Requires the account owner or an operator. The revision and exact maximum support an audited financial decision.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
billing_account_id | path | Yes | string | |
request_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The current reservation and immutable authorization. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/tenant-limits/{tenant_id}
getTenantFundsLimit
Read the cumulative spending limit of an owned tenant
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
None.
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Exact net usage and active reservations under the optional limit. This read creates no records. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/billing-accounts/{billing_account_id}/tenant-limits/{tenant_id}
setTenantFundsLimit
Set the cumulative spending limit of an owned tenant
The revision prevents concurrent replacement. A repeated identical last change returns the current resource. Existing reservations remain authorized.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
None.
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
limit_cents | Yes | string,null | Cumulative USD limit in cents, through the maximum signed 64-bit integer. Null removes the tenant limit. |
revision | Yes | integer |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The retained limit and current usage. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The hosted resource request failed. |
409 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/connections
listManagementConnections
List account connections and provider definitions
Connections use ascending ID order. Continue with next_cursor. An empty next_cursor indicates the last page.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
limit | query | No | integer | |
cursor | query | No | string | The next_cursor from the previous page. The cursor remains valid after connection deletion. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Operation completed. |
400 | application/json | Cache-Control | The connection operation failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The connection operation failed. |
409 | application/json | Cache-Control | The connection operation failed. |
500 | application/json | Cache-Control | The connection operation failed. |
/api/management/connections
createManagementConnection
Verify credentials and create an account connection
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Idempotency-Key | header | Yes | string | Account-scoped key for one connection creation request. Repeat the same key and request to receive the original 201 response and Location. A changed request returns 409. Receipts survive connection deletion. Read the connection resource for its current state. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
name | Yes | string | |
provider | Yes | string | |
fields | Yes | object | |
version | No | integer | Use zero or omit on creation. Updates require the current connection version. |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
201 | application/json | Cache-Control, Location | Operation completed. |
400 | application/json | Cache-Control | The connection operation failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The connection operation failed. |
409 | application/json | Cache-Control | The connection operation failed. |
415 | none | none | A management mutation did not supply application/json. |
422 | text/plain | none | The candidate credential was rejected or cannot access the selected text model. Nothing was saved. |
429 | text/plain | none | The provider rate-limited the single verification operation. The credential remains unconfirmed and nothing was saved. |
500 | application/json | Cache-Control | The connection operation failed. |
503 | text/plain | none | The provider was unavailable or returned a malformed success envelope. The credential remains unconfirmed and nothing was saved. |
504 | text/plain | none | The single verification operation timed out or was canceled. The credential remains unconfirmed and nothing was saved. |
/api/management/connections/{connection_id}
deleteManagementConnection
Delete an unassigned connection
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
connection_id | path | Yes | string | |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
204 | none | Cache-Control | Operation completed. |
400 | application/json | Cache-Control | The connection operation failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The connection operation failed. |
409 | application/json | Cache-Control | The connection operation failed. |
415 | none | none | A management mutation did not supply application/json. |
500 | application/json | Cache-Control | The connection operation failed. |
/api/management/connections/{connection_id}
getManagementConnection
Read a connection with masked credentials
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
connection_id | path | Yes | string | |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Operation completed. |
400 | application/json | Cache-Control | The connection operation failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The connection operation failed. |
409 | application/json | Cache-Control | The connection operation failed. |
500 | application/json | Cache-Control | The connection operation failed. |
/api/management/connections/{connection_id}
replaceManagementConnection
Update a connection at its expected version
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
connection_id | path | Yes | string | |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
name | Yes | string | |
provider | Yes | string | |
fields | Yes | object | |
version | No | integer | Use zero or omit on creation. Updates require the current connection version. |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Operation completed. |
400 | application/json | Cache-Control | The connection operation failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The connection operation failed. |
409 | application/json | Cache-Control | The connection operation failed. |
415 | none | none | A management mutation did not supply application/json. |
422 | text/plain | none | The candidate credential was rejected or cannot access the selected text model. Nothing was saved. |
429 | text/plain | none | The provider rate-limited the single verification operation. The credential remains unconfirmed and nothing was saved. |
500 | application/json | Cache-Control | The connection operation failed. |
503 | text/plain | none | The provider was unavailable or returned a malformed success envelope. The credential remains unconfirmed and nothing was saved. |
504 | text/plain | none | The single verification operation timed out or was canceled. The credential remains unconfirmed and nothing was saved. |
/api/management/hosted-access-grants
listHostedAccessGrants
Read hosted access grants for the authenticated account
Operators can read all grants. Results use ascending ID order and an exclusive cursor.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
limit | query | No | integer | |
cursor | query | No | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The account grants without platform credentials or private provider handles. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/hosted-access-grants
createHostedAccessGrant
Create a hosted access grant as an operator
Creation binds one tenant to its billing account and explicit provider offerings. A grant does not bypass pricing, metering, funds admission, or the hosted activation gate. The original creation response remains available after grant changes and catalog changes.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Idempotency-Key | header | Yes | string | A creation key scoped to the authenticated actor and resource kind. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
billing_account_id | Yes | string | |
tenant_id | Yes | string | |
platform_connection_id | Yes | string | |
catalog_revision | Yes | string | |
offerings | Yes | array<object> | Exact models or explicit services from one provider. An omitted model selects services, never all models. |
reason | Yes | string | Operator reason without leading or trailing whitespace. Customer responses omit this field. |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
201 | application/json | Cache-Control, Location | The retained creation response. Read the resource for its current state. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The hosted resource request failed. |
409 | application/json | Cache-Control | The hosted resource request failed. |
415 | none | none | A management mutation did not supply application/json. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/hosted-access-grants/{grant_id}
getHostedAccessGrant
Read one hosted access grant
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
grant_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The grant state. Only operators receive the platform connection identifier. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/hosted-access-grants/{grant_id}
changeHostedAccessGrant
Change grant state with a revision precondition
Only operators can change grants. Each change records its actor and reason in the same transaction. Suspended grants can return to active state. Revoked grants cannot return to another state. A stale revision or an unchanged state returns a conflict. Read the current resource before another change.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
grant_id | path | Yes | string |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
state | Yes | string | |
revision | Yes | integer | |
reason | Yes | string | Operator reason without leading or trailing whitespace. Customer responses omit this field. |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The grant state. Only operators receive the platform connection identifier. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The hosted resource request failed. |
409 | application/json | Cache-Control | The hosted resource request failed. |
415 | none | none | A management mutation did not supply application/json. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/hosted-access-grants/{grant_id}/revisions
listHostedAccessGrantRevisions
Read the grant audit as an operator
Revisions use ascending order. Each cursor identifies the last revision on the previous page.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
grant_id | path | Yes | string | |
limit | query | No | integer | |
cursor | query | No | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Retained grant revisions with operator identity and reason. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/platform-connections
listPlatformConnections
Read platform connection metadata as an operator
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
limit | query | No | integer | |
cursor | query | No | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Connection metadata in ascending identifier order. Credentials are excluded. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/platform-connections
createPlatformConnection
Verify and create a platform connection as an operator
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Idempotency-Key | header | Yes | string | A creation key scoped to the authenticated actor and resource kind. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
name | Yes | string | |
provider | Yes | string | |
fields | Yes | object | |
version | No | integer |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
201 | application/json | Cache-Control, Location | The immutable creation receipt. Repeated keys require identical intent. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
409 | application/json | Cache-Control | The hosted resource request failed. |
415 | none | none | A management mutation did not supply application/json. |
422 | text/plain | none | The candidate credential was rejected or cannot access the selected text model. Nothing was saved. |
429 | text/plain | none | The provider rate-limited the single verification operation. The credential remains unconfirmed and nothing was saved. |
500 | application/json | Cache-Control | The hosted resource request failed. |
503 | text/plain | none | The provider was unavailable or returned a malformed success envelope. The credential remains unconfirmed and nothing was saved. |
504 | text/plain | none | The single verification operation timed out or was canceled. The credential remains unconfirmed and nothing was saved. |
/api/management/platform-connections/{platform_connection_id}
getPlatformConnection
Read platform connection metadata as an operator
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
platform_connection_id | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Platform metadata without credentials. Only operators can read this resource. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The hosted resource request failed. |
500 | application/json | Cache-Control | The hosted resource request failed. |
/api/management/platform-connections/{platform_connection_id}
rotatePlatformConnection
Replace platform credentials while retaining accepted versions
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
platform_connection_id | path | Yes | string |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
name | Yes | string | |
provider | Yes | string | |
fields | Yes | object | |
version | No | integer |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Platform metadata without credentials. Only operators can read this resource. |
400 | application/json | Cache-Control | The hosted resource request failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The hosted resource request failed. |
409 | application/json | Cache-Control | The hosted resource request failed. |
415 | none | none | A management mutation did not supply application/json. |
422 | text/plain | none | The candidate credential was rejected or cannot access the selected text model. Nothing was saved. |
429 | text/plain | none | The provider rate-limited the single verification operation. The credential remains unconfirmed and nothing was saved. |
500 | application/json | Cache-Control | The hosted resource request failed. |
503 | text/plain | none | The provider was unavailable or returned a malformed success envelope. The credential remains unconfirmed and nothing was saved. |
504 | text/plain | none | The single verification operation timed out or was canceled. The credential remains unconfirmed and nothing was saved. |
/api/management/tenants
createManagementTenant
Create an owned tenant
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
name | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
201 | application/json | Cache-Control | Created tenant profile. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
409 | text/plain | none | The requested tenant name conflicts, the final owned tenant cannot be deleted, or a retained provider credential changed after verification began. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}
deleteManagementTenant
Delete an owned non-final tenant
Tenants with hosted grant history cannot be deleted. The service returns 409 with managed_tenant_hosted_history.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
204 | none | none | Tenant deleted. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
409 | text/plain | none | The requested tenant name conflicts, the final owned tenant cannot be deleted, or a retained provider credential changed after verification began. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}
getManagementTenant
Read an owned tenant profile
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Current tenant profile. |
401 | none | none | The TAuth session is absent or invalid. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}
renameManagementTenant
Rename an owned tenant
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
name | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Current tenant profile. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
409 | text/plain | none | The requested tenant name conflicts, the final owned tenant cannot be deleted, or a retained provider credential changed after verification began. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}/connections
listManagementProviderAssignments
Read the tenant's explicit provider assignments
The list contains one assignment per selected provider, in provider ID order. It contains no platform credentials.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The tenant's selected account connections and hosted access grants. |
401 | none | none | The TAuth session is absent or invalid. |
404 | application/json | none | The tenant does not belong to the authenticated account. |
500 | application/json | none | The assignment store is unavailable. |
/api/management/tenants/{tenant_id}/connections/{provider}
detachManagementConnection
Detach the selected provider resource and optionally clear dependent defaults
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
provider | path | Yes | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. |
clear_defaults | query | No | string | Use true to confirm removal of dependent default routes. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
204 | none | Cache-Control | Operation completed. |
400 | application/json | Cache-Control | The connection operation failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The connection operation failed. |
409 | application/json | Cache-Control | The connection operation failed. |
415 | none | none | A management mutation did not supply application/json. |
500 | application/json | Cache-Control | The connection operation failed. |
/api/management/tenants/{tenant_id}/connections/{provider}
assignManagementConnection
Select an account connection or hosted access grant for one provider
The resource must belong to the tenant's account. A hosted grant must also name this tenant and provider. Detach the current assignment before selecting a different resource. The service does not substitute credential sources.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
provider | path | Yes | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
kind | Yes | string | |
resource_id | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Operation completed. |
400 | application/json | Cache-Control | The connection operation failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The connection operation failed. |
409 | application/json | Cache-Control | The connection operation failed. |
415 | none | none | A management mutation did not supply application/json. |
500 | application/json | Cache-Control | The connection operation failed. |
/api/management/tenants/{tenant_id}/defaults
putManagementTenantDefaults
Replace the tenant routing defaults
Every nonempty provider/model pair must use a provider for which this tenant has a saved API key. The text pair is empty only when no provider key exists. An empty dictation pair is a valid unset selection. A catalog capability change preserves it.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
provider | Yes | string | Canonical configured text provider, or empty with model when no provider connection exists. |
model | Yes | string | Canonical model for provider, or empty with provider when no provider connection exists. |
transcription_provider | Yes | string | Canonical configured transcription provider, or empty with transcription_model for an unset selection. |
transcription_model | Yes | string | Canonical transcription model, or empty with transcription_provider for an unset selection. |
speech_provider | No | string | Selected speech provider. An empty value clears the selection. |
speech_model | No | string | Selected speech model. An empty value clears the selection. |
system_prompt | Yes | string | |
reasoning_effort | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Current tenant profile. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}/provider-profiles/{provider}
updateManagementProviderProfile
Save the tenant provider model and system prompt
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
provider | path | Yes | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
text_model | Yes | string | |
speech_provider | No | string | Selected speech provider. An empty value clears the selection. |
speech_model | No | string | Selected speech model. An empty value clears the selection. |
system_prompt | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Operation completed. |
400 | application/json | Cache-Control | The connection operation failed. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | application/json | Cache-Control | The connection operation failed. |
409 | application/json | Cache-Control | The connection operation failed. |
415 | none | none | A management mutation did not supply application/json. |
500 | application/json | Cache-Control | The connection operation failed. |
/api/management/tenants/{tenant_id}/secrets
postManagementTenantSecret
Generate and replace the tenant client secret
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The newly generated tenant client secret and current profile. The secret is returned only by this response. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}/usage
getManagementTenantUsage
Read interval-scoped usage for an owned tenant
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
interval | query | Yes | string | |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Usage summary for the exact requested interval and authenticated reporting scope. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}/usage/failures
getManagementTenantUsageFailures
Read safe failure details for an owned tenant and interval
Returns a newest-first snapshot page of failed managed proxy events. Rows expose only bounded diagnostic metadata and canonical outcome codes; they never include prompts, responses, provider bodies, free-form errors, credentials, or ownership identifiers. Historical rows use status-derived normalized outcome codes rather than reconstructed error messages.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
interval | query | Yes | string | |
limit | query | No | integer | Maximum failure rows in this page. Omission selects 25. |
cursor | query | No | string | Opaque continuation cursor returned by the preceding page for the same interval and reporting scope. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Snapshot page of safe tenant failure details for the exact requested interval. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}/usage/rejections
getManagementTenantUsageRejections
Read safe rejected-request details for an owned tenant and interval
Returns a newest-first snapshot page of rejected managed proxy requests. These requests did not reach provider dispatch and are excluded from execution and failure metrics. Rows expose only bounded diagnostic metadata and canonical rejection outcomes.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
interval | query | Yes | string | |
limit | query | No | integer | Maximum failure rows in this page. Omission selects 25. |
cursor | query | No | string | Opaque continuation cursor returned by the preceding page for the same interval and reporting scope. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Snapshot page of safe tenant rejection details for the exact requested interval. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
500 | text/plain | none | The management operation failed internally. |
/api/management/usage
getManagementAccountUsage
Read interval-scoped usage across every owned tenant
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
interval | query | Yes | string | |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Usage summary for the exact requested interval and authenticated reporting scope. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
500 | text/plain | none | The management operation failed internally. |
/api/management/usage/failures
getManagementAccountUsageFailures
Read safe failure details across every owned tenant and interval
Returns a newest-first snapshot page of failed managed proxy events across every tenant owned by the authenticated user. Each row identifies its tenant by opaque ID and current name while exposing only bounded diagnostic metadata and canonical outcome codes. Rows never include prompts, responses, provider bodies, free-form errors, credentials, or another user's ownership data.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
interval | query | Yes | string | |
limit | query | No | integer | Maximum failure rows in this page. Omission selects 25. |
cursor | query | No | string | Opaque continuation cursor returned by the preceding page for the same interval and reporting scope. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Snapshot page of safe failure details across every owned tenant for the exact requested interval. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
500 | text/plain | none | The management operation failed internally. |
/api/management/usage/rejections
getManagementAccountUsageRejections
Read safe rejected-request details across every owned tenant and interval
Returns a newest-first snapshot page of rejected managed proxy requests across every tenant owned by the authenticated user. Rejected requests did not reach provider dispatch and are excluded from execution totals, failure totals, charts, dimensions, status breakdowns, and success rate. Each row exposes only bounded diagnostic metadata and its canonical rejection outcome.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
interval | query | Yes | string | |
limit | query | No | integer | Maximum failure rows in this page. Omission selects 25. |
cursor | query | No | string | Opaque continuation cursor returned by the preceding page for the same interval and reporting scope. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Snapshot page of safe rejection details across every owned tenant for the exact requested interval. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
500 | text/plain | none | The management operation failed internally. |
/api/payments/paddle/events
receivePaddlePaymentEvent
Retain a verified Paddle event
Verifies the signature against raw bytes before JSON parsing. The configured secret binds the event to one processor account and environment. A successful response confirms durable inbox storage, not a funding credit. Identical events have one inbox record. Changed content for the same event returns 409. This receiver currently has controlled development integration only.
Authentication: PaddleSignature (header Paddle-Signature)
Parameters
None.
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
event_id | Yes | string | |
event_type | Yes | string | |
occurred_at | Yes | string | |
data | Yes | object |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The verified event is in the durable inbox. |
400 | application/json | Cache-Control | The payment event was rejected or could not be retained. |
401 | application/json | Cache-Control | The payment event was rejected or could not be retained. |
409 | application/json | Cache-Control | The payment event was rejected or could not be retained. |
413 | application/json | Cache-Control | The payment event was rejected or could not be retained. |
415 | application/json | Cache-Control | The payment event was rejected or could not be retained. |
503 | application/json | Cache-Control | The payment event was rejected or could not be retained. |
/api/public/capabilities
getPublicCapabilities
Read the public normalized model capability catalog
Returns the deterministic, secret-free projection of model publishers, families, exact models, provider offerings, and public proxy request limits.
Authentication: None
Parameters
None.
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Access-Control-Allow-Origin, Cache-Control | Current public capability catalog. |
/config-ui.yaml
getBrowserConfiguration
Read the browser runtime configuration
Authentication: None
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/yaml | Cache-Control | Current browser runtime configuration. |
/dictate
postDictation
Transcribe an audio upload
Hosted dictation requires Idempotency-Key. Identical audio and format replay the accepted request across both transcription interfaces. The usage journal retains provider measurements and the request identity after result expiry.
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
provider | query | No | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. Omission uses the tenant default. |
model | query | No | string | Model identifier. Omission uses the resolved provider default. |
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Idempotency-Key | header | No | string | Required for hosted text and dictation. The key identifies one tenant request across native and client protocols. An identical request returns its saved result or active receipt. Changed intent returns 409. Expired hosted results return 410. A hosted replay never starts another execution. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
audio | Yes | string | The canonical incoming audio file part. |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | Transcription result. |
202 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | The durable request has not reached a terminal state. Reconcile the same key again. |
400 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The request is malformed, names an invalid route/capability, or supplies an invalid timeout. Text validation failures use the canonical plain-text error. Timeout-header validation uses the canonical JSON error. |
402 | application/json | none | The available funds cannot cover the accepted maximum cost. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
409 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The provider is not configured, or the key identifies a different intent or an uncertain provider outcome. |
410 | application/json | none | The saved hosted result expired. The journal keeps the request identity and prevents another execution. |
413 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The compatibility JSON request limit, dictation audio limit, tenant asset limit, or selected provider media limit was exceeded. |
429 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider returned HTTP 429. The proxy preserves 429 at its public boundary and returns only sanitized provider metadata; it never exposes the raw provider body or message. |
499 | none | none | The caller canceled or closed the request. |
502 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The provider failed or returned an unusable response. A retained request failure uses the durable error representation. The proxy continues output-budget stops only when the execution contract permits another attempt. Errors exclude partial text, token-count headers, and raw provider errors. The journal can retain available usage after failure. |
503 | application/json, text/plain | X-LLM-Proxy-Request-Timeout-Seconds | The request queue is full or financial admission is unavailable. |
504 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The proxy request budget or upstream operation timed out. |
/healthz
getHealth
Read local datastore readiness without authentication or provider work.
Authentication: None
Parameters
None.
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The local datastore is available. |
503 | application/json | Cache-Control | The local datastore is unavailable. |
/mcp
postMCPRequest
Use an owned tenant through MCP.
Stateless Streamable HTTP supports 2026-07-28, 2025-11-25, 2025-06-18, and 2025-03-26 with JSON responses. The 2025 revisions use initialize and notifications/initialized. The 2026 revision uses server/discover and per-request protocol metadata. TAuth issues tokens for the API origin with the llm-proxy:use scope. Each request requires a bearer token. The body must arrive within server.request_timeout_seconds and cannot exceed 8 MiB. An upload timeout returns HTTP 408 before tool execution. Generation uses a separate request_timeout_seconds budget after the upload. The llm_proxy.list_tenants tool provides all owned tenant summaries. The llm_proxy.generate_text tool requires tenant_id and messages. Hosted text also requires idempotency_key and returns the original execution identifier for identical requests. A concurrent hosted request returns state dispatched without generated text. The llm-proxy://tenants/{tenant_id}/routes resource template provides configured text routes. Tool execution failures use isError with a sanitized code. Resource errors and protocol errors use JSON-RPC errors with the protocol HTTP status.
Authentication: MCPAccessToken (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
MCP-Protocol-Version | header | No | string | Send the negotiated version after initialization. The initial handshake can omit this header. An absent header selects the protocol-defined 2025-03-26 default. Repeated headers are rejected. |
Mcp-Method | header | No | string | Required for 2026-07-28. The value must equal the JSON-RPC method. |
Mcp-Name | header | No | string | Supply the tool name for tools/call or the resource URI for resources/read. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
jsonrpc | Yes | string | |
id | Yes | string,integer | |
method | Yes | string | |
params | No | object | The MCP method defines parameters and required protocol metadata. |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | none | An MCP result or application error. |
202 | none | none | The handshake-family notification was accepted. The response has no body. |
400 | none | none | The protocol version, resource URI, or request is invalid. |
401 | none | WWW-Authenticate | A valid TAuth OAuth access token is required. |
403 | none | none | The required scope is absent or the origin is prohibited. |
404 | none | none | The MCP method is unknown. |
406 | none | none | The Accept header does not permit the required response type. |
408 | none | none | The request body did not arrive within the server timeout or the request was canceled. |
413 | none | none | The request exceeds the configured message limit. |
415 | none | none | The request content type is unsupported. |
500 | none | none | The requested resource is unavailable because of a server error. |
/model/v1/assets
uploadTenantAsset
Upload exact tenant media bytes
Stores one media asset for the configured retention period. The authenticated tenant owns the returned opaque asset id.
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
201 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset is available to its authenticated tenant. |
400 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
413 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
499 | none | none | The caller canceled or closed the request. |
500 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
504 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The proxy request budget or upstream operation timed out. |
/model/v1/assets/{asset_id}
deleteTenantAsset
Delete one tenant asset
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
asset_id | path | Yes | string | Opaque tenant asset identifier. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
204 | none | none | The asset is deleted. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
404 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
410 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
500 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
/model/v1/assets/{asset_id}
getTenantAsset
Read one tenant asset metadata record
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
asset_id | path | Yes | string | Opaque tenant asset identifier. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | none | The asset metadata is available to its authenticated tenant. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
404 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
410 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
500 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
/model/v1/assets/{asset_id}/content
downloadTenantAsset
Download exact tenant asset bytes
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
asset_id | path | Yes | string | Opaque tenant asset identifier. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json, application/x-subrip, image/jpeg, image/png, image/webp, audio/m4a, audio/mpeg, audio/wav, audio/flac, audio/ogg, video/mp4, video/webm, application/octet-stream | none | Exact authenticated asset bytes. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
404 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
410 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
500 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
/model/v1/capabilities
getTenantMediaCapabilities
Read tenant-available durable media routes
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
None.
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | none | Tenant-available media capability routes. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
/model/v1/operations
createTenantMediaOperation
Accept one durable tenant media operation
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Idempotency-Key | header | Yes | string | Tenant-bound key for one durable media operation intent. Exact repeats converge to the retained operation or tombstone. Changed intent returns 409 before dispatch. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | none | Current durable media operation state. |
202 | application/json | none | Current durable media operation state. |
400 | application/json | none | The media operation request failed with a stable caller-safe code. |
402 | application/json | none | The media operation request failed with a stable caller-safe code. |
403 | text/plain, application/json | none | The tenant key is unknown or the financial account is suspended. |
409 | application/json | none | The media operation request failed with a stable caller-safe code. |
410 | application/json | none | Terminal operation detail expired. The tenant idempotency tombstone remains. |
422 | application/json | none | The media operation request failed with a stable caller-safe code. |
429 | application/json | none | The media operation request failed with a stable caller-safe code. |
500 | application/json | none | The media operation request failed with a stable caller-safe code. |
503 | application/json | none | The media operation request failed with a stable caller-safe code. |
/model/v1/operations/{operation_id}
getTenantMediaOperation
Read one durable tenant media operation
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
operation_id | path | Yes | string | Opaque durable media operation identifier. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | none | Current durable media operation state. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
404 | application/json | none | The media operation request failed with a stable caller-safe code. |
410 | application/json | none | Terminal operation detail expired. The tenant idempotency tombstone remains. |
/model/v1/operations/{operation_id}/cancellation
cancelTenantMediaOperation
Request cancellation of one durable tenant media operation
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
operation_id | path | Yes | string | Opaque durable media operation identifier. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | none | Current durable media operation state. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
404 | application/json | none | The media operation request failed with a stable caller-safe code. |
422 | application/json | none | The media operation request failed with a stable caller-safe code. |
/model/v1/provider-diagnostics/{provider}
getProviderDiagnostics
Read retained tenant operation counts for a provider
Counts include only retained media operations owned by the authenticated tenant for the selected provider. Each accepted operation counts once. Repeated status reads and idempotent retries do not add operations. Counts include every retained state, including uncertain. Terminal detail expiry removes its count. These are retained operation counts, not lifetime usage or billing totals. An assigned connection is required. Connection changes do not transfer another tenant's history. The request does not contact the provider or return server health, uptime, or global latency.
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
provider | path | Yes | string | |
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Retained tenant operation counts for one assigned provider. |
400 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The request is malformed, names an invalid route/capability, or supplies an invalid timeout. Text validation failures use the canonical plain-text error. Timeout-header validation uses the canonical JSON error. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
404 | application/json | Cache-Control | A diagnostic read failed with a stable public code. |
405 | application/json | Cache-Control | A diagnostic read failed with a stable public code. |
500 | application/json | Cache-Control | A diagnostic read failed with a stable public code. |
/model/v1/provider-diagnostics/{provider}
getProviderDiagnosticsHeaders
Read diagnostic response headers without a response body
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
provider | path | Yes | string | |
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | none | Cache-Control | Retained tenant operation counts are available. |
default | none | none | The diagnostic read failed. The response has no body. |
/model/v1/provider-resources/{provider}/{kind}
getTenantProviderResource
Read assigned provider account metadata or quota
Account observations do not add executable model routes. The YAML catalog controls available routes.
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
provider | path | Yes | string | |
kind | path | Yes | string |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Current provider account observation. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
404 | application/json | none | The assigned resource is absent or the provider observation is unavailable. |
502 | application/json | none | The assigned resource is absent or the provider observation is unavailable. |
/model/v1/voices
listTenantMediaVoices
Discover and list tenant-owned provider voices
Hosted access requires an active speech grant and qualified platform credentials. Hosted ElevenLabs discovery exposes default premade voices. Hosted Dictator discovery includes only presets and the tenant's retained extracted voices. Hosted cursors bind the grant revision and credential version. Metadata reads do not create billable attempts.
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
provider | query | Yes | string | Canonical provider identifier. |
cursor | query | No | string | |
search | query | No | string | |
page_size | query | No | integer | |
sort | query | No | string | |
sort_direction | query | No | string | |
voice_type | query | No | string | Hosted ElevenLabs access accepts only default. Other values return 400. |
category | query | No | string | Hosted ElevenLabs access accepts only premade. Other values return 400. |
include_total_count | query | No | boolean |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | none | Tenant-owned voices discovered from the selected provider. |
400 | application/json | none | The voice request failed with a stable caller-safe code. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
500 | application/json | none | The voice request failed with a stable caller-safe code. |
502 | application/json | none | The voice request failed with a stable caller-safe code. |
/model/v1/voices/{voice_id}
getTenantMediaVoice
Read one tenant-owned voice
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
voice_id | path | Yes | string | Opaque tenant voice identifier. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | none | One tenant-owned voice without native provider identifiers. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
404 | application/json | none | The voice request failed with a stable caller-safe code. |
500 | application/json | none | The voice request failed with a stable caller-safe code. |
/model/v1/voices/{voice_id}/previews/{preview}
getTenantMediaVoicePreview
Read one account-bound voice preview
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
voice_id | path | Yes | string | Opaque tenant voice identifier. |
preview | path | Yes | integer |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | audio/mpeg, audio/wav | Cache-Control | Audio preview from the current provider connection. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
404 | application/json | none | The voice request failed with a stable caller-safe code. |
500 | application/json | none | The voice request failed with a stable caller-safe code. |
502 | application/json | none | The voice request failed with a stable caller-safe code. |
/v1/audio/transcriptions
createTranscription
createTranscription
Authenticate with a tenant bearer key. Select one exact provider/model route. Reject unsupported fields before provider dispatch. Hosted requests require Idempotency-Key. Identical audio and format use the same request identity across both transcription interfaces.
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Idempotency-Key | header | No | string | Required for hosted text and dictation. The key identifies one tenant request across native and client protocols. An identical request returns its saved result or active receipt. Changed intent returns 409. Expired hosted results return 410. A hosted replay never starts another execution. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
model | Yes | string | |
file | Yes | string | |
response_format | No | object |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Completed result. |
202 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | The durable request has not reached a terminal state. Reconcile the same key again. |
400 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
401 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control | Request failure. |
402 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
403 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
405 | application/json | Allow | The HTTP method is unsupported. |
409 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
410 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
413 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
415 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
429 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds, Retry-After | Request failure. |
499 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
502 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
503 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
504 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
/v1/chat/completions
createChatCompletion
createChatCompletion
Authenticate with a tenant bearer key. Select one exact provider/model route. Reject unsupported fields before provider dispatch.
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Idempotency-Key | header | No | string | Required for hosted text and dictation. The key identifies one tenant request across native and client protocols. An identical request returns its saved result or active receipt. Changed intent returns 409. Expired hosted results return 410. A hosted replay never starts another execution. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
model | Yes | string | |
messages | Yes | array<OpenAIChatMessage> | |
max_tokens | No | integer | |
max_completion_tokens | No | integer | |
reasoning_effort | No | string | |
tools | No | array<OpenAIChatTool> | |
tool_choice | No | object | |
parallel_tool_calls | No | boolean | |
stream | No | boolean | |
stream_options | No | object | |
store | No | object | |
response_format | No | object |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json, text/event-stream | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Completed result. |
202 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | The durable request has not reached a terminal state. Reconcile the same key again. |
400 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
401 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control | Request failure. |
402 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
403 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
405 | application/json | Allow | The HTTP method is unsupported. |
409 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
410 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
413 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
415 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
429 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds, Retry-After | Request failure. |
499 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
502 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
503 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
504 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
/v1/models
listClientModels
listClientModels
Return only catalog routes available to the authenticated tenant. The created value records catalog entry creation from repository history.
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
None.
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control | Completed result. |
400 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control | Request failure. |
401 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control | Request failure. |
405 | application/json | Allow | The HTTP method is unsupported. |
/v1/responses
createResponse
createResponse
Authenticate with a tenant bearer key. Select one exact provider/model route. Reject unsupported fields before provider dispatch.
Authentication: TenantBearerKey (Authorization: Bearer <tenant-client-key>)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Idempotency-Key | header | No | string | Required for hosted text and dictation. The key identifies one tenant request across native and client protocols. An identical request returns its saved result or active receipt. Changed intent returns 409. Expired hosted results return 410. A hosted replay never starts another execution. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
model | Yes | string | |
input | Yes | object | |
instructions | No | string | |
max_output_tokens | No | integer | |
reasoning | No | object | |
tools | No | array<OpenAIResponsesTool> | |
tool_choice | No | object | |
parallel_tool_calls | No | boolean | |
stream | No | boolean | |
store | No | object | |
include | No | array<object> | |
prompt_cache_key | No | null | |
text | No | object |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json, text/event-stream | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Completed result. |
202 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | The durable request has not reached a terminal state. Reconcile the same key again. |
400 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
401 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control | Request failure. |
402 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
403 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
405 | application/json | Allow | The HTTP method is unsupported. |
409 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
410 | application/json | none | Hosted authority is denied, request intent conflicts, the outcome is unknown, or the saved result expired. |
413 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
415 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
429 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds, Retry-After | Request failure. |
499 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
502 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
503 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
504 | application/json | X-LLM-Proxy-Request-ID, X-Request-ID, Cache-Control, X-LLM-Proxy-Request-Timeout-Seconds | Request failure. |
/v2
postV2Messages
Generate text from canonical messages
The current messages-only operation. `messages` is required. User messages may include ordered inline or tenant-asset-backed image and audio attachments. `model`, `web_search`, `max_tokens`, `reasoning_effort`, and `structured_output` are optional. A structured request requires one Idempotency-Key and a supported provider protocol. The proxy compiles the schema and validates the selected provider subset before dispatch. It saves its provider result for reconciliation through `GET /v2/requests`. Omitting `reasoning_effort` selects the tenant or route default. A supplied value must be non-blank and supported by the resolved route. The selected provider offering owns media admission and transport limits. Unsupported media or route capabilities return HTTP 400 before an upstream call. Each Gemini Interactions route returns HTTP 400 when any message has the assistant role. The service rejects an encoded request body above 8 MiB before JSON decoding. A smaller catalog-derived body limit applies when configured. Current Moonshot Kimi image routes preserve attachment order and exact bytes through Chat Completions Data URL blocks.
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
provider | query | No | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. Omission uses the tenant default. |
format | query | No | string | Preferred response media type. Unknown values select text/plain. |
Accept | header | No | string | Response media preference used when format is omitted. |
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Idempotency-Key | header | No | string | Required for hosted text and structured output. A hosted key identifies one tenant request across native and client protocols. An identical request returns its saved result or active receipt. Changed intent returns 409. Expired hosted results return 410. A hosted replay never starts another execution. For account-owned credentials, the key requires structured_output. A known failed request with account-owned credentials permits an explicit new attempt. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
tools | No | array<ClientFunction> | |
tool_choice | No | object | |
parallel_tool_calls | No | boolean | |
messages | Yes | array<V2ChatMessage> | Each message must have an allowed role and non-blank content. The request must include at least one user message. All messages must omit order, or all must have unique non-negative order values. Only user messages can have attachments. Message and attachment order are preserved. Each Gemini Interactions route rejects assistant history. |
model | No | string | Omission selects the resolved provider default. |
web_search | No | boolean | The resolved route must declare web-search capability when true. |
max_tokens | No | integer | Initial output budget. A transport that declares continuation actions reuses it for missing-suffix attempts. |
reasoning_effort | No | string | Omission selects the tenant or route default. An explicit value must be non-blank and supported by the resolved provider/model route. Kimi K3 accepts low, high, or max. |
structured_output | No | object |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | text/plain, application/json, application/xml, text/csv | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-Tokens, X-LLM-Proxy-Response-Tokens, X-LLM-Proxy-Total-Tokens, X-LLM-Proxy-Structured-Request-State | Final text, caller-schema JSON, or caller function calls. Structured output includes durable request state. Function calls use NativeToolResult. |
202 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Structured-Request-State | The durable request is active. Reconcile the same key again. |
400 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The canonical message input or referenced asset is invalid. |
402 | application/json | none | The available funds cannot cover the accepted maximum cost. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
404 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
409 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The provider is not configured, or the key identifies a different intent or an uncertain provider outcome. |
410 | application/json | none | A referenced asset or saved hosted result expired. |
413 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The compatibility JSON request limit, dictation audio limit, tenant asset limit, or selected provider media limit was exceeded. |
429 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider returned HTTP 429. The proxy preserves 429 at its public boundary and returns only sanitized provider metadata; it never exposes the raw provider body or message. |
499 | none | none | The caller canceled or closed the request. |
500 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset store or structured request store failed. |
502 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The provider failed or returned an unusable response. A retained request failure uses the durable error representation. The proxy continues output-budget stops only when the execution contract permits another attempt. Errors exclude partial text, token-count headers, and raw provider errors. The journal can retain available usage after failure. |
503 | application/json, text/plain | X-LLM-Proxy-Request-Timeout-Seconds | The request queue is full or financial admission is unavailable. |
504 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The proxy request budget or upstream operation timed out. |
/v2/identity
getTenantIdentity
Read the authenticated tenant identity
Returns the server-resolved tenant identifier for the supplied tenant client key. This operation never dispatches provider work. A successful response sets Cache-Control to no-store.
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Server-resolved identity for the authenticated tenant. |
400 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The request is malformed, names an invalid route/capability, or supplies an invalid timeout. Text validation failures use the canonical plain-text error. Timeout-header validation uses the canonical JSON error. |
403 | text/plain, application/json | none | The tenant client key is absent or unknown, or hosted admission is denied. |
499 | none | none | The caller canceled or closed the request. |
/v2/requests
getV2StructuredRequest
Reconcile a durable text request
Returns the terminal JSON result, a safe in-progress receipt, or a safe terminal failure for the authenticated tenant and exact Idempotency-Key. This operation never dispatches provider work. Every response sets Cache-Control to no-store.
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
Idempotency-Key | header | Yes | string | Exact key of the durable structured-output request to reconcile. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | A saved hosted completion contains text, optional tool_calls, and optional usage. An account-owned structured request returns the exact JSON that passed its caller schema. |
202 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | The durable request has not reached a terminal state. Reconcile the same key again. |
400 | application/json | Cache-Control | The Idempotency-Key is missing or invalid. |
404 | application/json | Cache-Control | No durable request exists for the authenticated tenant and key. |
409 | application/json | Cache-Control | The key names a different request intent, or provider dispatch completed with an outcome that cannot be proven. |
410 | application/json | Cache-Control | The saved hosted result expired. The journal keeps the request identity and prevents another execution. |
429 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | The durable request reached a safe terminal provider failure. |
500 | application/json | Cache-Control | The durable request record cannot be read or updated. |
502 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | The durable request reached a safe terminal provider failure. |
503 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | The durable request reached a safe terminal provider failure. |
504 | application/json | Cache-Control, X-LLM-Proxy-Structured-Request-State | The durable request reached a safe terminal provider failure. |