Build Workflows Programmatically

Workflows are deterministic automation pipelines. Unlike agents (which decide what to do), workflows follow a fixed graph of blocks and edges. This guide creates a simple summarizer workflow and deploys it as a webhook.

Prerequisites:

Authentication configured (see Authentication guide)

Create a workflow

Create an empty workflow container.Endpoint: POST /api/workflows

response = requests.post(
    f"{BASE_URL}/api/workflows",
    headers=headers,
    json={"name": "Document Summarizer", "description": "Summarizes uploaded documents"},
)
workflow = response.json()
wf_id = workflow["id"]

const response = await fetch(`${BASE_URL}/api/workflows`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "Document Summarizer", description: "Summarizes uploaded documents" }),
});
const workflow = await response.json();

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

Define the graph

Save blocks (processing steps) and edges (connections between them) as a complete graph. The block registry recognizes these canonical types: starter, agent, code, condition, general_api, platform_api, response, split, webhook, orchestration (function and api_call are accepted as back-compat aliases for code and general_api). The example below wires a starter that injects workflow variables, runs an agent block to produce a summary, then returns the agent’s output through a response block.Endpoint: PUT /api/workflows/{id}/graph

# Assumes an agent already exists. Create one with POST /api/agents
# if you don't have one yet — see guides/build-agent.
agent_id = "..."  # existing agent UUID

response = requests.put(
    f"{BASE_URL}/api/workflows/{wf_id}/graph",
    headers=headers,
    json={
        "blocks": [
            {"id": "start", "type": "starter", "config": {}, "position": {"x": 0, "y": 0}},
            {"id": "summarize", "type": "agent", "config": {
                "agent_id": agent_id,
                "message": "Summarize the following document:\n\n{{variables.text}}",
            }, "position": {"x": 300, "y": 0}},
            {"id": "out", "type": "response", "config": {}, "position": {"x": 600, "y": 0}},
        ],
        "edges": [
            {"source": "start", "target": "summarize"},
            {"source": "summarize", "target": "out"},
        ],
    },
)
print(response.json())

// Assumes an agent already exists. Create one with POST /api/agents
// if you don't have one yet — see guides/build-agent.
const agentId = "..."; // existing agent UUID

await fetch(`${BASE_URL}/api/workflows/${wfId}/graph`, {
  method: "PUT",
  headers,
  body: JSON.stringify({
    blocks: [
      { id: "start", type: "starter", config: {}, position: { x: 0, y: 0 } },
      { id: "summarize", type: "agent", config: {
        agent_id: agentId,
        message: "Summarize the following document:\n\n{{variables.text}}",
      }, position: { x: 300, y: 0 } },
      { id: "out", type: "response", config: {}, position: { x: 600, y: 0 } },
    ],
    edges: [
      { source: "start", target: "summarize" },
      { source: "summarize", target: "out" },
    ],
  }),
});

curl -X PUT '{BASE_URL}/api/workflows/{wf_id}/graph' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"blocks": [...], "edges": [...]}'

Unknown block types are rejected with 400 Unknown block type. See the Workflows concept page for what each block does.

Execute the workflow

Run the workflow with input data. Returns execution results.Endpoint: POST /api/workflows/{id}/execute

response = requests.post(
    f"{BASE_URL}/api/workflows/{wf_id}/execute",
    headers=headers,
    json={"variables": {"text": "Your document content here..."}},
)
result = response.json()
print(result)

const response = await fetch(`${BASE_URL}/api/workflows/${wfId}/execute`, {
  method: "POST",
  headers,
  body: JSON.stringify({ variables: { text: "Your document content here..." } }),
});
const result = await response.json();
console.log(result);

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": {"text": "Your document content here..."}}'

Deploy with webhook

Two activation modes:

Deploy (POST /api/workflows/{id}/deploy) sets state = "deployed". The webhook accepts unlimited calls until you undeploy.
Arm (POST /api/workflows/{id}/arm) leaves state = "internal" but opens a 10-minute window during which the webhook accepts exactly one call. After it fires (or expires), you must arm again.

