Conventions

Base format

Chat endpoints consume and return JSON. In streaming mode, the response is sent as text/event-stream.

The model field

The model field is required and must follow one of these formats:

group:<uuid>
custom:<uuid>

Example:

group:123e4567-e89b-12d3-a456-426614174000
custom:123e4567-e89b-12d3-a456-426614174111

group:<uuid> targets can use auto, normal, orch, or synth modes. custom:<uuid> targets always run in normal mode. If a custom target receives metadata.mode with orch or synth, the API returns 400.

Messages

The request expects a messages array.

Accepted roles:

• system
• user
• assistant
• tool

Important rules:

• the array must contain at least one user message
• the last user message is treated as the current prompt
• tool messages are accepted for compatibility but are not sent as chat history
• tool_call_id is optional and can be up to 200 characters

Content formats

The content field of a message can be:

• a string
• null
• an array of content parts with properties such as type and text

Streaming

If stream is true, the API returns SSE events.

The flow generally looks like this:

1. one initial chunk opens the assistant response
2. additional chunks append text in choices[0].delta.content
3. one final chunk closes the response
4. the stream ends with data: [DONE]

metadata

The metadata field is optional. It is especially useful for:

• passing a request_id
• indicating a mode through metadata.mode

Accepted metadata.mode values:

• auto
• normal
• orch
• synth

Unknown request fields are ignored. Supported fields are listed on each endpoint page.

Reasoning effort

Reasoning effort can be sent in three ways:

• reasoning_effort: applies to the brain target
• reasoning.effort: OpenAI-style object form, also applies to the brain target
• reasoning_effort_overrides: object that maps target IDs such as brain or agent:0 to an effort

Accepted values are:

• none
• minimal
• low
• medium
• high
• xhigh
• max

Explicit reasoning_effort_overrides take priority over reasoning_effort and reasoning.effort.

Request IDs

Clients can send x-request-id with letters, digits, ., _, :, or -, up to 128 characters. The API returns the selected request ID in the same header and in error payloads.

metadata.request_id can also provide an application-level request ID. When it is present and non-empty, it is used for the Kitemesh execution metadata.

Useful input limits

• messages: between 1 and 500 items
• temperature: between 0 and 2
• max_tokens: between 1 and 200000
• max_completion_tokens: between 1 and 200000
• denied_tools[].reason: up to 2000 characters
• approved_tool_execution_ids and denied_tools: up to 200 items each on resume requests

If both max_tokens and max_completion_tokens are present, max_completion_tokens is the clearest field to use for output control.