---
title: "Legacy text completion"
method: POST
path: "/completions"
---

# Legacy text completion

`POST /completions`

## Request

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

Requires the COMPLETIONS scope. Streaming defaults to off; explicit stream: true enables progressive OpenAI-compatible 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. Set stream_options.include_usage: true for a final usage chunk after the last delta and before [DONE]; otherwise that chunk is omitted. 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.

## 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: Catalog model id (vendor/model).
  - `prompt` string, required
  - `max_tokens` integer
  - `stream` boolean: Defaults to false. Set true explicitly for progressive OpenAI-compatible SSE with x-openmayhem-stream-mode: live.

## Response `200`

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

## 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)