Agent Workflows

Build and manage AI voice agents with full version control

A voice agent (called a workflow in the API) is a directed graph of nodes that defines how an AI handles a phone conversation. Agents support full versioning — a published version runs live while a draft version is edited.

Endpoints

Method	Path	Description
GET	`/workflow/fetch`	List all agents
GET	`/workflow/fetch/{id}`	Get a specific agent by ID
POST	`/workflow/create/definition`	Create from a raw definition JSON
POST	`/workflow/create/template`	Create from a natural language template request
POST	`/workflow/templates/duplicate`	Duplicate an existing template into a new agent
PUT	`/workflow/{id}`	Update an agent's definition
PUT	`/workflow/{id}/status`	Publish or archive an agent
PUT	`/workflow/{id}/folder`	Move an agent into a folder
POST	`/workflow/{id}/duplicate`	Duplicate an agent (including definition, config, recordings, triggers)
POST	`/workflow/{id}/validate`	Validate all nodes in an agent (dry-run check)
POST	`/workflow/{id}/publish`	Publish the current draft version
POST	`/workflow/{id}/create-draft`	Create a new draft from the published version
GET	`/workflow/{id}/versions`	List version history (newest first)
GET	`/workflow/count`	Count active / archived agents
GET	`/workflow/summary`	Minimal agent info (id and name) for use in dropdowns
GET	`/workflow/templates`	List all available agent templates
GET	`/workflow/{id}/report`	Download a CSV report of completed runs
POST	`/workflow/ambient-noise/upload-url`	Get presigned URL to upload a custom ambient noise file

List Agents

GET

/workflow/fetch

Query Parameters

Parameter	Type	Required	Description
`status`	string	Optional	Filter by agent status. Accepted values: "active", "archived", or "all". Default: "active".

Response

json

{
  "workflows": [
    {
      "id": 247,
      "name": "Support Agent",
      "uuid": "3f2a1c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "status": "active",
      "created_at": "2026-05-01T10:00:00Z",
      "updated_at": "2026-06-15T12:00:00Z",
      "node_count": 4
    }
  ]
}

Get a Specific Agent

GET

/workflow/fetch/{id}

Returns the full agent definition including the published definition JSON, configuration overrides, and trigger paths.

Create from Definition

POST

/workflow/create/definition

Request Body — CreateWorkflowRequest

json

{
  "name": "Lead Qualification Agent",
  "definition": { ... },
  "configuration": { ... }
}

Create from Template (Natural Language)

POST

/workflow/create/template

Request Body — CreateWorkflowTemplateRequest

json

{
  "name": "My Support Agent",
  "template_description": "A customer support agent that handles billing questions and escalates to humans"
}

The platform generates the full agent definition from the description.

Duplicate a Template

POST

/workflow/templates/duplicate

Request Body — DuplicateTemplateRequest

json

{
  "template_id": "inbound-support",
  "name": "My Support Agent"
}

Update an Agent

PUT

/workflow/{id}

Request body — UpdateWorkflowRequest: partial or full update of the agent definition and configuration.

Update Status (Publish / Archive)

PUT

/workflow/{id}/status

Request Body — UpdateWorkflowStatusRequest

json

{ "status": "active" }

Valid values: "active", "archived"

Move to Folder

PUT

/workflow/{id}/folder

Request Body — MoveWorkflowToFolderRequest

json

{ "folder_id": 5 }

Pass null for folder_id to move to Uncategorized.

Duplicate an Agent

POST

/workflow/{id}/duplicate

Duplicates the agent including its definition, configuration, recordings, and triggers. The new agent is created in draft status.

Response includes the new agent's workflow_id.

Validate an Agent

POST

/workflow/{id}/validate

Performs a dry-run validation of all nodes — checks required fields, edge connectivity, and trigger path uniqueness. Does not modify the agent.

Response — Valid

Response

json

{
  "is_valid": true,
  "errors": []
}

Response — Invalid

Response

json

{
  "is_valid": false,
  "errors": [
    {
      "kind": "node",
      "id": "node-abc123",
      "field": "data.prompt",
      "message": "Prompt is required"
    }
  ]
}

Publish

POST

/workflow/{id}/publish

Promotes the current draft to the live published version. All subsequent calls after publishing use the new definition.

Create Draft

POST

/workflow/{id}/create-draft

Creates a new editable draft from the current published definition. The published agent is untouched.

Version History

GET

/workflow/{id}/versions

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Maximum number of results to return. Default: 20.
`offset`	integer	Optional	Pagination offset.

Returns versions newest-first, each with a timestamp, author, and whether it is the current published version.

Download CSV Report

GET

/workflow/{id}/report

Query Parameters

Parameter	Type	Required	Description
`start_date`	datetime	Optional	ISO 8601 start filter.
`end_date`	datetime	Optional	ISO 8601 end filter.

Returns a CSV file with all completed runs: duration, outcome, transcript summary, and extracted data fields.

Ambient Noise Upload

POST

/workflow/ambient-noise/upload-url

Request Body — AmbientNoiseUploadRequest

json

{
  "filename": "office-background.mp3",
  "content_type": "audio/mpeg"
}

Response

json

{
  "upload_url": "https://...",
  "file_key": "ambient-noise/abc123/office-background.mp3"
}

Upload the audio file directly to the upload_url via PUT. The file_key is then referenced in the agent's voice configuration.

Was this page helpful?

PreviousAPI Keys NextWorkflow Runs