Documentation by ClonePartner

Start typing to search.

API Reference

Stream an AI chat response (agent or task-editor mode)

View Markdown
POST /api/ai/chat

Stream an AI chat response (agent or task-editor mode)

Operation IDpostAiChat

Authentication

  • BearerAuth·http bearer·API key token (envoy_<hex>). Create keys from Settings → API Keys — see Using the API.

Request body

This request body is required.

Content typeapplication/json

requestobject
11 properties
conversation_idinteger
messagestring
messagesarray<object>
Array items
itemobject
2 properties
rolestringrequired

Request body roles are user/assistant only. Persisted conversation history may also contain role=summary rows from auto-compaction.

Allowed values
user, assistant
contentstring | array<object>required
One of
One of 1string
One of 2array<object>
Array items
itemobject
route_contextstring
referencesarray<object>

User-staged entity references (composer @-mentions / Add to chat). Invalid entries are ignored.

Maximum items
10
Array items
itemobject
5 properties
typestringrequired
Allowed values
task, job, job_template, connector, trigger, dashboard, run, job_run, reference, account
idstringrequired
labelstring
connector_idinteger

Owning connector (account references only)

integrationstring

Integration slug (account references only)

modestring
Allowed values
agent, task-editor
editor_kindstring

Which YAML editor is active when current_yaml is sent

Allowed values
task, dashboard
connector_idsarray<integer>
Array items
iteminteger
current_yamlstring
modelstring

Per-request model override. Must be one of the ids from GET /api/ai/status models; requests with an unknown model are rejected with 400.

approvalsarray<object>
Array items
itemobject
4 properties
tool_use_idstring
decisionstring
Allowed values
approved, rejected
methodstring
pathstring

Success response body

200SSE stream events: text, thinking, thinking_signature, tool_call_start (name + tool_use_id, emitted when the model opens a tool_use block and its args are still being generated — lets the client show an in-progress card immediately), tool_call, tool_result, pending_approval, navigate, resource, title, conversation, compaction (status start|done|skipped; done includes message_id + summary), usage (context_tokens + context_window after each model response — drives the UI context meter), done, error. The internal turns event is not forwarded to the client.

SSE stream events: text, thinking, thinking_signature, tool_call_start (name + tool_use_id, emitted when the model opens a tool_use block and its args are still being generated — lets the client show an in-progress card immediately), tool_call, tool_result, pending_approval, navigate, resource, title, conversation, compaction (status start|done|skipped; done includes message_id + summary), usage (context_tokens + context_window after each model response — drives the UI context meter), done, error. The internal turns event is not forwarded to the client.

Content typetext/event-stream

responsestring

Error responses

400Validation error

Validation error

No response content schema is documented.

501AI not configured

AI not configured

No response content schema is documented.