Chat completions

POST https://api.inference.runatlas.com/v1/chat/completions

Authenticated with an inference key (atl_live_).

Request body

modelstringrequired

A catalog model identifier, e.g. atlas-mid-1. Must resolve in GET /v1/models; an unknown identifier returns 404 model_not_found, a retired one 404 model_retired.

messagesarrayrequired

At least one message. Roles: system, developer, user, assistant, tool.

content is a string or an array of content parts. An assistant message may carry tool_calls and refusal; a tool message requires tool_call_id.

streambooleandefault: false

Stream the response as server-sent events. See Streaming.

stream_optionsobject

{"include_usage": boolean}. Atlas forces include_usage on upstream for every stream, so the usage frame is delivered regardless of this setting. Dropped on non-streaming requests.

max_completion_tokensinteger

Positive. Set this. With neither this nor max_tokens, a per-model default output ceiling is reserved against your token-per-minute budget — see Rate limits.

max_tokensinteger

The older name for the same cap. Positive.

temperaturenumber

0 – 2.

top_pnumber

0 – 1.

frequency_penaltynumber

−2 – 2.

presence_penaltynumber

−2 – 2.

stopstring | string[]

Up to 4 sequences.

seedinteger

Carried to the backend. Determinism is a backend property, not an Atlas guarantee.

logit_biasobject

Token id → bias.

logprobsboolean

top_logprobsinteger

0 – 20.

toolsarray

Function tool definitions. Refused with model_does_not_support_tools on a model whose capabilities.tool_calling is false. See Tool calling.

tool_choicestring | object

"auto", "none", "required", or {"type": "function", "function": {"name": "..."}}.

parallel_tool_callsboolean

response_formatobject

{"type": "text"}, {"type": "json_object"}, or {"type": "json_schema", "json_schema": {"name", "schema", "strict"}}.

The schema is validated against atlas-json-schema-subset-v1 before the request is admitted.

ninteger

Must be 1 or omitted. Greater than 1 is refused with 400 unsupported_parameter.

user, safety_identifier, prompt_cache_key, service_tier, store, metadatavarious

Modelled and carried to the backend.

Any top-level field not listed here is accepted and dropped. It does not reach the backend and does not cause an error.

Headers

Authorizationstringrequired

Bearer atl_live_...

x-atlas-diagnostic-capturestring

1, true, yes, or on retains this one request's content for at least 24 hours. See Diagnostic capture.

Response

request_idstring

Additive to the OpenAI shape; also the x-request-id header.

finish_reasonstring

stop, length, tool_calls, content_filter, or function_call.

usage.completion_tokens_details.reasoning_tokensinteger

Counted inside completion_tokens. Never add the two.

Response headers

Header	When
`x-request-id`	Always
`content-type`	`application/json`, or `text/event-stream; charset=utf-8` on a stream
`cache-control`, `connection`, `x-accel-buffering`	On a stream
`retry-after`, `retry-after-ms`, `x-ratelimit-*`	On a `429` only

Errors

Status	Code
400	`unsupported_parameter`	`n` greater than 1.
400	`model_does_not_support_tools`
400	`model_does_not_support_structured_output`
400	`unsupported_json_schema`	Schema outside the subset.
400	`backend_rejected_request`
401	—	Any credential problem.
404	`model_not_found` / `model_retired`
413	`request_too_large`	Above the model's `max_request_bytes`.
429	`rate_limit_exceeded`	Your configured limit. Carries retry headers.
499	`client_disconnected`	You closed the connection. Generated tokens are still metered.
500	`backend_unavailable`, `backend_protocol_error`, `backend_error`, `internal_error`
503	`server_overloaded`	Atlas capacity. No retry headers.
503	`backend_timeout`, `server_shutting_down`

Once a stream has begun, the status is already 200 — a later failure arrives as an in-band error frame with no [DONE]. See Streaming.

Full details in Error codes.