Workflows Endpoints

Endpoints for creating and managing workflows - DAG-based orchestrations of multiple agents.

List Workflows

GET /api/v1/workflows

List all workflows for the current tenant.

Query Parameters:

Parameter	Type	Description
`limit`	integer	Max results (default: 50)
`offset`	integer	Pagination offset
`is_active`	boolean	Filter by active status

Response:

{
  "items": [
    {
      "id": "uuid",
      "slug": "daily-call",
      "name": "Daily Health Check",
      "is_active": true,
      "created_at": "2026-01-17T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Get Workflow

GET /api/v1/workflows/{slug}

Get a workflow by slug.

Path Parameters:

Parameter	Type	Description
`slug`	string	Workflow slug (unique per tenant)

Response:

{
  "id": "uuid",
  "slug": "daily-call",
  "name": "Daily Health Check",
  "description": "Daily health check workflow with meal and glucose tracking",
  "config": {
    "nodes": [
      { 
        "id": "node-1", 
        "agent_name": "greeter-agent", 
        "is_entry": true,
        "position": { "x": 100, "y": 100 }
      },
      { 
        "id": "node-2", 
        "agent_name": "meal-agent",
        "skip_condition": "{{flags.skip_meal}}",
        "position": { "x": 300, "y": 100 }
      },
      { 
        "id": "node-3", 
        "agent_name": "feedback-agent", 
        "is_exit": true,
        "position": { "x": 500, "y": 100 }
      }
    ],
    "connections": [
      { "source_id": "node-1", "target_id": "node-2" },
      { "source_id": "node-2", "target_id": "node-3" }
    ],
    "shared_context": ["user_id", "logged_meals", "glucose_reading"]
  },
  "is_active": true
}

Create Workflow

POST /api/v1/workflows

Create a new workflow.

Request Body:

{
  "slug": "daily-call",
  "name": "Daily Health Check",
  "description": "Daily health check workflow",
  "config": {
    "nodes": [
      { 
        "id": "node-1", 
        "agent_name": "greeter-agent", 
        "is_entry": true 
      },
      { 
        "id": "node-2", 
        "agent_name": "meal-agent" 
      },
      { 
        "id": "node-3", 
        "agent_name": "feedback-agent", 
        "is_exit": true 
      }
    ],
    "connections": [
      { "source_id": "node-1", "target_id": "node-2" },
      { "source_id": "node-2", "target_id": "node-3" }
    ],
    "shared_context": ["user_id"]
  }
}

Required Fields:

Field	Type	Description
`slug`	string	Unique workflow identifier
`name`	string	Human-readable name
`config.nodes`	array	List of workflow nodes
`config.connections`	array	Connections between nodes

Update Workflow

PUT /api/v1/workflows/{slug}

Update an existing workflow.

Path Parameters:

Parameter	Type	Description
`slug`	string	Workflow slug

Request Body:

{
  "name": "Updated Workflow Name",
  "config": {
    "nodes": [...],
    "connections": [...]
  }
}

Delete Workflow

DELETE /api/v1/workflows/{slug}

Delete a workflow. Returns 204 on success.

Deleting a workflow will not affect calls already in progress, but will prevent new calls from using this workflow.

Activate Workflow

POST /api/v1/workflows/{slug}/activate

Activate a deactivated workflow.

Deactivate Workflow

POST /api/v1/workflows/{slug}/deactivate

Deactivate a workflow without deleting it.

Workflow Configuration Schema

Node Configuration

{
  "id": "node-1",
  "agent_name": "meal-agent",
  "is_entry": false,
  "is_exit": false,
  "skip_condition": "{{flags.skip_meal}}",
  "context_mapping": {
    "previous_meals": "workflow.logged_meals"
  },
  "position": { "x": 300, "y": 100 }
}

Field	Type	Description
`id`	string	Unique node identifier within workflow
`agent_name`	string	Name of the agent to use
`is_entry`	boolean	Whether this is an entry point
`is_exit`	boolean	Whether this is an exit point
`skip_condition`	string	Template expression to skip this node
`context_mapping`	object	Map context values to agent inputs
`position`	object	Visual position in editor (optional)

Connection Configuration

{
  "source_id": "node-1",
  "target_id": "node-2",
  "condition": "{{flags.meal_logged}}"
}

Field	Type	Description
`source_id`	string	Source node ID
`target_id`	string	Target node ID
`condition`	string	Optional condition for this connection

Shared Context

The shared_context array defines which context keys are available across all agents in the workflow:

{
  "shared_context": [
    "user_id",
    "logged_meals",
    "glucose_reading",
    "feedback_given"
  ]
}

Workflow Validation

Workflows are validated on create/update:

Must have exactly one entry node (is_entry: true)
Must have at least one exit node (is_exit: true)
All referenced agents must exist
No circular dependencies in connections
All node IDs must be unique
All connections must reference valid node IDs

Workflows Endpoints

On this page