Build Workflows Programmatically

Create automated workflows by defining blocks and edges via the API. Blocks are processing steps (LLM calls, agent runs, conditions). Edges connect them into a directed graph.

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)

1. Create a workflow

   Create an empty workflow container.

   Endpoint: POST /api/workflows

   Python

   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"]
   
2. Define the graph

   Save blocks (processing steps) and edges (connections between them) as a complete graph. Block types include: input, output, llm, agent, condition, code, and more.

   Endpoint: PUT /api/workflows/{id}/graph

   Python

   response = requests.put(
       f"{BASE_URL}/api/workflows/{wf_id}/graph",
       headers=headers,
       json={
           "blocks": [
               {"id": "input", "type": "input", "config": {}, "position": {"x": 0, "y": 0}},
               {"id": "summarize", "type": "llm", "config": {
                   "model": "gpt-4o",
                   "prompt": "Summarize the following document:\n\n{{input.text}}",
               }, "position": {"x": 300, "y": 0}},
               {"id": "output", "type": "output", "config": {}, "position": {"x": 600, "y": 0}},
           ],
           "edges": [
               {"source": "input", "target": "summarize"},
               {"source": "summarize", "target": "output"},
           ],
       },
   )
   print(response.json())
   
3. Execute the workflow

   Run the workflow with input data. Returns execution results.

   Endpoint: POST /api/workflows/{id}/execute

   Python

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

   Deploy the workflow to make it externally triggerable via webhook. First deploy, then arm for a single execution.

   Endpoint: POST /api/workflows/{id}/deploy + POST /api/workflows/{id}/arm

   Python

   # Deploy
   requests.post(f"{BASE_URL}/api/workflows/{wf_id}/deploy", headers=headers)
   
   # Arm for webhook trigger
   arm_response = requests.post(f"{BASE_URL}/api/workflows/{wf_id}/arm", headers=headers)
   webhook_info = arm_response.json()
   print(f"Webhook ID: {webhook_info['webhook_id']}")
   print(f"Secret: {webhook_info['secret']}")
   
5. Trigger externally

   Call the webhook endpoint from any external system. No API key needed — uses the secret from the arm step.

   Endpoint: POST /api/webhooks/{webhook_id}

   Webhooks are unauthenticated but validated by secret. After one trigger, you must re-arm the workflow for the next execution.

   Python

   response = requests.post(
       f"{BASE_URL}/api/webhooks/{webhook_id}",
       json={
           "secret": webhook_secret,
           "input": {"text": "Document to summarize..."},
       },
   )
   print(response.json())
   

What’s Next

Workflows (Copilot)

Build workflows with natural language.

Workflows

Understand block types and graph execution.

Workflows API Reference

Full endpoint documentation.