> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a chat completion > OpenAI-compatible chat completions. Routes the request through the gateway's provider layer (OpenAI, Azure OpenAI, Anthropic, Vertex, Bedrock, OpenAI-compatible) based on the resolved model spec. **Streaming.** When `stream: true`, the response is a `text/event-stream` of OpenAI-compatible delta chunks (`ChatCompletionChunk`) terminated by a literal `data: [DONE]` payload. Provider-native stream shapes (Anthropic, Bedrock, Vertex) are normalised to OpenAI deltas before being forwarded. Provider errors mid-stream are emitted as a synthetic chunk with a `content` message followed by `[DONE]`. When `stream: false` (default), the response is a single JSON `ChatCompletionResponse`. The non-streaming response is enriched with `usage.cost`, `usage.duration_ms`, and `usage.carbon` (Prisme.ai extensions over the standard OpenAI shape). **Prisme.ai extensions** in the request body: - `task_id` - opaque correlation identifier for A2A flows. - `analytics_context` - caller-supplied context (`orgSlug`, `agent_id`, `user_id`, `context_id`, `agent_allowed_models`, `call_type`, `message_turn`) used to enrich `analytics.llm.completion` events. **Rate limiting.** 100 requests per 60 seconds per consumer (`auth.user_id` or `session.id`). **Governance.** Calls may be rejected with `403 MODEL_NOT_ALLOWED` or `429` quota errors based on the caller's organization governance (resolved via `ai-governance-v2`). ## OpenAPI ````yaml /api-reference/llm-gateway/swagger.yml post /v1/chat/completions openapi: 3.0.3 info: version: 1.0.0 title: LLM Gateway API description: | Public REST API for the Prisme.ai LLM Gateway - OpenAI-compatible chat completions and embeddings, plus a managed model catalogue with governance overrides per organization. The gateway abstracts multi-provider LLM access (OpenAI, Azure OpenAI, Anthropic, Google Vertex, AWS Bedrock, OpenAI-compatible providers) behind an OpenAI-compatible request/response shape. It enforces per-tenant governance (allowed models, default models, quotas) and emits analytics events (`analytics.llm.completion`) usable for cost and carbon reporting. This spec documents only the public REST surface (endpoints exposed via Prisme.ai workspace webhooks). Internal helpers (private automations prefixed with `_`) and load-test mocks are not part of the public contract. contact: name: Prisme.ai url: https://prisme.ai servers: - url: https://{host}/v2/workspaces/slug:llm-gateway/webhooks description: Prisme.ai workspace webhooks variables: host: default: api.studio.prisme.ai description: API host (override for self-hosted or sandbox) security: - BearerAuth: [] - OrgApiKeyAuth: [] tags: - name: Completions description: OpenAI-compatible chat completions (with optional SSE streaming). - name: Embeddings description: OpenAI-compatible text embeddings. - name: Models description: Model catalogue (CRUD + bulk replace + governance-aware listing). - name: Defaults description: >- Resolved default models for completions / embeddings / image generation / file parsing. - name: Test description: Smoke-test reachability of a model through the gateway. paths: /v1/chat/completions: post: tags: - Completions summary: Create a chat completion description: > OpenAI-compatible chat completions. Routes the request through the gateway's provider layer (OpenAI, Azure OpenAI, Anthropic, Vertex, Bedrock, OpenAI-compatible) based on the resolved model spec. **Streaming.** When `stream: true`, the response is a `text/event-stream` of OpenAI-compatible delta chunks (`ChatCompletionChunk`) terminated by a literal `data: [DONE]` payload. Provider-native stream shapes (Anthropic, Bedrock, Vertex) are normalised to OpenAI deltas before being forwarded. Provider errors mid-stream are emitted as a synthetic chunk with a `content` message followed by `[DONE]`. When `stream: false` (default), the response is a single JSON `ChatCompletionResponse`. The non-streaming response is enriched with `usage.cost`, `usage.duration_ms`, and `usage.carbon` (Prisme.ai extensions over the standard OpenAI shape). **Prisme.ai extensions** in the request body: - `task_id` - opaque correlation identifier for A2A flows. - `analytics_context` - caller-supplied context (`orgSlug`, `agent_id`, `user_id`, `context_id`, `agent_allowed_models`, `call_type`, `message_turn`) used to enrich `analytics.llm.completion` events. **Rate limiting.** 100 requests per 60 seconds per consumer (`auth.user_id` or `session.id`). **Governance.** Calls may be rejected with `403 MODEL_NOT_ALLOWED` or `429` quota errors based on the caller's organization governance (resolved via `ai-governance-v2`). operationId: createChatCompletion requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' responses: '200': description: | Successful completion. Content type depends on `request.stream`: - `application/json`: non-streaming `ChatCompletionResponse`. - `text/event-stream`: SSE stream of `ChatCompletionChunk` payloads terminated by `data: [DONE]`. content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' text/event-stream: schema: description: | Server-Sent Events stream. Each `data:` line carries a JSON `ChatCompletionChunk` (delta), and the final `data:` line is the literal string `[DONE]`. The schema below describes the per-chunk JSON payload. allOf: - $ref: '#/components/schemas/ChatCompletionChunk' '400': description: Validation error (validateArguments rejected the body shape). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid authentication. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: | Model not allowed for this caller (governance overlay). `error.code` is typically `MODEL_NOT_ALLOWED`. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: | Rate limit exceeded (`code: RATE_LIMITED`, 100 req / 60 s per consumer) or governance quota exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ChatCompletionRequest: type: object required: - model - messages description: | OpenAI-compatible chat completion request. Only the fields actually accepted by the gateway are documented here. properties: model: type: string maxLength: 256 description: | Model id from the catalogue (e.g. `gpt-4o`, `eu.anthropic.claude-sonnet-4-20250514-v1:0`, `vertex-gemini-2.5-flash`). messages: type: array description: Conversation history (system + user/assistant/tool turns). items: $ref: '#/components/schemas/ChatMessage' temperature: description: Sampling temperature (provider-dependent range, typically 0–2). max_tokens: description: Max tokens to generate. top_p: description: Nucleus sampling parameter. frequency_penalty: description: OpenAI-style frequency penalty. presence_penalty: description: OpenAI-style presence penalty. stop: description: One or more stop sequences (string or array of strings). stream: type: boolean description: | When `true`, the response is a `text/event-stream` of `ChatCompletionChunk` deltas terminating with `data: [DONE]`. tools: type: array description: | Tool/function definitions made available to the model. Forwarded to providers that support tool calling. items: type: object additionalProperties: true tool_choice: description: | Tool selection hint: `"auto"`, `"none"`, `"required"`, or `{ type: "function", function: { name } }`. response_format: description: | OpenAI-style structured output hint (e.g. `{ "type": "json_object" }`). type: object additionalProperties: true seed: description: Provider seed for reproducible sampling (where supported). task_id: type: string maxLength: 128 description: | **Prisme.ai extension.** Opaque correlation id propagated to A2A (agent-to-agent) flows. analytics_context: type: object description: | **Prisme.ai extension.** Caller-supplied analytics context merged into the `analytics.llm.completion` event. additionalProperties: true properties: orgSlug: type: string agent_id: type: string user_id: type: string context_id: type: string agent_allowed_models: type: array items: type: string call_type: type: string message_turn: type: number ChatCompletionResponse: type: object description: | Non-streaming chat completion response. Mirrors OpenAI's shape with Prisme.ai extensions on `usage` (`cost`, `duration_ms`, `carbon`). required: - id - object - created - model - choices properties: id: type: string description: Generated id (`chatcmpl-`). object: type: string enum: - chat.completion created: type: integer description: Unix timestamp (seconds). model: type: string description: Resolved model id used to serve the request. choices: type: array items: type: object required: - index - message properties: index: type: integer message: $ref: '#/components/schemas/ChatMessage' finish_reason: type: string description: | `stop`, `length`, `tool_calls`, `content_filter`, or another provider-specific value. usage: type: object description: Token, cost, and carbon accounting. properties: prompt_tokens: type: integer completion_tokens: type: integer total_tokens: type: integer cost: type: number format: double description: | **Prisme.ai extension.** Estimated USD cost computed from `pricing.input_per_1m_tokens` / `pricing.output_per_1m_tokens` on the model document. duration_ms: type: integer description: '**Prisme.ai extension.** Wall-clock duration of the call.' carbon: type: object description: | **Prisme.ai extension.** Carbon-footprint estimate produced by `_compute-carbon-footprint`. additionalProperties: true ChatCompletionChunk: type: object description: | Single chunk in a streaming chat completion. Forwarded as the JSON payload of an SSE `data:` line. The final SSE payload of a stream is the literal string `[DONE]` (not JSON). properties: id: type: string object: type: string created: type: integer model: type: string choices: type: array items: type: object required: - index properties: index: type: integer delta: type: object description: Incremental message delta. properties: role: type: string content: type: string tool_calls: type: array items: type: object additionalProperties: true finish_reason: type: string usage: type: object additionalProperties: true Error: type: object required: - error description: | Standard error envelope. `error` carries either a stable PascalCase identifier or a free-text label (legacy endpoints) - `code` is the canonical machine-readable identifier going forward. properties: error: type: string description: Stable PascalCase identifier or short error label. message: type: string description: Human-readable error message. code: type: string description: | Machine-readable error code. Observed values include `RATE_LIMITED`, `MODEL_NOT_ALLOWED`, `MODEL_NOT_FOUND`, `MODEL_EXISTS`, `MISSING_MODEL_ID`, `MISSING_TYPE`, `INVALID_BODY`, `INVALID_ITEMS`, `INVALID_DIMENSIONS`, `PAYLOAD_TOO_LARGE`, `METHOD_NOT_ALLOWED`, `PROVIDER_ERROR`, `PROVIDER_NO_RESPONSE`. details: description: Optional structured context (e.g. list of invalid items). additionalProperties: true status: type: integer description: HTTP status mirror, when present. retryAfter: type: integer description: Seconds to wait before retrying (rate-limit responses). provider: type: string description: Upstream provider name (provider-error responses). model: type: string description: Model id involved in the error (provider-error responses). provider_error_type: type: string description: Upstream provider's own error class name. ChatMessage: type: object required: - role description: A single message in a chat completion request or response. properties: role: type: string enum: - system - user - assistant - tool description: Author role. content: description: | Message content. Either a plain string, or an array of typed parts (e.g. text + image) for multimodal inputs. oneOf: - type: string - type: array items: type: object additionalProperties: true name: type: string description: Optional author name (e.g. function name for tool messages). tool_call_id: type: string description: 'For `role: tool`, the id of the tool call this message responds to.' tool_calls: type: array description: Tool calls emitted by an assistant message. items: $ref: '#/components/schemas/ToolCall' ToolCall: type: object required: - id - type - function properties: id: type: string description: Provider-issued tool call identifier. type: type: string enum: - function description: Tool kind. Currently always `function`. function: type: object required: - name properties: name: type: string description: Function name. arguments: type: string description: | JSON-encoded arguments. Sent as a string (matches OpenAI's wire format). securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | User-bound credential carrying an identity: either a session JWT or a user access token (`at:*`) generated from the user settings UI. Send as `Authorization: Bearer `. Org API keys (`iak_*`) are **not** accepted here - they carry no user identity. Use the `x-prismeai-api-key` header instead (see `OrgApiKeyAuth`). OrgApiKeyAuth: type: apiKey in: header name: x-prismeai-api-key description: | Organization API key (`iak_{orgSlug}_{uuid}`). Unlike `Authorization: Bearer`, this credential is **not** tied to a user identity - it is bound to the org and its effective access is defined by the scopes / permission rules attached to it (it can be restricted to a single project, or kept broader). Send as `x-prismeai-api-key: iak_...`. ````