Skip to main content
The Copilot API provides an AI-assisted workflow builder. Create a copilot session linked to a workflow, describe what you want in natural language, and the copilot generates the workflow graph. You can iterate through multiple chat turns to refine the workflow, then save a snapshot to apply the generated graph.

​
Common Patterns

Create a copilot session with a workflow_id, send messages via the chat endpoint (streaming SSE), and save good suggestions with the snapshot endpoint. Each chat message can produce a new version of the workflow graph. The copilot maintains conversation context within a session.

​
POST /api/copilot/sessions

Create a copilot session for a workflow. 
{ "workflow_id": "wf-uuid" }

requests.post(f"{BASE_URL}/api/copilot/sessions", headers=headers, json={"workflow_id": wf_id})

​
GET /api/copilot/sessions

Get session by workflow_id.
​
workflow_id
string
required
Workflow ID
requests.get(f"{BASE_URL}/api/copilot/sessions?workflow_id={wf_id}", headers=headers)

​
DELETE /api/copilot/sessions/

Delete a copilot session.
​
id
string
required
Session ID
requests.delete(f"{BASE_URL}/api/copilot/sessions/{session_id}", headers=headers)

​
GET /api/copilot/sessions//messages

Get copilot conversation history.
​
id
string
required
Session ID
requests.get(f"{BASE_URL}/api/copilot/sessions/{session_id}/messages", headers=headers)

​
POST /api/copilot/sessions//messages//snapshot

Save the copilot’s workflow suggestion as a snapshot.
​
id
string
required
Session ID
​
mid
string
required
Message ID
requests.post(f"{BASE_URL}/api/copilot/sessions/{session_id}/messages/{message_id}/snapshot", headers=headers)

​
POST /api/copilot/sessions//chat

Send a message and stream the copilot response (SSE). The copilot runs a ReAct loop with access to a fixed set of tools for inspecting and modifying the workflow.
​
id
string
required
Session ID
{
  "message": "Add a step that sends Slack notifications when the run finishes",
  "workflow_state": { "nodes": [...], "edges": [...] }
}
Body fieldTypeNotes
messagestring (required)User message
workflow_stateobjectThe current editor state (nodes + edges). The copilot needs this so it can reason against the live in-progress workflow, not just the persisted version. The Studio sends it automatically.

​
SSE event types

The chat stream emits these events (each as data: <json> lines):
EventPayloadWhen
status{ message }Human-readable status string (“Thinking…”, “Modifying workflow…”, etc.) for the UI. Derived from ReAct step + tool name via the platform’s status map.
tool_call{ name, arguments }A copilot tool is about to execute
tool_result{ name, result }A copilot tool finished (truncated to readable size)
content_delta{ delta }A token of the copilot’s text response
complete{ message_id, content, workflow_diff }Final event. workflow_diff is the structured change-set the copilot proposes (added/removed/modified blocks and edges) — pass message_id to /snapshot to apply it.
error{ error }The copilot failed mid-run

​
Copilot tools

The copilot has eight tools, exposed via the ReAct loop:
ToolPurpose
modify_workflowAdd / update / remove blocks and edges in the in-progress workflow. The workflow_diff in the complete event is the cumulative effect of all modify_workflow calls.
get_block_infoLook up the schema for a block type (which config fields, defaults, validation) before constructing it
get_db_schemaRead the project database’s schema (tables, columns, types) so the copilot can build correct SQL for code or general_api blocks
list_project_assetsEnumerate existing agents, KBs, orchestrations, workflows the copilot might want to call
get_asset_detailsFetch one asset’s full config — for agents, the system prompt is truncated to 1000 chars to fit context
execute_public_sqlRun a read-only SQL query against the project DB (public schema only) — useful for exploring data before designing a block
get_workflow_run_logsRead past execution logs from this workflow — useful for “the last run failed at step X, fix it”
manage_project_assetCreate / update / delete a project asset (agent, KB, etc.) on the copilot’s recommendation. Requires user confirmation in the UI before the change persists.
The copilot itself runs as an agent under platform billing. Its model is configurable via /api/copilot/settings/model — defaults to gpt-5.2, with options including GPT-5.2, GPT-4.1, o3/o4, and Claude Opus/Sonnet/Haiku 4.x. Only function-calling-capable models are allowed. Runtime limits: 25 ReAct steps max, temperature 0.7, workflow state truncated at 50,000 chars total (block configs over 2,000 chars get ... [truncated]). 
requests.post(
    f"{BASE_URL}/api/copilot/sessions/{session_id}/chat",
    headers=headers,
    json={"message": "Build a workflow that...", "workflow_state": current_state},
    stream=True,
)

​
GET /api/copilot/settings/model

Get copilot model configuration. 
requests.get(f"{BASE_URL}/api/copilot/settings/model", headers=headers)

​
PUT /api/copilot/settings/model

Set copilot model. 
{ "model": "gpt-4o" }

requests.put(f"{BASE_URL}/api/copilot/settings/model", headers=headers, json={"model": "gpt-4o"})

​
Error Responses

Copilot routes return {"error": "<message>"}.
StatusDescription
400Missing required field (workflow_id on POST/GET, message on chat, pre_snapshot on snapshot, model on settings PUT)
400Settings PUT: model value fails registry validation (must be one of the allowed copilot model options)
404No workflow or copilot session exists with the given ID