Use deploy for production integrations; use arm for one-shot tests.The webhook_id and webhook_secret are properties of the webhook block itself, stored in block.config. The studio editor mints them client-side when you drag in a webhook block. To retrieve them programmatically, fetch the workflow and pull them from the block’s config.

If you create the webhook block via API instead of the UI (PUT /api/workflows/{id}/graph), you must mint both webhook_id and webhook_secret yourself and include them in the block’s config. The server does not generate them. webhook_id MUST be a valid UUID; the trigger endpoint validates it and returns 400 otherwise. webhook_secret can be any non-empty string (the studio editor uses crypto.randomUUID() for both). A webhook block with no secret is silently un-triggerable (the trigger endpoint returns 401).

# Deploy (or arm) the workflow
requests.post(f"{BASE_URL}/api/workflows/{wf_id}/deploy", headers=headers)
# OR: requests.post(f"{BASE_URL}/api/workflows/{wf_id}/arm", headers=headers)

# Look up webhook credentials from the saved graph (assumes one webhook block)
wf = requests.get(f"{BASE_URL}/api/workflows/{wf_id}", headers=headers).json()
webhook_block = next(b for b in wf["blocks"] if b["type"] == "webhook")
webhook_id = webhook_block["config"]["webhook_id"]
webhook_secret = webhook_block["config"]["webhook_secret"]

// Deploy (or arm) the workflow
await fetch(`${BASE_URL}/api/workflows/${wfId}/deploy`, { method: "POST", headers });

// Look up webhook credentials from the saved graph (assumes one webhook block)
const wf = await fetch(`${BASE_URL}/api/workflows/${wfId}`, { headers }).then(r => r.json());
const webhookBlock = wf.blocks.find((b: { type: string }) => b.type === "webhook");
const webhookId = webhookBlock.config.webhook_id;
const webhookSecret = webhookBlock.config.webhook_secret;

# Deploy (or arm)
curl -X POST '{BASE_URL}/api/workflows/{wf_id}/deploy' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}"

# Read graph and pull webhook_id / webhook_secret from the block whose type=="webhook"
curl '{BASE_URL}/api/workflows/{wf_id}' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}"

The deploy endpoint returns {"ok": true, "state": "deployed"} and arm returns {"ok": true, "armed_until": "<iso-timestamp>"}. Neither response contains the webhook credentials.

Trigger externally

Call the webhook endpoint from any external system. No platform API key is needed; auth is per-webhook via the secret, sent either as a Bearer header (preferred) or a ?token= query param. The request body becomes the workflow’s input variables directly.

Use one auth mechanism or the other, not both. The server checks the header with auth_header.lower().startswith("bearer ") (note the trailing space). If your Authorization header is exactly Bearer (trailing space, no token), which is what Bearer ${secret || ""} produces when secret is falsy, the server reads an empty token and 401s without consulting ?token=. The ?token= fallback only fires when the header doesn’t start with Bearer .

Endpoint: POST /api/webhooks/{webhook_id}

If the workflow is deployed, the webhook accepts unlimited calls. If only armed, the webhook accepts exactly one call within the 10-minute window; re-arm to fire it again.

response = requests.post(
    f"{BASE_URL}/api/webhooks/{webhook_id}",
    headers={"Authorization": f"Bearer {webhook_secret}", "Content-Type": "application/json"},
    json={"text": "Document to summarize..."},
)
print(response.json())

const response = await fetch(`${BASE_URL}/api/webhooks/${webhookId}`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${webhookSecret}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Document to summarize..." }),
});
console.log(await response.json());

curl -X POST '{BASE_URL}/api/webhooks/{webhook_id}' \
  -H "Authorization: Bearer {webhook_secret}" \
  -H "Content-Type: application/json" \
  -d '{"text": "Document to summarize..."}'

What’s Next

Workflows (Copilot)

Build workflows with natural language.

Workflows

Understand block types and graph execution.

Workflows API Reference

Full endpoint documentation.

​What’s Next

Workflows (Copilot)

Workflows

Workflows API Reference

What’s Next