---
title: "Chat completion"
method: POST
path: "/chat/completions"
---

# Chat completion

`POST /chat/completions`

## Request

- Base URL: `https://api.openmayhem.ai/v1`
- URL: `https://api.openmayhem.ai/v1/chat/completions`
- Auth: HTTP bearer

OpenAI-compatible. Requires the CHAT scope. Streaming defaults to off; explicit stream: true enables progressive server-sent events (SSE). The API forwards emitted deltas without buffering the entire output; a provider backend may buffer its own output rather than emit token by token. Native Core durable jobs preserve billing and reconciliation. Disconnecting does not guarantee cancellation or a refund; charges settle exactly from the signed receipt for work performed. Budget with max_tokens. stream_recovery_unavailable means the gateway does not yet support stream recovery: the request fails before inference starts; use stream: false instead. Send an Idempotency-Key header to make retries safe.

## Headers

- `X-Mayhem-Min-Att-Tier` union
  - integer
  - 'T1' | 'T2' | 'T3' | 'T4'
- `X-Mayhem-Min-Ctx` integer
- `X-Mayhem-Quant` string
- `X-Mayhem-Prefer-Providers` string
- `X-Mayhem-Hedge` 0 | 1
- `X-Mayhem-Min-Tok-S` number
- `X-Mayhem-Max-Wait-Ms` integer
- `X-OpenMayhem-Max-Cost-Usd` string: Non-negative decimal USD string with at most 6 decimal places, parsed with exact fixed-point arithmetic.
- `X-OpenMayhem-Max-Input-Price-Per-Million-Usd` string: Non-negative decimal USD string with at most 6 decimal places, parsed with exact fixed-point arithmetic.
- `X-OpenMayhem-Max-Output-Price-Per-Million-Usd` string: Non-negative decimal USD string with at most 6 decimal places, parsed with exact fixed-point arithmetic.
- `X-OpenMayhem-Max-Representative-Request-Price-Usd` string: Non-negative decimal USD string with at most 6 decimal places, parsed with exact fixed-point arithmetic.
- `X-OpenMayhem-Estimate` string

## Request body

- object
  - `model` string, required
  - `messages` object[], required
    - `role` 'system' | 'user' | 'assistant' | 'tool', required
    - `content` unknown, required
  - `max_tokens` integer: Budget generously (2000+) for reasoning models; thinking consumes tokens.
  - `stream` boolean: Defaults to false. Set true explicitly for progressive OpenAI-compatible SSE with x-openmayhem-stream-mode: live.
  - `stream_options` object: For streaming Chat Completions, set include_usage: true to receive a final usage chunk after the last delta and before [DONE]. Without this option, the usage chunk is omitted.
    - `include_usage` boolean

## Response `200`

With streaming off, an OpenAI-shaped completion plus usage.cost (USD string) and openmayhem.request_id / openmayhem.receipt. With stream: true, text/event-stream with x-openmayhem-stream-mode: live; Chat Completions chunks end with [DONE], preceded by an optional final usage chunk when stream_options.include_usage is true.

- ChatCompletion: OpenAI chat completion plus OpenMayhem billing fields.
  - `choices` object[]
  - `usage` object
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
    - `cost` string: Exact settled cost in USD.
  - `openmayhem` object
    - `request_id` string
    - `receipt` object
      - `session_id` string
      - `sequence` integer
      - `final` boolean
      - `verified` boolean

## Other responses

- `400`: Contract violation; nothing charged.
- `401`: Missing or invalid API key.
- `402`: Insufficient credit.
- `403`: Scope, allowlist, spend limit or account restriction.
- `429`: Rate limit; wait Retry-After seconds.
- `503`: No provider capacity; retry with backoff.

---

[API](https://skmtc.dev/openmayhem/apis/openmayhem-api.md) · [All operations](https://skmtc.dev/openmayhem/apis/openmayhem-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openmayhem/apis/openmayhem-api/revisions/0ea33ad12f21?raw)