Copilot

The Copilot API is 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. Iterate over multiple chat turns to refine it, 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})

await fetch(`${BASE_URL}/api/copilot/sessions`, { method: "POST", headers, body: JSON.stringify({ workflow_id: wfId }) });

curl -X POST '{BASE_URL}/api/copilot/sessions' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"workflow_id": "uuid"}'

GET /api/copilot/sessions

Get session by workflow_id.

string

required

Workflow ID

requests.get(f"{BASE_URL}/api/copilot/sessions?workflow_id={wf_id}", headers=headers)

await fetch(`${BASE_URL}/api/copilot/sessions?workflow_id=${wfId}`, { headers });

curl '{BASE_URL}/api/copilot/sessions?workflow_id={wf_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

DELETE /api/copilot/sessions/

Delete a copilot session.

string

required

Session ID

requests.delete(f"{BASE_URL}/api/copilot/sessions/{session_id}", headers=headers)

await fetch(`${BASE_URL}/api/copilot/sessions/${sessionId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/copilot/sessions/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

GET /api/copilot/sessions//messages

Get copilot conversation history.

string

required

Session ID

requests.get(f"{BASE_URL}/api/copilot/sessions/{session_id}/messages", headers=headers)

await fetch(`${BASE_URL}/api/copilot/sessions/${sessionId}/messages`, { headers });

curl '{BASE_URL}/api/copilot/sessions/{id}/messages' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

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

Save the copilot’s workflow suggestion as a snapshot.

string

required

Session ID

string

required

Message ID

requests.post(f"{BASE_URL}/api/copilot/sessions/{session_id}/messages/{message_id}/snapshot", headers=headers)

await fetch(`${BASE_URL}/api/copilot/sessions/${sessionId}/messages/${messageId}/snapshot`, { method: "POST", headers });

curl -X POST '{BASE_URL}/api/copilot/sessions/{id}/messages/{mid}/snapshot' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

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.

string

required

Session ID

{
  "message": "Add a step that sends Slack notifications when the run finishes",
  "workflow_state": { "nodes": [...], "edges": [...] }
}

Body field	Type	Notes
`message`	string (required)	User message
`workflow_state`	object	The 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):

Event	Payload	When
`status`	`{ message }`	Human-readable status string (“Thinking…”, “Modifying workflow…”, etc.) for the UI. Derived from the ReAct step and 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:

Tool	Purpose
`modify_workflow`	Add / 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_info`	Look up the schema for a block type (which config fields, defaults, validation) before constructing it
`get_db_schema`	Read the project database’s schema (tables, columns, types) so the copilot can build correct SQL for code or general_api blocks
`list_project_assets`	Enumerate existing agents, KBs, orchestrations, workflows the copilot might want to call
`get_asset_details`	Fetch one asset’s full config. For agents, the system prompt is truncated to 1000 chars to fit context
`execute_public_sql`	Run a read-only SQL query against the project DB (public schema only) for exploring data before designing a block
`get_workflow_run_logs`	Read past execution logs from this workflow, e.g. for “the last run failed at step X, fix it”
`manage_project_asset`	Create / 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 and 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,
)

await fetch(`${BASE_URL}/api/copilot/sessions/${sessionId}/chat`, {
  method: "POST", headers,
  body: JSON.stringify({ message: "Build a workflow that...", workflow_state: currentState }),
});

curl -N -X POST '{BASE_URL}/api/copilot/sessions/{id}/chat' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"message": "Build a workflow that..."}'

GET /api/copilot/settings/model

Get copilot model configuration.

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

await fetch(`${BASE_URL}/api/copilot/settings/model`, { headers });

curl '{BASE_URL}/api/copilot/settings/model' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

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"})

await fetch(`${BASE_URL}/api/copilot/settings/model`, { method: "PUT", headers, body: JSON.stringify({ model: "gpt-4o" }) });

curl -X PUT '{BASE_URL}/api/copilot/settings/model' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"model": "gpt-4o"}'

Error Responses

Copilot routes return {"error": "<message>"}.

Status	Description
400	Missing required field (`workflow_id` on POST/GET, `message` on chat, `pre_snapshot` on snapshot, `model` on settings PUT)
400	Settings PUT: `model` value fails registry validation (must be one of the allowed copilot model options)
404	No workflow or copilot session exists with the given ID

Getting Started

Concepts

Guides

API Reference

Common Patterns

POST /api/copilot/sessions

GET /api/copilot/sessions

DELETE /api/copilot/sessions/

GET /api/copilot/sessions//messages

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

POST /api/copilot/sessions//chat

SSE event types

Copilot tools

GET /api/copilot/settings/model

PUT /api/copilot/settings/model

Error Responses

​Common Patterns

​POST /api/copilot/sessions

​GET /api/copilot/sessions

​DELETE /api/copilot/sessions/

​GET /api/copilot/sessions//messages

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

​POST /api/copilot/sessions//chat

​SSE event types

​Copilot tools

​GET /api/copilot/settings/model

​PUT /api/copilot/settings/model

​Error Responses

Common Patterns

POST /api/copilot/sessions

GET /api/copilot/sessions

DELETE /api/copilot/sessions/

GET /api/copilot/sessions//messages

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

POST /api/copilot/sessions//chat

SSE event types

Copilot tools

GET /api/copilot/settings/model

PUT /api/copilot/settings/model

Error Responses