Build Workflows with Copilot

The AI copilot generates a complete workflow graph from a natural language description. You create a copilot session linked to a workflow, describe what you want, and the copilot produces the blocks and edges. Iterate over multiple chat turns to refine the workflow.

Prerequisites:

Authentication configured (see Authentication guide)

Create a workflow

Create an empty workflow that the copilot will populate.Endpoint: POST /api/workflows

response = requests.post(
    f"{BASE_URL}/api/workflows",
    headers=headers,
    json={"name": "Email Classifier"},
)
workflow = response.json()
wf_id = workflow["id"]

const response = await fetch(`${BASE_URL}/api/workflows`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "Email Classifier" }),
});
const workflow = await response.json();
const wfId = workflow.id;

curl -X POST '{BASE_URL}/api/workflows' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Email Classifier"}'

Start a copilot session

Create a copilot session linked to the workflow.Endpoint: POST /api/copilot/sessions

response = requests.post(
    f"{BASE_URL}/api/copilot/sessions",
    headers=headers,
    json={"workflow_id": wf_id},
)
session = response.json()
session_id = session["id"]

const response = await fetch(`${BASE_URL}/api/copilot/sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({ workflow_id: wfId }),
});
const session = await response.json();
const sessionId = session.id;

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": "{wf_id}"}'

Describe your workflow

Send a natural language description via the chat endpoint. The copilot responds with a streaming SSE response that includes the generated workflow graph.Endpoint: POST /api/copilot/sessions/{id}/chat

response = requests.post(
    f"{BASE_URL}/api/copilot/sessions/{session_id}/chat",
    headers=headers,
    json={
        "message": "Build a workflow that takes an email as input, classifies it as spam/not-spam using an LLM, and outputs the classification with confidence score.",
    },
    stream=True,
)

message_id = None
for line in response.iter_lines():
    if not line:
        continue
    text = line.decode("utf-8")
    if text.startswith("data: "):
        event = json.loads(text[6:])
        if event.get("message_id"):
            message_id = event["message_id"]
        if event["event"] == "chunk":
            print(event["content"], end="")
print(f"\nMessage ID: {message_id}")

const response = await fetch(`${BASE_URL}/api/copilot/sessions/${sessionId}/chat`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    message: "Build a workflow that takes an email as input, classifies it as spam/not-spam using an LLM, and outputs the classification with confidence score.",
  }),
});
// Parse SSE stream for chunks and message_id

curl -N -X POST '{BASE_URL}/api/copilot/sessions/{session_id}/chat' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"message": "Build a workflow that classifies emails as spam or not-spam"}'

Save the copilot's suggestion

Save the copilot’s generated workflow graph as a snapshot. This applies the blocks and edges to the workflow.Endpoint: POST /api/copilot/sessions/{id}/messages/{mid}/snapshot

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

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

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

Execute the workflow

Run the copilot-built workflow with input data.Endpoint: POST /api/workflows/{id}/execute

You can also build workflows programmatically via PUT /api/workflows/{id}/graph; see the Build Workflows Programmatically guide.

response = requests.post(
    f"{BASE_URL}/api/workflows/{wf_id}/execute",
    headers=headers,
    json={"variables": {"email": "Congratulations! You've won a free iPhone..."}},
)
print(response.json())

const response = await fetch(`${BASE_URL}/api/workflows/${wfId}/execute`, {
  method: "POST",
  headers,
  body: JSON.stringify({ variables: { email: "Congratulations! You've won a free iPhone..." } }),
});
console.log(await response.json());

curl -X POST '{BASE_URL}/api/workflows/{wf_id}/execute' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"email": "Congratulations! You have won a free iPhone..."}}'

What’s Next

Workflows (Programmatic)

Fine-tune workflows by editing the graph directly.

Workflows

Understand block types and graph execution.

Copilot API Reference

Full endpoint documentation.

​What’s Next

Workflows (Programmatic)

Workflows

Copilot API Reference

What’s Next