---
title: "Chat Completions"
method: POST
path: "/v1/chat/completions"
tags: ["chat"]
---

# Chat Completions

`POST /v1/chat/completions`

OpenAI-compatible chat completions endpoint.

Supports both streaming and non-streaming responses.
Handles reasoning content from otari providers.

Authentication modes:
- Master key + user field: Use specified user (must exist)
- API key + user field: Use specified user (must exist)
- API key without user field: Use the shared "default" user

## Request body

- ChatCompletionRequest — OpenAI-compatible chat completion request. The completion-param fields are derived from any-llm's ``CompletionParams`` (see ``_schema_derive``) so the schema cannot silently drop a param any-llm forwards. Fields below either tighten a derived field (``messages``, ``response_format``), declare an OpenAI wire param ``CompletionParams`` does not model (``service_tier``, forwarded as an any-llm ``**kwargs`` param), add gateway-internal behavior (``mcp_servers``, ``mcp_server_ids``, ``guardrails``, ``tools_header``, ``max_tool_iterations``) that is stripped before the request is forwarded upstream, or restate a derived field unchanged to document it (``max_completion_tokens``), which is only worth doing where the wire contract is not guessable from the field itself.
  - `frequency_penalty` number, nullable
  - `guardrails` GuardrailConfig[], nullable
    - `mode` 'block' | 'monitor'
    - `on` string[]
    - `on_unavailable` 'block' | 'monitor'
    - `profile` string, required
    - `url` string, nullable
    - `validate_kwargs` object
  - `logit_bias` object, nullable
  - `logprobs` boolean, nullable
  - `max_completion_tokens` integer, nullable — Upper bound on generated tokens. OpenAI's current name for the cap `max_tokens` used to carry; either field is accepted, and this one wins when a request sends both.
  - `max_tokens` integer, nullable
  - `max_tool_iterations` integer, nullable
  - `mcp_server_ids` string[], nullable
  - `mcp_servers` McpServerConfig[], nullable
    - `allowed_tools` string[], nullable
    - `authorization_token` string, nullable
    - `name` string, required
    - `purpose_hint` string, nullable
    - `url` string, required
  - `messages` object[], required
  - `model` string, required
  - `n` integer, nullable
  - `parallel_tool_calls` boolean, nullable
  - `presence_penalty` number, nullable
  - `prompt_cache_key` string, nullable
  - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto', nullable
  - `response_format` object, nullable
  - `seed` integer, nullable
  - `service_tier` string, nullable
  - `session_label` string, nullable — Optional caller-supplied label for cost attribution (per run, experiment, or conversation). In hybrid mode it is forwarded onto the platform usage report so spend can be sliced by session without standing up OpenTelemetry. Stripped before the request is forwarded upstream to the provider. Has no effect in standalone mode, where there is no platform to report it to.
  - `stop` union
    - string
    - string[]
  - `stream` boolean
  - `stream_options` object, nullable
  - `temperature` number, nullable
  - `tool_choice` union
    - string
    - object
  - `tools` union[], nullable
    - union
      - object
      - unknown
  - `tools_header` string, nullable — Optional override for the lead-in that the gateway prepends before the per-tool hint block in the system message. Useful for expressing global tool-selection policy (e.g. 'prefer MCP tools over code_execution'). Falls back to OTARI_TOOLS_HEADER env, then to the built-in default.
  - `top_logprobs` integer, nullable
  - `top_p` number, nullable
  - `user` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-25** `7f7b2d236b61` — 1 info
  - added the new optional request property `prompt_cache_key`
- **2026-08-12** `dc832629bd32` — 1 info
  - added the new optional request property `service_tier`
- **2026-08-05** `00866b0c5407` — 1 info
  - added the new optional request property `guardrails/anyOf[subschema #1]/items/on_unavailable`
- **2026-07-20** `d9a87177ce4a` — 1 info
  - the endpoint scheme security `XApiKeyAuth` was added to the API
- **2026-07-14** `0ad4e5f1cc3e` — 1 info
  - the endpoint scheme security `ApiKeyAuth` was added to the API

[Full history](https://skmtc.dev/mozilla-ai/apis/otari/changes/v1/chat/completions/post.md)

---

[API](https://skmtc.dev/mozilla-ai/apis/otari.md) · [All operations](https://skmtc.dev/mozilla-ai/apis/otari/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mozilla-ai/otari/revisions/6240738fd489/schema)