Skip to navigation

Chat Completions

Creates a model response for a chat conversation. This endpoint accepts OpenAI-compatible chat payloads and adds JoyToken routing, policy, wallet, and usage metadata around the provider call.

When JoyToken routes a request through orchestration (multi-task planning) mode, the gateway first produces a task plan, executes each task with a selected sub-model, and then aggregates a final answer. In this mode: the non-streaming choices[].message.content is a JSON-encoded array of per-task outputs (each with content and title), the top-level plan lists the tasks, and metadata is an array with one entry per task (including the reserved __planner__ and __final__ tasks). When streaming, a leading planning event arrives first (a chunk whose orchestration.phase is planning, carrying the ordered plan) followed by the __planner__ metadata event; then each task’s full content arrives as a chunk that carries an orchestration field (task_id, task_seq, task_status, title), each followed by one standalone metadata event (a single object, not an array) before [DONE].

Authentication

AuthorizationBearer

Use Authorization: Bearer $JOY_TOKEN_API_KEY.

Headers

X-Request-IDstringOptional
Optional request identifier for log, billing, and debugging correlation.

Request

This endpoint expects an object.
modelstringRequired

Use auto to let the gateway pick the model, or pass a concrete modelName from the model catalog to pin that model. Both ways are available to every account. When a model is pinned, tier is ignored, orchestration is not used, and there is no fallback to another model.

messageslist of objectsRequired

OpenAI-compatible chat messages.

tierenumOptional
JoyToken model tier.
Allowed values:
streambooleanOptionalDefaults to false

Return an OpenAI-compatible SSE stream when true.

temperaturedoubleOptional0-2
Sampling temperature forwarded to the selected provider when supported.
top_pdoubleOptional0-1
Nucleus sampling value forwarded to the selected provider when supported.
max_tokensintegerOptional>=1
Maximum output tokens. Also participates in JoyToken billing estimation.
userstringOptional

Optional end-user identifier used as route session context.

toolslist of objectsOptional

OpenAI-compatible tool definitions.

Response headers

X-DAOE-FailoverstringOptional
Present on streaming responses when provider failover occurred.

Response

Successful chat completion response.
idstring
objectstring
choiceslist of objects
createdlongOptional
modelstringOptional
usageobjectOptional
metadatalist of objectsOptional

Array of JoyToken metadata objects. Always an array: a normal single-model response returns one element, while orchestration (multi-task planning) mode returns one element per task.

planlist of objectsOptional

Present only in orchestration mode. The ordered task plan produced by the planner. Each item maps to a task whose output appears as one entry in the JSON-encoded choices[].message.content array.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error