Chat Completions | JoyToken

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].

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.

Request

This endpoint expects an object.

modelenumRequired

Must be auto. Concrete model IDs are not accepted.

messageslist of objectsRequired

OpenAI-compatible chat messages.

tierenumOptional

JoyToken model tier.

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