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
Use Authorization: Bearer $JOY_TOKEN_API_KEY.
Headers
Request
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.
OpenAI-compatible chat messages.
Return an OpenAI-compatible SSE stream when true.
Optional end-user identifier used as route session context.
OpenAI-compatible tool definitions.
Response headers
Response
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.
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.
