---
title: "OpenAI-compatible text completions (T41 wired)"
method: POST
path: "/v1/completions"
tags: ["openai-compat"]
---

# OpenAI-compatible text completions (T41 wired)

`POST /v1/completions`

Accepts the public OpenAI `POST /v1/completions` request shape
and dispatches to the deployed function the gateway operator
has aliased to the requested `model` (via
`TENSOR_WASM_API_OPENAI_MODEL_MAP`). Returns the standard OpenAI
`text_completion` envelope on success, or
`404 model_not_found` when the model alias is unknown.

When `stream: true`, returns `text/event-stream` with one
`data: { ... }` SSE frame per emitted chunk and a terminal
`data: [DONE]\n\n` line.

The `X-TensorWasm-Tenant` header is not honoured on this
route, because OpenAI SDKs never send it. Tenant resolution
comes from the bearer token's scope (see
`docs/OPENAI-COMPAT.md`).

## Request body

- CompletionsRequest — Body of `POST /v1/completions`. Mirrors the public OpenAI completions REST contract; every field is optional at the wire layer so SDKs that omit knobs still parse cleanly.
  - `model` string — Model identifier. The gateway operator pre-aliases this to a deployed function UUID via `TENSOR_WASM_API_OPENAI_MODEL_MAP`. Unknown ids surface as `404 model_not_found`.
  - `prompt` unknown
  - `max_tokens` integer
  - `temperature` number
  - `stream` boolean — When true the response is `text/event-stream` with one `data: { ... }` SSE frame per emitted chunk and a terminal `data: [DONE]\n\n` line.
  - `echo` boolean
  - `n` integer
  - `user` string

## Response `200`

Completion result (or SSE stream when `stream:true`).

- CompletionsResponse — Non-streaming `/v1/completions` response. The `object` field carries the literal `"text_completion"`.
  - `id` string, required
  - `object` 'text_completion', required
  - `created` integer, required — Unix seconds at which the response was generated.
  - `model` string, required — Echoes the request's `model` field.
  - `choices` CompletionsChoice[], required
    - `text` string, required
    - `index` integer, required
    - `finish_reason` 'stop' | 'length' | 'content_filter' | 'null', nullable
    - `logprobs` unknown
  - `usage` CompletionsUsage, required — Token-count block. v0.4 ships zeros across the board because the gateway does not yet wire a tokenizer; v0.5 lands a real counter (see `docs/OPENAI-COMPAT.md`).
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required

## Other responses

- `400` — Malformed request body (OpenAI envelope).
- `401` — Missing or unrecognised bearer token
- `403` — Bearer token is not scoped to the requested tenant
- `404` — The requested `model` is not configured in the gateway's `TENSOR_WASM_API_OPENAI_MODEL_MAP`. Carries OpenAI envelope `code: "model_not_found"`.
- `413` — Request body exceeded the 64 MiB cap enforced by axum's `DefaultBodyLimit::max`. Often rendered as a bare 413 with no body when the limit is hit during streaming.
- `429` — Per-token QPS + burst exceeded. The `Retry-After` header carries the wait in integer seconds (RFC 9110 §10.2.3).

---

[API](https://skmtc.dev/craton-co/apis/tensorwasm-http-api.md) · [All operations](https://skmtc.dev/craton-co/apis/tensorwasm-http-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/craton-co/tensorwasm-http-api/revisions/d363e13d8640/schema)