Workflows API
Federated workflow zones with folders, phases, custom fields, field rules, routing (including cross-workflow routes), items, assignment groups, saved views, comments, attachments, access control, and activity history. Creating a workflow provisions a zero-trust federated zone rooted at org/{company_id}/folder/{folder_id}/workflow/{workflow_id}; the creator receives the initial local permission bundle. Automations are managed by the central `automations` service.
/api/v1/workflowsAutomation triggers: view every Workflows event, payload field, and predicate.
Workflows
Create and manage workflow definitions inside folders. A workflow is a zero-trust federated zone; the creator receives the initial local permission bundle. Includes folder moves, graph layout, and the record-source pickers (worksheets/views) used to configure record fields.
/api/v1/workflows/companies/{company_id}/workflowsCreate Workflow
Create a new workflow in a folder for the given company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Organization ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Workflow name |
folder_id* | UUID | Folder the workflow belongs to |
description | string | null | Optional description |
mode | string (process | project) | Workflow modeDefault: process |
notify_when_assigned | boolean | Send assignment emails by defaultDefault: false |
default_max_assignees_per_item | integer | Maximum concurrent assignees per item; 0 means unlimitedDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Workflow ID |
company_id* | UUID | Organization ID |
folder_id | UUID | null | Containing folder |
name* | string | Name |
description* | string | null | Description |
mode | string (process | project) | Workflow modeDefault: process |
created_by* | UUID | null | Creating user |
created_at* | datetime | Creation time |
phase_count | integer | Number of phases |
field_count | integer | Number of fields |
item_count | integer | Number of items |
default_max_assignees_per_item | integer | null | Default assignee cap per item; 0 means unlimited and legacy null means 1 |
notify_when_assigned | boolean | Send an email when a new assignee is added; phases can override this defaultDefault: false |
global_timeout_minutes | number | null | Workflow-wide timeout |
global_timeout_target_phase_id | UUID | null | Phase items move to on global timeout |
graph_layout | object | null | Saved graph layout positions |
managed_bucket_id | UUID | null | Managed attachment bucket |
managed_automation_project_id | UUID | null | Managed automation project |
principal_id | UUID | null | Workflow service principal |
capabilities | object | Caller's capability flags for this workflow |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/companies/c0ffee00-cafe-babe-dead-beefcafebabe/workflows \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Support queue", "folder_id": "01234567-89ab-cdef-0123-456789abcdef", "description": "Tier-1 intake"}'Response
201 Created{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"folder_id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Support queue",
"description": "Tier-1 intake",
"mode": "process",
"default_max_assignees_per_item": 0,
"created_by": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"created_at": "2026-06-01T12:00:00Z",
"phase_count": 0,
"field_count": 0,
"item_count": 0,
"graph_layout": null,
"capabilities": {"manage_settings": true, "manage_security": true}
}/api/v1/workflows/companies/{company_id}/workflowsList Workflows
List workflows for a company, respecting view permissions.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Organization ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Page sizeDefault: 50 |
offset | integer | Offset for paginationDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<WorkflowResponse> | Page of workflows |
total* | integer | Total matching workflows |
limit* | integer | Page size |
offset* | integer | Page offset |
curl "https://platform.ergondata.ai/api/v1/workflows/companies/c0ffee00-cafe-babe-dead-beefcafebabe/workflows?limit=50&offset=0" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Support queue",
"description": "Tier-1 intake",
"folder_id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2026-06-01T12:00:00Z",
"phase_count": 3,
"item_count": 42
}
],
"total": 1,
"limit": 50,
"offset": 0
}/api/v1/workflows/companies/{company_id}/process-entry-phasesList Process Entry Phases
List create-capable, non-terminal workflow phases where the caller may create items.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Organization ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Page size (1–200)Default: 200 |
offset | integer | Offset for paginationDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array | Create-capable workflow entry phases visible to the caller |
total* | integer | Total matching phases |
limit* | integer | Page size |
offset* | integer | Page offset |
curl "https://platform.ergondata.ai/api/v1/workflows/companies/c0ffee00-cafe-babe-dead-beefcafebabe/process-entry-phases?limit=200&offset=0" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"workflow_name": "Support queue",
"phase_name": "Open"
}
],
"total": 1,
"limit": 200,
"offset": 0
}/api/v1/workflows/workflows/{workflow_id}Get Workflow
Return a single workflow with counts and the caller's capabilities.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Workflow ID |
company_id* | UUID | Organization ID |
folder_id | UUID | null | Containing folder |
name* | string | Name |
description* | string | null | Description |
mode | string (process | project) | Workflow modeDefault: process |
created_by* | UUID | null | Creating user |
created_at* | datetime | Creation time |
phase_count | integer | Number of phases |
field_count | integer | Number of fields |
item_count | integer | Number of items |
default_max_assignees_per_item | integer | null | Default assignee cap per item; 0 means unlimited and legacy null means 1 |
notify_when_assigned | boolean | Send an email when a new assignee is added; phases can override this defaultDefault: false |
global_timeout_minutes | number | null | Workflow-wide timeout |
global_timeout_target_phase_id | UUID | null | Phase items move to on global timeout |
graph_layout | object | null | Saved graph layout positions |
managed_bucket_id | UUID | null | Managed attachment bucket |
managed_automation_project_id | UUID | null | Managed automation project |
principal_id | UUID | null | Workflow service principal |
capabilities | object | Caller's capability flags for this workflow |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"folder_id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Support queue",
"description": "Tier-1 intake",
"mode": "process",
"phase_count": 3,
"field_count": 5,
"item_count": 42,
"global_timeout_minutes": null,
"graph_layout": null,
"created_at": "2026-06-01T12:00:00Z"
}/api/v1/workflows/workflows/{workflow_id}Update Workflow
Update workflow settings such as name, description, mode, and global timeout.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name |
description | string | null | New description |
mode | string (process | project) | null | Workflow mode |
default_max_assignees_per_item | integer | null | Default assignee cap per item; 0 means unlimited. Explicit null restores the current default of 0 |
notify_when_assigned | boolean | Enable assignment emails by default for this workflow |
global_timeout_minutes | number | null | Workflow-wide timeout |
global_timeout_target_phase_id | UUID | null | Phase items move to on global timeout |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Workflow ID |
company_id* | UUID | Organization ID |
folder_id | UUID | null | Containing folder |
name* | string | Name |
description* | string | null | Description |
mode | string (process | project) | Workflow modeDefault: process |
created_by* | UUID | null | Creating user |
created_at* | datetime | Creation time |
phase_count | integer | Number of phases |
field_count | integer | Number of fields |
item_count | integer | Number of items |
default_max_assignees_per_item | integer | null | Default assignee cap per item; 0 means unlimited and legacy null means 1 |
notify_when_assigned | boolean | Send an email when a new assignee is added; phases can override this defaultDefault: false |
global_timeout_minutes | number | null | Workflow-wide timeout |
global_timeout_target_phase_id | UUID | null | Phase items move to on global timeout |
graph_layout | object | null | Saved graph layout positions |
managed_bucket_id | UUID | null | Managed attachment bucket |
managed_automation_project_id | UUID | null | Managed automation project |
principal_id | UUID | null | Workflow service principal |
capabilities | object | Caller's capability flags for this workflow |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"description": "Tier-1 + tier-2 intake"}'Response
200 OK{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Support queue",
"description": "Tier-1 + tier-2 intake",
"mode": "process"
}/api/v1/workflows/workflows/{workflow_id}Delete Workflow
Delete a workflow and its federated zone. Remaining non-expired item-export artifacts are purged first.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/workflows/{workflow_id}/folderMove Workflow Folder
Move a workflow into a different folder.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
folder_id* | UUID | Destination folder |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Workflow ID |
company_id* | UUID | Organization ID |
folder_id | UUID | null | Containing folder |
name* | string | Name |
description* | string | null | Description |
mode | string (process | project) | Workflow modeDefault: process |
created_by* | UUID | null | Creating user |
created_at* | datetime | Creation time |
phase_count | integer | Number of phases |
field_count | integer | Number of fields |
item_count | integer | Number of items |
default_max_assignees_per_item | integer | null | Default assignee cap per item; 0 means unlimited and legacy null means 1 |
notify_when_assigned | boolean | Send an email when a new assignee is added; phases can override this defaultDefault: false |
global_timeout_minutes | number | null | Workflow-wide timeout |
global_timeout_target_phase_id | UUID | null | Phase items move to on global timeout |
graph_layout | object | null | Saved graph layout positions |
managed_bucket_id | UUID | null | Managed attachment bucket |
managed_automation_project_id | UUID | null | Managed automation project |
principal_id | UUID | null | Workflow service principal |
capabilities | object | Caller's capability flags for this workflow |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/folder \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"folder_id": "01234567-89ab-cdef-0123-456789abcdef"}'Response
200 OK{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"folder_id": "01234567-89ab-cdef-0123-456789abcdef"
}/api/v1/workflows/workflows/{workflow_id}/graph-layoutSave Graph Layout
Persist the phase node positions and handles for the workflow graph editor.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
positions* | object | Map of phase ID to {x, y} position |
handles | object | null | Edge handle anchors |
layout_mode | string (freeform | auto) | null | Layout mode |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Workflow ID |
company_id* | UUID | Organization ID |
folder_id | UUID | null | Containing folder |
name* | string | Name |
description* | string | null | Description |
mode | string (process | project) | Workflow modeDefault: process |
created_by* | UUID | null | Creating user |
created_at* | datetime | Creation time |
phase_count | integer | Number of phases |
field_count | integer | Number of fields |
item_count | integer | Number of items |
default_max_assignees_per_item | integer | null | Default assignee cap per item; 0 means unlimited and legacy null means 1 |
notify_when_assigned | boolean | Send an email when a new assignee is added; phases can override this defaultDefault: false |
global_timeout_minutes | number | null | Workflow-wide timeout |
global_timeout_target_phase_id | UUID | null | Phase items move to on global timeout |
graph_layout | object | null | Saved graph layout positions |
managed_bucket_id | UUID | null | Managed attachment bucket |
managed_automation_project_id | UUID | null | Managed automation project |
principal_id | UUID | null | Workflow service principal |
capabilities | object | Caller's capability flags for this workflow |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/graph-layout \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"layout_mode": "freeform", "positions": {"b2c3d4e5-f6a7-8901-bcde-f12345678901": {"x": 120, "y": 40}}}'Response
200 OK{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"graph_layout": {"layout_mode": "freeform", "positions": {"b2c3d4e5-f6a7-8901-bcde-f12345678901": {"x": 120, "y": 40}}}
}/api/v1/workflows/workflows/{workflow_id}/graph-layoutDelete Graph Layout
Clear the saved graph layout, reverting to the automatic layout.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/graph-layout \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/workflows/{workflow_id}/attachment-bucket-targetsList Attachment Bucket Targets
List buckets and folders eligible as custom attachment-field targets. Returns the buckets and folder tree the calling user can view; system-managed buckets and folders are filtered out.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Target node ID |
target_type* | string | bucket or folder |
name* | string | Display name |
bucket_id* | UUID | Owning bucket |
bucket_name | string | Bucket name |
folder_id | UUID | null | Folder ID (for folder targets) |
parent_folder_id | UUID | null | Parent folder |
depth | integer | Depth in the folder tree |
storage_path | string | Storage path |
folders | array<WorkflowBucketTargetOption> | Nested folder options |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/attachment-bucket-targets" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "bucket-uuid",
"target_type": "bucket",
"name": "Support uploads",
"bucket_id": "bucket-uuid",
"folders": []
}
]/api/v1/workflows/workflows/{workflow_id}/record-worksheetsList Record Worksheets
List worksheets eligible for a workflow record field. Returns the worksheets the calling user can view; saving a record field against one auto-provisions the workflow principal's connection and grants.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Worksheet ID |
name* | string | Worksheet name |
folder_id* | UUID | Containing folder |
folder_name | string | null | Folder name |
column_count | integer | Number of columns |
created_at* | datetime | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/record-worksheets" \
-H "Authorization: Bearer {token}"Response
200 OK[
{"id": "9999aaaa-bbbb-cccc-dddd-eeeeffff0000", "name": "Customers", "folder_id": "01234567-89ab-cdef-0123-456789abcdef", "column_count": 8}
]/api/v1/workflows/workflows/{workflow_id}/record-worksheets/{worksheet_id}/columnsList Record Worksheet Columns
List columns of a worksheet for the record-field config picker.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
worksheet_id* | string (UUID) | Worksheet ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
include_capabilities | boolean | Also return can_edit_rows: whether the caller can edit rows in each column (default false) |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/record-worksheets/9999aaaa-bbbb-cccc-dddd-eeeeffff0000/columns" \
-H "Authorization: Bearer {token}"Response
200 OK{
"columns": [
{"id": "col-uuid", "name": "Email", "type": "text"}
]
}/api/v1/workflows/workflows/{workflow_id}/record-viewsList Record Views
List worksheet views eligible as a workflow record-field target.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | View ID |
name* | string | View name |
worksheet_id* | UUID | Backing worksheet |
worksheet_name | string | null | Worksheet name |
folder_id* | UUID | Containing folder |
folder_name | string | null | Folder name |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/record-views" \
-H "Authorization: Bearer {token}"Response
200 OK[
{"id": "f6a7b8c9-d0e1-2345-6789-012345678901", "name": "Active customers", "worksheet_id": "9999aaaa-bbbb-cccc-dddd-eeeeffff0000", "folder_id": "01234567-89ab-cdef-0123-456789abcdef"}
]/api/v1/workflows/workflows/{workflow_id}/record-views/{view_id}/columnsList Record View Columns
List visible columns of a worksheet view for the record-field config picker.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
view_id* | string (UUID) | View ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
include_capabilities | boolean | Also return can_edit_rows: whether the caller can edit rows in each column (default false) |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/record-views/f6a7b8c9-d0e1-2345-6789-012345678901/columns" \
-H "Authorization: Bearer {token}"Response
200 OK{
"columns": [
{"id": "col-uuid", "name": "Status", "type": "select"}
]
}/api/v1/workflows/workflows/{workflow_id}/record-sourcesList Record Sources
Folders, worksheets and views the calling user can pick as a record field target, in one call. Faster than listing worksheets and views separately: no counts, and permissions are checked in batches.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
folders* | array | Folders (id, name) |
worksheets* | array | Worksheets (id, folder_id, name) |
views* | array | Views (id, folder_id, worksheet_id, worksheet_name, name) |
truncated* | boolean | True when some sources the user can view may be missing: a list reached 2000 entries, or the scan stopped after about 10,000 rows |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/record-sources" \
-H "Authorization: Bearer {token}"Response
200 OK{
"folders": [{"id": "01234567-89ab-cdef-0123-456789abcdef", "name": "Entidades"}],
"worksheets": [{"id": "9999aaaa-bbbb-cccc-dddd-eeeeffff0000", "folder_id": "01234567-89ab-cdef-0123-456789abcdef", "name": "Clientes"}],
"views": [
{"id": "f6a7b8c9-d0e1-2345-6789-012345678901", "folder_id": "01234567-89ab-cdef-0123-456789abcdef", "worksheet_id": "9999aaaa-bbbb-cccc-dddd-eeeeffff0000", "worksheet_name": "Clientes", "name": "Clientes ativos"}
],
"truncated": false
}Folders
Folders group workflows within a company and act as a folder-zone for access control and aggregated activity. Includes per-user folder preferences (favorite and ordering).
/api/v1/workflows/companies/{company_id}/foldersList Folders
List folders for a company, with workflow counts.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Organization ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Folder ID |
name* | string | Folder name |
description* | string | null | Description |
color* | string | Display color |
icon* | string | null | Display icon |
workflow_count | integer | Workflows in the folderDefault: 0 |
created_at* | datetime | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/companies/c0ffee00-cafe-babe-dead-beefcafebabe/folders" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Customer Success",
"description": null,
"color": "#6366f1",
"icon": "inbox",
"workflow_count": 4,
"created_at": "2026-05-01T09:00:00Z"
}
]/api/v1/workflows/companies/{company_id}/foldersCreate Folder
Create a new folder for the given company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Organization ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Folder name |
description | string | null | Description |
color | string | null | Display color |
icon | string | null | Display icon |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Folder ID |
company_id* | UUID | Organization ID |
name* | string | Folder name |
description* | string | null | Description |
color* | string | Display color |
icon* | string | null | Display icon |
created_by* | UUID | null | Creating user |
workflow_count | integer | Workflows in the folderDefault: 0 |
created_at* | datetime | Creation time |
capabilities | object | Caller's capability flags for this folder |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/companies/c0ffee00-cafe-babe-dead-beefcafebabe/folders \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Customer Success", "color": "#6366f1"}'Response
201 Created{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Customer Success",
"description": null,
"color": "#6366f1",
"icon": null,
"workflow_count": 0,
"created_at": "2026-06-01T12:00:00Z"
}/api/v1/workflows/folders/{folder_id}Get Folder
Return a single folder with the caller's capabilities.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Folder ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Folder ID |
company_id* | UUID | Organization ID |
name* | string | Folder name |
description* | string | null | Description |
color* | string | Display color |
icon* | string | null | Display icon |
created_by* | UUID | null | Creating user |
workflow_count | integer | Workflows in the folderDefault: 0 |
created_at* | datetime | Creation time |
capabilities | object | Caller's capability flags for this folder |
curl "https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Customer Success",
"color": "#6366f1",
"workflow_count": 4,
"capabilities": {"can_create_workflow": true, "manage_security": true}
}/api/v1/workflows/folders/{folder_id}Update Folder
Update a folder's name, description, color, or icon.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Folder ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name |
description | string | null | New description |
color | string | null | New color |
icon | string | null | New icon |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Folder ID |
company_id* | UUID | Organization ID |
name* | string | Folder name |
description* | string | null | Description |
color* | string | Display color |
icon* | string | null | Display icon |
created_by* | UUID | null | Creating user |
workflow_count | integer | Workflows in the folderDefault: 0 |
created_at* | datetime | Creation time |
capabilities | object | Caller's capability flags for this folder |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "CS & Support"}'Response
200 OK{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "CS & Support"
}/api/v1/workflows/folders/{folder_id}Delete Folder
Delete an empty folder.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Folder ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/folders/{folder_id}/workflowsList Folder Workflows
List workflows contained in a folder.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Folder ID |
curl "https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/workflows" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Support queue", "folder_id": "01234567-89ab-cdef-0123-456789abcdef"}
]
}/api/v1/workflows/companies/{company_id}/folder-orderGet Folder Order
Return the caller's personal workflow-folder display order.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Organization ID |
Response Fields
| Name | Type | Description |
|---|---|---|
folder_order* | array<UUID> | Ordered accessible folder IDs |
curl "https://platform.ergondata.ai/api/v1/workflows/companies/c0ffee00-cafe-babe-dead-beefcafebabe/folder-order" \
-H "Authorization: Bearer {token}"Response
200 OK{"folder_order": ["01234567-89ab-cdef-0123-456789abcdef"]}/api/v1/workflows/companies/{company_id}/folder-orderUpdate Folder Order
Replace the caller's personal workflow-folder display order.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Organization ID |
Request Body
| Name | Type | Description |
|---|---|---|
folder_order* | array<UUID> | Complete ordered folder ID list |
curl -X PUT "https://platform.ergondata.ai/api/v1/workflows/companies/c0ffee00-cafe-babe-dead-beefcafebabe/folder-order" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"folder_order": ["01234567-89ab-cdef-0123-456789abcdef"]}'Response
200 OK{"folder_order": ["01234567-89ab-cdef-0123-456789abcdef"]}/api/v1/workflows/companies/{company_id}/workflow-favoritesList Workflow Favorites
List every workflow favorited by the caller in this organization.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Organization ID |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<WorkflowFavorite> | Visible favorites, newest first; each includes workflow_id, company_id, folder_id, and created_at |
curl "https://platform.ergondata.ai/api/v1/workflows/companies/c0ffee00-cafe-babe-dead-beefcafebabe/workflow-favorites" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [{
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"folder_id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2026-07-22T14:00:00Z"
}]
}/api/v1/workflows/workflows/{workflow_id}/favoriteFavorite Workflow
Idempotently add a workflow to the caller's favorites.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
curl -X PUT "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/favorite" \
-H "Authorization: Bearer {token}"Response
200 OK{
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"folder_id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2026-07-22T14:00:00Z"
}/api/v1/workflows/workflows/{workflow_id}/favoriteUnfavorite Workflow
Idempotently remove a workflow from the caller's favorites.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
curl -X DELETE "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/favorite" \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No ContentPhases
Phases are the columns or stages within a workflow. They carry SLA/visibility timeouts, assignee caps, working hours, and the principals eligible to be assigned there. Every workflow also has one built-in exception phase (`kind: exception`) for items that hit a problem; see the Workflows guide.
/api/v1/workflows/workflows/{workflow_id}/phasesList Phases
List the phases of a workflow in display order.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Phase ID |
workflow_id* | UUID | Owning workflow |
name* | string | Phase name |
description* | string | null | Description |
position* | integer | Order within the workflow |
color | string | Display colorDefault: #3b82f6 |
is_terminal | boolean | Whether this is an end phaseDefault: false |
kind* | string | Processing mode: `standard`, `pull` or `exception`, fixed at creation. Every workflow has one exception phase. Pull phases are take-only: items are pulled or claimed, never assigned.Default: standard |
processing_policy | object (ProcessingPolicy) | null | Stored processing policy with defaults filled; null when the phase has none |
pull_policy | object (ProcessingPolicy) | null | Deprecated copy of processing_policy, removed in the next release |
allow_create_items | boolean | Whether items can be created directly into this phaseDefault: true |
max_assignees_per_item | integer | null | Assignee cap per item |
notify_when_assigned | boolean | null | Phase assignment-email override; null inherits the workflow default |
field_count | integer | Number of phase fields |
item_count | integer | Number of items in the phase |
timeout_minutes | number | null | Phase SLA timeout |
timeout_target_phase_id | UUID | null | Phase items move to on timeout |
return_to_origin_on_timeout* | boolean | Exceptions phase: timed-out items return to their origin phase |
visibility_timeout_on_create_minutes | integer | null | Hide-on-create window |
visibility_timeout_on_release_minutes | integer | null | Hide-on-release window |
visibility_timeout_on_transition_minutes | integer | null | Hide-on-transition window |
created_at* | datetime | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/phases" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Triage",
"position": 0,
"color": "#3b82f6",
"is_terminal": false,
"kind": "standard",
"field_count": 2,
"item_count": 12,
"created_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/workflows/{workflow_id}/phasesCreate Phase
Create a phase. Optionally attach a default assignment group, either an existing one (default_group_id) or a new one created inline (default_group).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Phase name |
description | string | null | Description |
kind | "standard" | "pull" | Processing mode, fixed after creation. The exception kind cannot be set; pull phases cannot be terminalDefault: "standard" |
processing_policy | object (ProcessingPolicy) | null | Any mode. Fields left out of the object are unset: no limit, no retry delay, claims that never expire. Only a pull phase created with no policy at all stores retry_delay fixed 60 s and claim_timeout_seconds 300. pull_policy is a deprecated alias |
default_group_id | UUID | null | Existing assignment group to attach as default |
default_group | object (NewGroupPayload) | null | Inline new assignment group |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Phase ID |
workflow_id* | UUID | Owning workflow |
name* | string | Phase name |
description* | string | null | Description |
position* | integer | Order within the workflow |
color | string | Display colorDefault: #3b82f6 |
is_terminal | boolean | Whether this is an end phaseDefault: false |
kind* | string | Processing mode: `standard`, `pull` or `exception`, fixed at creation. Every workflow has one exception phase. Pull phases are take-only: items are pulled or claimed, never assigned.Default: standard |
processing_policy | object (ProcessingPolicy) | null | Stored processing policy with defaults filled; null when the phase has none |
pull_policy | object (ProcessingPolicy) | null | Deprecated copy of processing_policy, removed in the next release |
allow_create_items | boolean | Whether items can be created directly into this phaseDefault: true |
max_assignees_per_item | integer | null | Assignee cap per item |
notify_when_assigned | boolean | null | Phase assignment-email override; null inherits the workflow default |
field_count | integer | Number of phase fields |
item_count | integer | Number of items in the phase |
timeout_minutes | number | null | Phase SLA timeout |
timeout_target_phase_id | UUID | null | Phase items move to on timeout |
return_to_origin_on_timeout* | boolean | Exceptions phase: timed-out items return to their origin phase |
visibility_timeout_on_create_minutes | integer | null | Hide-on-create window |
visibility_timeout_on_release_minutes | integer | null | Hide-on-release window |
visibility_timeout_on_transition_minutes | integer | null | Hide-on-transition window |
created_at* | datetime | Creation time |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/phases \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Triage"}'Response
201 Created{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Triage",
"position": 0,
"created_at": "2026-06-01T12:00:00Z"
}/api/v1/workflows/phases/{phase_id}Update Phase
Update phase settings: name, color, terminal flag, processing_policy, timeouts (including the Exceptions return to origin), visibility windows, and assignee caps. The processing mode (kind) is set at creation and ignored here. Any phase's timeout may target the Exceptions phase without a route.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name |
description | string | null | New description |
color | string | null | Display color |
is_terminal | boolean | null | Whether this is an end phase. Pull phases cannot be terminal (400 pull_phase_not_terminal). kind is not updatable and is ignored if sent |
processing_policy | object (ProcessingPolicy) | null | Any user phase (400 exception_phase_kind_locked on the Exceptions phase). Replaces the whole policy: fields left out of the object are unset, so send every knob you want to keep. null clears it, omitted leaves it alone. pull_policy is a deprecated alias |
allow_create_items | boolean | null | Allow creating items directly into this phase |
max_assignees_per_item | integer | null | Assignee cap per item |
notify_when_assigned | boolean | null | Phase assignment-email override; null inherits workflow setting |
timeout_minutes | number | null | Phase SLA timeout |
timeout_target_phase_id | UUID | null | Phase items move to on timeout. 400 return_to_origin_with_timeout_target while return_to_origin_on_timeout is on |
return_to_origin_on_timeout | boolean | Exceptions phase only (400 return_to_origin_exception_only elsewhere): on timeout each item returns to its origin over the system route, if the route's condition passes. Over max passes the item stays and workflows.items.exhausted is emitted. Requires timeout_target_phase_id null |
visibility_timeout_on_create_minutes | integer | null | Hide-on-create window |
visibility_timeout_on_release_minutes | integer | null | Hide-on-release window |
visibility_timeout_on_transition_minutes | integer | null | Hide-on-transition window |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Phase ID |
workflow_id* | UUID | Owning workflow |
name* | string | Phase name |
description* | string | null | Description |
position* | integer | Order within the workflow |
color | string | Display colorDefault: #3b82f6 |
is_terminal | boolean | Whether this is an end phaseDefault: false |
kind* | string | Processing mode: `standard`, `pull` or `exception`, fixed at creation. Every workflow has one exception phase. Pull phases are take-only: items are pulled or claimed, never assigned.Default: standard |
processing_policy | object (ProcessingPolicy) | null | Stored processing policy with defaults filled; null when the phase has none |
pull_policy | object (ProcessingPolicy) | null | Deprecated copy of processing_policy, removed in the next release |
allow_create_items | boolean | Whether items can be created directly into this phaseDefault: true |
max_assignees_per_item | integer | null | Assignee cap per item |
notify_when_assigned | boolean | null | Phase assignment-email override; null inherits the workflow default |
field_count | integer | Number of phase fields |
item_count | integer | Number of items in the phase |
timeout_minutes | number | null | Phase SLA timeout |
timeout_target_phase_id | UUID | null | Phase items move to on timeout |
return_to_origin_on_timeout* | boolean | Exceptions phase: timed-out items return to their origin phase |
visibility_timeout_on_create_minutes | integer | null | Hide-on-create window |
visibility_timeout_on_release_minutes | integer | null | Hide-on-release window |
visibility_timeout_on_transition_minutes | integer | null | Hide-on-transition window |
created_at* | datetime | Creation time |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"color": "#f97316", "timeout_minutes": 120}'Response
200 OK{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"color": "#f97316",
"timeout_minutes": 120
}/api/v1/workflows/phases/{phase_id}Delete Phase
Delete a phase. Pass force=true to delete a phase that still has items.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
force | boolean | Delete even if the phase has itemsDefault: false |
curl -X DELETE "https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901?force=false" \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/workflows/{workflow_id}/phases/reorderReorder Phases
Set the order of phases by providing the full list of phase IDs in the desired order.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
phase_ids* | array<UUID> | Phase IDs in the desired order |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Phase ID |
workflow_id* | UUID | Owning workflow |
name* | string | Phase name |
description* | string | null | Description |
position* | integer | Order within the workflow |
color | string | Display colorDefault: #3b82f6 |
is_terminal | boolean | Whether this is an end phaseDefault: false |
kind* | string | Processing mode: `standard`, `pull` or `exception`, fixed at creation. Every workflow has one exception phase. Pull phases are take-only: items are pulled or claimed, never assigned.Default: standard |
processing_policy | object (ProcessingPolicy) | null | Stored processing policy with defaults filled; null when the phase has none |
pull_policy | object (ProcessingPolicy) | null | Deprecated copy of processing_policy, removed in the next release |
allow_create_items | boolean | Whether items can be created directly into this phaseDefault: true |
max_assignees_per_item | integer | null | Assignee cap per item |
notify_when_assigned | boolean | null | Phase assignment-email override; null inherits the workflow default |
field_count | integer | Number of phase fields |
item_count | integer | Number of items in the phase |
timeout_minutes | number | null | Phase SLA timeout |
timeout_target_phase_id | UUID | null | Phase items move to on timeout |
return_to_origin_on_timeout* | boolean | Exceptions phase: timed-out items return to their origin phase |
visibility_timeout_on_create_minutes | integer | null | Hide-on-create window |
visibility_timeout_on_release_minutes | integer | null | Hide-on-release window |
visibility_timeout_on_transition_minutes | integer | null | Hide-on-transition window |
created_at* | datetime | Creation time |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/phases/reorder \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"phase_ids": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]}'Response
200 OK[
{"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "position": 0}
]/api/v1/workflows/phases/{phase_id}/eligible-assigneesList Eligible Assignees
Return principals eligible to be assigned in this phase — the intersection of items:claim grants on the phase resource and routing-group membership.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
curl "https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/eligible-assignees" \
-H "Authorization: Bearer {token}"Response
200 OK{
"principals": [
{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "principal_type": "user", "label": "Ada Lovelace"}
]
}/api/v1/workflows/phases/{phase_id}/working-hoursGet Phase Working Hours
Return the working-hours schedule used to pause SLA clocks for the phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
curl "https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/working-hours" \
-H "Authorization: Bearer {token}"Response
200 OK{
"timezone": "America/Sao_Paulo",
"schedule": {"mon": [["09:00", "18:00"]]}
}/api/v1/workflows/phases/{phase_id}/working-hoursSet Phase Working Hours
Replace the phase's working-hours schedule.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
Request Body
| Name | Type | Description |
|---|---|---|
timezone | string | IANA timezone |
schedule | object | Per-weekday list of [start, end] windows |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/working-hours \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"timezone": "America/Sao_Paulo", "schedule": {"mon": [["09:00", "18:00"]]}}'Response
200 OK{
"timezone": "America/Sao_Paulo",
"schedule": {"mon": [["09:00", "18:00"]]}
}/api/v1/workflows/phases/{phase_id}/working-hoursDelete Phase Working Hours
Clear the phase's working-hours schedule (SLA clocks run continuously).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/working-hours \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/phases/{phase_id}/timeout-rulesGet Phase Timeout Rules
Return the phase's ordered timeout rules. When an item's stay passes its deadline, the first enabled rule whose origin phases and conditions match decides the wait and the move; the phase's own timeout settings apply when none matches.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
curl "https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/timeout-rules" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "7f1c...",
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"position": 0,
"enabled": true,
"origin_phase_ids": ["3a9e..."],
"condition": null,
"timeout_minutes": 15,
"target_kind": "origin",
"target_phase_id": null,
"annotation": "fast lane back to Triage"
}
]/api/v1/workflows/phases/{phase_id}/timeout-rulesReplace Phase Timeout Rules
Replace the phase's timeout rules; list order is evaluation order. Rules with an id are kept, the rest are recreated. A phase target must be reachable by a route from this phase; return-to-origin is only valid on the Exceptions phase. A rule with timeout_minutes 0 moves the item on arrival (needs a phase target, emits no timeout event; 409 on_arrival_rules_cycle when such rules would loop). Saving re-arms stays whose automatic move was blocked or had a missing target.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
Request Body
| Name | Type | Description |
|---|---|---|
rules* | array | Up to 50 rules: {id?, enabled, origin_phase_ids?, condition?, timeout_minutes? (>= 0; 0 = on arrival), target_kind: phase|origin|none, target_phase_id?, annotation?} |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/timeout-rules \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"rules": [{"enabled": true, "origin_phase_ids": ["3a9e..."], "timeout_minutes": 15, "target_kind": "origin"}]}'Response
200 OK[
{
"id": "7f1c...",
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"position": 0,
"enabled": true,
"origin_phase_ids": ["3a9e..."],
"condition": null,
"timeout_minutes": 15,
"target_kind": "origin",
"target_phase_id": null,
"annotation": null
}
]Fields
Custom fields capture structured data on items. Fields live either on a phase or at the workflow level (phase-independent). Field types are defined by the field-types catalog; the `record` type links rows from a worksheet or view and can cascade via depends_on.
/api/v1/workflows/field-typesList Field Types
Return all available field types and their options requirements.
Bearer token required.
curl "https://platform.ergondata.ai/api/v1/workflows/field-types" \
-H "Authorization: Bearer {token}"Response
200 OK{
"field_types": [
{"type": "text", "label": "Text", "requires_options": false},
{"type": "select", "label": "Select", "requires_options": true},
{"type": "record", "label": "Record", "requires_options": true}
]
}/api/v1/workflows/workflows/{workflow_id}/fieldsList Workflow Fields
List the workflow-level (phase-independent) fields.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
for | string | null | Filter to a usage context (e.g. card, form) |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Field ID |
workflow_id | UUID | null | Owning workflow (workflow-level fields) |
phase_id | UUID | null | Owning phase (phase-level fields) |
name* | string | Field name |
field_type* | string | Field type slug |
description | string | null | Description |
required* | boolean | Whether a value is required |
is_list* | boolean | Whether the field holds multiple values |
position* | integer | Order within the phase/workflow |
show_on_card | boolean | Render on the item cardDefault: false |
options* | object | null | Field-type-specific configuration |
editable_from_phase_ids* | array<UUID> | null | Phases where the value is editable |
can_edit_value | boolean | null | Whether the caller may edit the value |
created_at* | datetime | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Priority",
"field_type": "select",
"required": false,
"is_list": false,
"position": 0,
"options": {"choices": ["low", "high"]}
}
]/api/v1/workflows/workflows/{workflow_id}/fieldsCreate Workflow Field
Create a workflow-level (phase-independent) field.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Field name |
field_type | string | Field type slug (see GET /field-types)Default: text |
description | string | null | Description |
required | boolean | Whether a value is requiredDefault: false |
is_list | boolean | Whether the field holds multiple valuesDefault: false |
show_on_card | boolean | Render on the item cardDefault: false |
options | object | null | Field-type-specific configuration. For field_type='record' it follows the record options shape and may declare depends_on cascade dependencies. A record field's editable_column_ids (a subset of display_column_ids) lists the columns items can edit; saving grants the workflow rows:edit on those the saving user can edit, and if IAM refuses that grant the save fails with 502 and nothing is saved. |
editable_from_phase_ids | array<UUID> | null | Phases where the value is editable |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Field ID |
workflow_id | UUID | null | Owning workflow (workflow-level fields) |
phase_id | UUID | null | Owning phase (phase-level fields) |
name* | string | Field name |
field_type* | string | Field type slug |
description | string | null | Description |
required* | boolean | Whether a value is required |
is_list* | boolean | Whether the field holds multiple values |
position* | integer | Order within the phase/workflow |
show_on_card | boolean | Render on the item cardDefault: false |
options* | object | null | Field-type-specific configuration |
editable_from_phase_ids* | array<UUID> | null | Phases where the value is editable |
can_edit_value | boolean | null | Whether the caller may edit the value |
created_at* | datetime | Creation time |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Priority", "field_type": "select", "options": {"choices": ["low", "high"]}}'Response
201 Created{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Priority",
"field_type": "select",
"position": 0
}/api/v1/workflows/workflows/{workflow_id}/fields/reorderReorder Workflow Fields
Set the order of workflow-level fields.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
field_ids* | array<UUID> | Field IDs in the desired order |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Field ID |
workflow_id | UUID | null | Owning workflow (workflow-level fields) |
phase_id | UUID | null | Owning phase (phase-level fields) |
name* | string | Field name |
field_type* | string | Field type slug |
description | string | null | Description |
required* | boolean | Whether a value is required |
is_list* | boolean | Whether the field holds multiple values |
position* | integer | Order within the phase/workflow |
show_on_card | boolean | Render on the item cardDefault: false |
options* | object | null | Field-type-specific configuration |
editable_from_phase_ids* | array<UUID> | null | Phases where the value is editable |
can_edit_value | boolean | null | Whether the caller may edit the value |
created_at* | datetime | Creation time |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields/reorder \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]}'Response
200 OK[
{"id": "d4e5f6a7-b8c9-0123-def0-234567890123", "position": 0}
]/api/v1/workflows/phases/{phase_id}/fieldsList Phase Fields
List the fields defined on a phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
for | string | null | Filter to a usage context (e.g. card, form) |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Field ID |
workflow_id | UUID | null | Owning workflow (workflow-level fields) |
phase_id | UUID | null | Owning phase (phase-level fields) |
name* | string | Field name |
field_type* | string | Field type slug |
description | string | null | Description |
required* | boolean | Whether a value is required |
is_list* | boolean | Whether the field holds multiple values |
position* | integer | Order within the phase/workflow |
show_on_card | boolean | Render on the item cardDefault: false |
options* | object | null | Field-type-specific configuration |
editable_from_phase_ids* | array<UUID> | null | Phases where the value is editable |
can_edit_value | boolean | null | Whether the caller may edit the value |
created_at* | datetime | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/fields" \
-H "Authorization: Bearer {token}"Response
200 OK[
{"id": "d4e5f6a7-b8c9-0123-def0-234567890123", "phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Notes", "field_type": "text", "position": 0}
]/api/v1/workflows/phases/{phase_id}/fieldsCreate Phase Field
Create a field on a phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Field name |
field_type | string | Field type slug (see GET /field-types)Default: text |
description | string | null | Description |
required | boolean | Whether a value is requiredDefault: false |
is_list | boolean | Whether the field holds multiple valuesDefault: false |
show_on_card | boolean | Render on the item cardDefault: false |
options | object | null | Field-type-specific configuration. For field_type='record' it follows the record options shape and may declare depends_on cascade dependencies. A record field's editable_column_ids (a subset of display_column_ids) lists the columns items can edit; saving grants the workflow rows:edit on those the saving user can edit, and if IAM refuses that grant the save fails with 502 and nothing is saved. |
editable_from_phase_ids | array<UUID> | null | Phases where the value is editable |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Field ID |
workflow_id | UUID | null | Owning workflow (workflow-level fields) |
phase_id | UUID | null | Owning phase (phase-level fields) |
name* | string | Field name |
field_type* | string | Field type slug |
description | string | null | Description |
required* | boolean | Whether a value is required |
is_list* | boolean | Whether the field holds multiple values |
position* | integer | Order within the phase/workflow |
show_on_card | boolean | Render on the item cardDefault: false |
options* | object | null | Field-type-specific configuration |
editable_from_phase_ids* | array<UUID> | null | Phases where the value is editable |
can_edit_value | boolean | null | Whether the caller may edit the value |
created_at* | datetime | Creation time |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/fields \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Notes", "field_type": "text"}'Response
201 Created{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Notes",
"field_type": "text",
"position": 0
}/api/v1/workflows/phases/{phase_id}/fields/reorderReorder Phase Fields
Set the order of fields on a phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
Request Body
| Name | Type | Description |
|---|---|---|
field_ids* | array<UUID> | Field IDs in the desired order |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Field ID |
workflow_id | UUID | null | Owning workflow (workflow-level fields) |
phase_id | UUID | null | Owning phase (phase-level fields) |
name* | string | Field name |
field_type* | string | Field type slug |
description | string | null | Description |
required* | boolean | Whether a value is required |
is_list* | boolean | Whether the field holds multiple values |
position* | integer | Order within the phase/workflow |
show_on_card | boolean | Render on the item cardDefault: false |
options* | object | null | Field-type-specific configuration |
editable_from_phase_ids* | array<UUID> | null | Phases where the value is editable |
can_edit_value | boolean | null | Whether the caller may edit the value |
created_at* | datetime | Creation time |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/fields/reorder \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]}'Response
200 OK[
{"id": "d4e5f6a7-b8c9-0123-def0-234567890123", "position": 0}
]/api/v1/workflows/fields/{field_id}Update Field
Update a field. The options shape is field-type specific; for field_type='record' it follows the record options shape and may declare depends_on cascade dependencies. Changing a record field's editable_column_ids grants the workflow rows:edit on the columns the saving user can edit and revokes it on the ones removed; if IAM refuses a grant the save fails with 502 and the field keeps its previous options. A record field can't be saved with options set to null (400).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
field_id* | string (UUID) | Field ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name |
field_type | string | null | New field type |
description | string | null | Description |
required | boolean | null | Whether a value is required |
is_list | boolean | null | Multi-valued |
show_on_card | boolean | null | Render on the item card |
options | object | null | Field-type-specific configuration |
editable_from_phase_ids | array<UUID> | null | Phases where the value is editable |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Field ID |
workflow_id | UUID | null | Owning workflow (workflow-level fields) |
phase_id | UUID | null | Owning phase (phase-level fields) |
name* | string | Field name |
field_type* | string | Field type slug |
description | string | null | Description |
required* | boolean | Whether a value is required |
is_list* | boolean | Whether the field holds multiple values |
position* | integer | Order within the phase/workflow |
show_on_card | boolean | Render on the item cardDefault: false |
options* | object | null | Field-type-specific configuration |
editable_from_phase_ids* | array<UUID> | null | Phases where the value is editable |
can_edit_value | boolean | null | Whether the caller may edit the value |
created_at* | datetime | Creation time |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/fields/d4e5f6a7-b8c9-0123-def0-234567890123 \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"required": true, "show_on_card": true}'Response
200 OK{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"required": true,
"show_on_card": true
}/api/v1/workflows/fields/{field_id}Delete Field
Delete a field and its stored values.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
field_id* | string (UUID) | Field ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/fields/d4e5f6a7-b8c9-0123-def0-234567890123 \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/fields/{field_id}/attachment-pipeline/schemas/generateGenerate Attachment Field Schema (Edit)
Generate an extraction schema for an existing attachment field's Buckets pipeline.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
field_id* | string (UUID) | Field ID |
Request Body
| Name | Type | Description |
|---|---|---|
(body)* | object | Pipeline generation parameters |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/fields/d4e5f6a7-b8c9-0123-def0-234567890123/attachment-pipeline/schemas/generate \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"prompt": "Extract invoice fields"}'Response
200 OK{
"schema": {"fields": [{"name": "total", "type": "number"}]}
}/api/v1/workflows/phases/{phase_id}/fields/attachment-pipeline/schemas/generateGenerate Attachment Field Schema (Phase Create)
Generate an extraction schema while creating a new attachment field on a phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
Request Body
| Name | Type | Description |
|---|---|---|
(body)* | object | Pipeline generation parameters |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/fields/attachment-pipeline/schemas/generate \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"prompt": "Extract invoice fields"}'Response
200 OK{
"schema": {"fields": [{"name": "total", "type": "number"}]}
}/api/v1/workflows/workflows/{workflow_id}/fields/attachment-pipeline/schemas/generateGenerate Attachment Field Schema (Workflow Create)
Generate an extraction schema while creating a new workflow-level attachment field.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
(body)* | object | Pipeline generation parameters |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields/attachment-pipeline/schemas/generate \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"prompt": "Extract invoice fields"}'Response
200 OK{
"schema": {"fields": [{"name": "total", "type": "number"}]}
}Field Rules
Field rules conditionally show fields based on a structured match expression. Rules are evaluated in order; each rule names the fields it reveals and (optionally) the phases it applies in.
/api/v1/workflows/workflows/{workflow_id}/field-rulesList Field Rules
List the field rules of a workflow in evaluation order.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Rule ID |
workflow_id* | UUID | Owning workflow |
name | string | null | Rule name |
match* | object | Condition expression that triggers the rule |
field_ids* | array<UUID> | Fields shown/affected when the rule matches |
phase_ids | array<UUID> | null | Phases the rule applies in (null = all) |
position* | integer | Evaluation order |
created_at* | datetime | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/field-rules" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "44445555-6666-7777-8888-9999aaaabbbb",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Show escalation fields",
"match": {"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "operator": "eq", "value": "high"},
"field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"],
"phase_ids": null,
"position": 0,
"created_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/workflows/{workflow_id}/field-rulesCreate Field Rule
Create a field rule.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
match* | object | Condition expression that triggers the rule |
field_ids* | array<UUID> | Fields revealed when the rule matches |
name | string | null | Rule name |
phase_ids | array<UUID> | null | Phases the rule applies in (null = all) |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Rule ID |
workflow_id* | UUID | Owning workflow |
name | string | null | Rule name |
match* | object | Condition expression that triggers the rule |
field_ids* | array<UUID> | Fields shown/affected when the rule matches |
phase_ids | array<UUID> | null | Phases the rule applies in (null = all) |
position* | integer | Evaluation order |
created_at* | datetime | Creation time |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/field-rules \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Escalation", "match": {"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "operator": "eq", "value": "high"}, "field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]}'Response
201 Created{
"id": "44445555-6666-7777-8888-9999aaaabbbb",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Escalation",
"field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"],
"position": 0
}/api/v1/workflows/workflows/{workflow_id}/field-rules/reorderReorder Field Rules
Set the evaluation order of field rules.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
rule_ids* | array<UUID> | Rule IDs in the desired order |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Rule ID |
workflow_id* | UUID | Owning workflow |
name | string | null | Rule name |
match* | object | Condition expression that triggers the rule |
field_ids* | array<UUID> | Fields shown/affected when the rule matches |
phase_ids | array<UUID> | null | Phases the rule applies in (null = all) |
position* | integer | Evaluation order |
created_at* | datetime | Creation time |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/field-rules/reorder \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"rule_ids": ["44445555-6666-7777-8888-9999aaaabbbb"]}'Response
200 OK[
{"id": "44445555-6666-7777-8888-9999aaaabbbb", "position": 0}
]/api/v1/workflows/field-rules/{rule_id}Update Field Rule
Update a field rule's name, match expression, fields, or phases.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
rule_id* | string (UUID) | Rule ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name |
match | object | null | New match expression |
field_ids | array<UUID> | null | Fields revealed |
phase_ids | array<UUID> | null | Phases the rule applies in |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Rule ID |
workflow_id* | UUID | Owning workflow |
name | string | null | Rule name |
match* | object | Condition expression that triggers the rule |
field_ids* | array<UUID> | Fields shown/affected when the rule matches |
phase_ids | array<UUID> | null | Phases the rule applies in (null = all) |
position* | integer | Evaluation order |
created_at* | datetime | Creation time |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/field-rules/44445555-6666-7777-8888-9999aaaabbbb \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "High-priority fields"}'Response
200 OK{
"id": "44445555-6666-7777-8888-9999aaaabbbb",
"name": "High-priority fields"
}/api/v1/workflows/field-rules/{rule_id}Delete Field Rule
Delete a field rule.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
rule_id* | string (UUID) | Rule ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/field-rules/44445555-6666-7777-8888-9999aaaabbbb \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No ContentCondition Fields
Metadata endpoints that enumerate the attributes available as sources when building condition/predicate expressions (e.g. for routing, field rules, and filters) at the workflow, phase, field, and item level.
/api/v1/workflows/workflows/{workflow_id}/condition-fieldsWorkflow Condition Fields
Return conditionable workflow attributes (source key `workflow`).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/condition-fields" \
-H "Authorization: Bearer {token}"Response
200 OK[
{"key": "name", "label": "Workflow name", "type": "text", "source": "workflow"}
]/api/v1/workflows/phases/{phase_id}/condition-fieldsPhase Condition Fields
Return conditionable phase attributes (source key `phase`).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
curl "https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/condition-fields" \
-H "Authorization: Bearer {token}"Response
200 OK[
{"key": "name", "label": "Phase name", "type": "text", "source": "phase"}
]/api/v1/workflows/fields/{field_id}/condition-fieldsField Condition Fields
Return phase-field metadata attributes for a given field.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
field_id* | string (UUID) | Field ID |
curl "https://platform.ergondata.ai/api/v1/workflows/fields/d4e5f6a7-b8c9-0123-def0-234567890123/condition-fields" \
-H "Authorization: Bearer {token}"Response
200 OK[
{"key": "value", "label": "Priority", "type": "select"}
]/api/v1/workflows/items/{item_id}/condition-fieldsItem Condition Fields
Return item attributes plus per-bound-field rows for field_values.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
curl "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/condition-fields" \
-H "Authorization: Bearer {token}"Response
200 OK[
{"key": "title", "label": "Title", "type": "text", "source": "item"}
]Records
Record fields link rows from a worksheet or view. These endpoints power typeahead search, single-row resolution, and column discovery for a record-type field. Cascade dependencies are passed via the `deps` query parameter.
/api/v1/workflows/workflows/{workflow_id}/fields/{field_id}/records/columnsList Record Columns
List the columns of the worksheet or view linked to a record field.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
field_id* | string (UUID) | Record field ID |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields/d4e5f6a7-b8c9-0123-def0-234567890123/records/columns" \
-H "Authorization: Bearer {token}"Response
200 OK{
"columns": [
{"id": "col-uuid", "name": "Email", "type": "text"}
]
}/api/v1/workflows/workflows/{workflow_id}/fields/{field_id}/records/searchSearch Records
Typeahead search for rows in the worksheet or view linked to a record field.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
field_id* | string (UUID) | Record field ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
q | string | Search text |
limit | integer | Max resultsDefault: 20 |
deps | string | null | JSON object mapping dependency source field IDs to their current value |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields/d4e5f6a7-b8c9-0123-def0-234567890123/records/search?q=acme&limit=20" \
-H "Authorization: Bearer {token}"Response
200 OK{
"rows": [
{"row_id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff", "label": "Acme Inc.", "values": {"email": "ops@acme.test"}}
]
}/api/v1/workflows/workflows/{workflow_id}/fields/{field_id}/records/{row_id}Get Record
Resolve a single row from the linked worksheet or view for card display. cell_values holds only the field's display_column_ids (every visible column when none are set); a worksheet_ref cell carries its label in value and the referenced row ID in raw_value. columns describes each display column (id, name, field_type, is_list, required, choices, allow_multiple) so the card can render and edit it.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
field_id* | string (UUID) | Record field ID |
row_id* | string | Row ID |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields/d4e5f6a7-b8c9-0123-def0-234567890123/records/88889999-aaaa-bbbb-cccc-ddddeeeeffff" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff",
"worksheet_id": "9999aaaa-bbbb-cccc-dddd-eeeeffff0000",
"cell_values": [
{"column_id": "col-email", "value": "ops@acme.test"},
{"column_id": "col-company", "value": "Acme Inc.", "raw_value": "row-uuid"}
],
"columns": [
{"id": "col-email", "name": "Email", "field_type": "email", "is_list": false, "required": false, "choices": null, "allow_multiple": false},
{"id": "col-company", "name": "Company", "field_type": "worksheet_ref", "is_list": false, "required": false, "choices": null, "allow_multiple": false}
]
}/api/v1/workflows/items/{item_id}/fields/{field_id}/records/{row_id}Update Record Cells
Edit cells of the worksheet row an item links through a record field. Requires workflows:workflows:items:edit on the field and on the item's current phase. Only the field's editable_column_ids can be written, the field must be editable from the item's current phase, and row_id must be the row the item links. The item must also pass the content-edit gate and not be in visibility cooldown (409). The write runs as the workflow, so worksheets validation applies (400 or 422 for an invalid value, 409 for a duplicate unique value, 413 for a value that is too large, 422 for an edit that would move the row out of the field's view). Logs workflows.items.record_cells_updated. If the row cannot be read back after the write, cell_values is null: reload the row.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
field_id* | string (UUID) | Record field ID |
row_id* | string (UUID) | Linked row ID |
Request Body
| Name | Type | Description |
|---|---|---|
cell_values* | array | Cells to write, at most 200 and one per column: column_id (one of the field's editable_column_ids) and value. A reference cell takes the referenced row ID, or a list of row IDs when the column allows several. |
curl -X PATCH "https://platform.ergondata.ai/api/v1/workflows/items/{item_id}/fields/d4e5f6a7-b8c9-0123-def0-234567890123/records/88889999-aaaa-bbbb-cccc-ddddeeeeffff" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"cell_values": [{"column_id": "col-uuid", "value": "ops@acme.test"}]}'Response
200 OK{
"id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff",
"cell_values": [{"column_id": "col-uuid", "value": "ops@acme.test"}]
}/api/v1/workflows/workflows/{workflow_id}/fields/{field_id}/records/columns/{column_id}/optionsList Record Reference Options
Typeahead the rows an editable reference column of a record field can point at. column_id must be a worksheet_ref column in the field's editable_column_ids.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
field_id* | string (UUID) | Record field ID |
column_id* | string (UUID) | Reference column ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
q | string | Search text |
limit | integer | Max results (1-100)Default: 20 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array | row_id and display_value |
has_more* | boolean | More rows match |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields/d4e5f6a7-b8c9-0123-def0-234567890123/records/columns/col-uuid/options?q=sp" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [{"row_id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff", "display_value": "São Paulo"}],
"has_more": false
}Routing
Routes define the allowed moves between phases. A route may carry the current assignment, require certain fields before moving, and (for cross-workflow routing) target a phase in a different workflow. Workflow-backed external conversations use this same item-routing contract for escalation: routing to a human-bound phase activates its normal assignment behavior.
/api/v1/workflows/workflows/{workflow_id}/routesList Routes
List the routes (allowed phase transitions) for a workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Route ID |
workflow_id* | UUID | Owning workflow |
from_phase_id* | UUID | Source phase |
from_phase_name* | string | Source phase name |
to_phase_id* | UUID | Target phase |
to_phase_name* | string | Target phase name |
to_workflow_id | UUID | null | Target workflow (set for cross-workflow routes) |
to_workflow_name | string | null | Target workflow name |
cross_workflow | boolean | Whether the route crosses workflowsDefault: false |
carry_assignment | boolean | Carry the current assignment across the moveDefault: true |
required_field_ids | array<UUID> | Fields that must be filled before routing |
max_passes | integer | null | Per-route limit on entries into the target phase over this route; the phase's own max_passes applies too |
visibility_timeout_on_transition_minutes | integer | null | Arrival cooldown over this route; null inherits the target phase's |
is_system | boolean | Platform-managed route to or from the Exceptions phase; cannot be deletedDefault: false |
annotation | string | null | Free-text annotation |
created_at* | datetime | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/routes" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"from_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"to_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"cross_workflow": false,
"carry_assignment": true,
"required_field_ids": []
}
]/api/v1/workflows/workflows/{workflow_id}/routesCreate Route
Create a route between two phases.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
from_phase_id* | UUID | Source phase |
to_phase_id* | UUID | Target phase |
carry_assignment | boolean | Carry the current assignment across the moveDefault: true |
required_field_ids | array<UUID> | Fields that must be filled before routing |
max_passes | integer | null | Entries into the target phase allowed per item through this route (1..1000), counted only over this route. The target phase's max_passes still counts every entry; both apply. Over either limit, a person, or anyone moving an item out of Exceptions, gets 409 max_passes_exceeded; any other caller (API key, agent, automation, on-arrival rule) and timeouts from any other phase send the item to Exceptions instead |
visibility_timeout_on_transition_minutes | integer | null | Arrival cooldown over this route (1..10080), replacing the target phase's; null inherits it. Editable on the system route out of Exceptions |
annotation | string | null | Free-text annotation |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Route ID |
workflow_id* | UUID | Owning workflow |
from_phase_id* | UUID | Source phase |
from_phase_name* | string | Source phase name |
to_phase_id* | UUID | Target phase |
to_phase_name* | string | Target phase name |
to_workflow_id | UUID | null | Target workflow (set for cross-workflow routes) |
to_workflow_name | string | null | Target workflow name |
cross_workflow | boolean | Whether the route crosses workflowsDefault: false |
carry_assignment | boolean | Carry the current assignment across the moveDefault: true |
required_field_ids | array<UUID> | Fields that must be filled before routing |
max_passes | integer | null | Per-route limit on entries into the target phase over this route; the phase's own max_passes applies too |
visibility_timeout_on_transition_minutes | integer | null | Arrival cooldown over this route; null inherits the target phase's |
is_system | boolean | Platform-managed route to or from the Exceptions phase; cannot be deletedDefault: false |
annotation | string | null | Free-text annotation |
created_at* | datetime | Creation time |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/routes \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"from_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "to_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"}'Response
201 Created{
"id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"from_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"to_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"carry_assignment": true
}/api/v1/workflows/routes/{route_id}Update Route
Update a route's assignment-carry behaviour, required fields, max passes, or annotation. Routes have no trigger (sending one is 422): to move items on entry, add a timeout rule with timeout_minutes 0 to the source phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
route_id* | string (UUID) | Route ID |
Request Body
| Name | Type | Description |
|---|---|---|
carry_assignment | boolean | null | Carry assignment across the move |
required_field_ids | array<UUID> | null | Fields that must be filled before routing |
max_passes | integer | null | Entries into the target phase allowed per item through this route (1..1000), counted only over this route. The target phase's max_passes still counts every entry; both apply. Over either limit, a person, or anyone moving an item out of Exceptions, gets 409 max_passes_exceeded; any other caller (API key, agent, automation, on-arrival rule) and timeouts from any other phase send the item to Exceptions instead |
visibility_timeout_on_transition_minutes | integer | null | Arrival cooldown over this route (1..10080), replacing the target phase's; null inherits it. Editable on the system route out of Exceptions |
annotation | string | null | Free-text annotation |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Route ID |
workflow_id* | UUID | Owning workflow |
from_phase_id* | UUID | Source phase |
from_phase_name* | string | Source phase name |
to_phase_id* | UUID | Target phase |
to_phase_name* | string | Target phase name |
to_workflow_id | UUID | null | Target workflow (set for cross-workflow routes) |
to_workflow_name | string | null | Target workflow name |
cross_workflow | boolean | Whether the route crosses workflowsDefault: false |
carry_assignment | boolean | Carry the current assignment across the moveDefault: true |
required_field_ids | array<UUID> | Fields that must be filled before routing |
max_passes | integer | null | Per-route limit on entries into the target phase over this route; the phase's own max_passes applies too |
visibility_timeout_on_transition_minutes | integer | null | Arrival cooldown over this route; null inherits the target phase's |
is_system | boolean | Platform-managed route to or from the Exceptions phase; cannot be deletedDefault: false |
annotation | string | null | Free-text annotation |
created_at* | datetime | Creation time |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/routes/e5f6a7b8-c9d0-1234-ef01-345678901234 \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"carry_assignment": false}'Response
200 OK{
"id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
"carry_assignment": false
}/api/v1/workflows/routes/{route_id}Delete Route
Delete a route.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
route_id* | string (UUID) | Route ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/routes/e5f6a7b8-c9d0-1234-ef01-345678901234 \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No ContentItems
Read, update, and delete workflow items, plus the per-item actions that drive the workflow page: claim/release, assign to a principal or routing group, route between phases, and the read-only helpers (claimability, assignable principals, messaging options, events) and the cross-workflow granted-items picker.
/api/v1/workflows/items/{item_id}Get Item
Return a single item with its current phase, assignees, card fields, and field values.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}/api/v1/workflows/items/{item_id}Update Item
Update an item's title, description, field values, and timeout settings. The caller still needs the item edit permission. Shared items stay editable after IAM even when another principal has claimed them. Owned items require a claim first, then an assignee seat. Creator identity does not grant extra edit rights and does not allow route, delete, release, assign, or reassign actions.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
title | string | null | New title (1-500 chars) |
description | string | null | New description |
field_values | object | null | Map of field name → new value. Keys are field names (not ids or labels); an unknown name is dropped and returned in ignored_fields as unknown_field (with a suggestion), and known fields that cannot be stored here are returned in ignored_fields too. Each value may serialize to at most 2 MB; a larger value fails the request with 413 and nothing is written. |
target_phase_id | string (UUID) | null | Phase context for field validation |
timeout_minutes | number | null | Per-phase timeout |
global_timeout_minutes | number | null | Global timeout |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Hides the item for this many minutes on create, once. Use defer or the phase cooldown instead; 0 means no cooldown |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Hides the item for this many minutes on the next release, once. Use defer or the phase cooldown instead; 0 means no cooldown |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Hides the item for this many minutes on the next phase move, once. Use defer or the phase cooldown instead; 0 means no cooldown |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X PATCH "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"title": "Refund request #4821 (escalated)", "field_values": {"Priority": "High"}}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}/api/v1/workflows/items/{item_id}Delete Item
Permanently delete an item.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
curl -X DELETE "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012" \
-H "Authorization: Bearer {token}"Response
204 No Content/api/v1/workflows/items/{item_id}/claimClaim Item
Claim the item for the calling principal, taking an assignee seat in the current phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/claim" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}/api/v1/workflows/phases/{phase_id}/items/pullPull Items
Atomically claim up to max available items of a phase for the caller. Concurrent pulls never return the same item. Send the optional X-Ergon-Consumer-Id header to identify the worker process: the claim is fenced to that consumer and expires after the phase claim timeout unless extended (never, when the phase sets none). An empty items list is a normal response.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
Request Body
| Name | Type | Description |
|---|---|---|
max | integer | Most items to claim (1-100)Default: 10 |
wait_seconds | integer | Wait up to this many seconds (0-30) for an item when none is availableDefault: 0 |
filter | object | null | Field predicate the items must match: {logic: 'all' | 'any', filters: [{field_id, operator, value}]}, at most 30 filters |
workflow_id | string (UUID) | null | Owning workflow; rejected with 400 when it does not own phase_id |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | ItemResponse[] | Claimed items, each with claim and processing blocks |
total* | integer | Number of items claimed |
claim_expires_at | datetime | null | When the claims expire unless extended |
consumer_id | string | null | Echo of X-Ergon-Consumer-Id |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/items/pull" \
-H "Authorization: Bearer {token}" \
-H "X-Ergon-Consumer-Id: invoice-bot-1" \
-H "Content-Type: application/json" \
-d '{"max": 5, "wait_seconds": 20}'Response
200 OK{
"items": [{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}],
"total": 1,
"claim_expires_at": "2026-01-15T10:35:00Z",
"consumer_id": "invoice-bot-1"
}/api/v1/workflows/items/{item_id}/extend-claimExtend Claim
Push back the claim expiry of an item the caller holds. Without seconds on a phase that sets no claim timeout, the call is a no-op and the claim keeps no expiry. Returns 409 claim_mismatch when another consumer (X-Ergon-Consumer-Id) holds the claim.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
seconds | integer | null | New claim length from now (10-86400); defaults to the phase claim timeout |
workflow_id | string (UUID) | null | Owning workflow; validated against item_id |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/extend-claim" \
-H "Authorization: Bearer {token}" \
-H "X-Ergon-Consumer-Id: invoice-bot-1" \
-H "Content-Type: application/json" \
-d '{"seconds": 600}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}/api/v1/workflows/items/{item_id}/failFail Item
Record a failed attempt on an item the caller holds. The item returns to its phase after the retry delay. When the stay has used the last attempt its phase policy allows, the platform moves the item to Exceptions instead (source system, reason attempt_limit_reached). A hold that no claim counted (assign, group auto-assign, a seat carried by a route) counts as an attempt when it fails or defers.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
reason* | string | Why the attempt failed (1-4000 characters) |
details | string | null | Longer diagnostic text |
delay_seconds | integer | null | Retry delay (0-604800); defaults to the phase policy's retry delay, 0 when the phase has none |
workflow_id | string (UUID) | null | Owning workflow; validated against item_id |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/fail" \
-H "Authorization: Bearer {token}" \
-H "X-Ergon-Consumer-Id: invoice-bot-1" \
-H "Content-Type: application/json" \
-d '{"reason": "upstream returned 503"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}/api/v1/workflows/items/{item_id}/deferDefer Item
Hand an item the caller holds back to its phase, hidden for delay_seconds. A phase with defer_max_seconds rejects longer delays with 400 defer_exceeds_max. When the stay has used its last allowed attempt, the platform moves the item to Exceptions instead (source system, reason attempt_limit_reached); workflows.items.deferred carries outcome deferred or moved_to_exceptions.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
delay_seconds* | integer | Seconds the item stays hidden (1-604800) |
reason | string | null | Why the item was deferred |
workflow_id | string (UUID) | null | Owning workflow; validated against item_id |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/defer" \
-H "Authorization: Bearer {token}" \
-H "X-Ergon-Consumer-Id: invoice-bot-1" \
-H "Content-Type: application/json" \
-d '{"delay_seconds": 3600, "reason": "waiting on customer"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}/api/v1/workflows/items/{item_id}/completeComplete Item
Mark the current stay of a held item as done and follow the phase's declared route (system routes into Exceptions do not count; the routes out of Exceptions back to each phase do). With one route the item moves along it; with several, target_phase_id picks one (400 ambiguous_route without it, 400 route_not_declared for a phase that is not a route). The move runs the exit gate, landing gate and max_passes like a route. With no route the item stays: pull, claimable lists and claimability skip the completed stay, and claim or assign return 409 stay_completed until it re-enters the phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
reason | string | null | Optional note stored on the completed event |
target_phase_id | string (UUID) | null | Destination when several declared routes leave the phase; must be one of them |
workflow_id | string (UUID) | null | Owning workflow; validated against item_id |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
diverted | ItemDiversion | null | Set when max_passes sent the item to Exceptions instead of the requested phase (current_phase_id is then the Exceptions phase); null otherwise |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/complete" \
-H "Authorization: Bearer {token}" \
-H "X-Ergon-Consumer-Id: invoice-bot-1" \
-H "Content-Type: application/json" \
-d '{}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"],
"diverted": null
}/api/v1/workflows/items/{item_id}/releaseRelease Item
Remove one assignee seat. Pass principal_id to remove that specific assignee; omit it to release the caller's own seat. A non-holder must provide principal_id. Remaining assignees stay attached; only removing the final seat emits workflows.items.released. A full release hides the item for the phase release cooldown. On a phase with max_attempts, a full release of a stay that has used its last attempt moves the item to Exceptions instead (source system, reason attempt_limit_reached).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_id | string (UUID) | null | Specific assignee to remove; omit for self-release |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/release" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}/api/v1/workflows/items/{item_id}/clear-cooldownClear Item Cooldown
Make a hidden item visible now by clearing visible_after (and processing.next_visible_at). Requires workflows:workflows:items:assign on the workflow. Assignees, attempt/defer/fail counters and per-item visibility timeouts are unchanged. Returns the item unchanged, without an event, when it is not in cooldown; otherwise emits workflows.items.cooldown_cleared.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
workflow_id | string (UUID) | Owning workflow; validated against item_id |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/clear-cooldown" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}/api/v1/workflows/items/{item_id}/assignAssign Item
Assign an eligible principal. Set replace_existing for an atomic exactly-one-responder handoff. Pull phases are take-only and return 400 pull_phase_no_assign.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_id* | string (UUID) | Principal to assign |
replace_existing | boolean | Replace all current assignee seats atomically (default false) |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/assign" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}/api/v1/workflows/items/{item_id}/assign-groupAssign Item Group
Assign the item to a routing group, distributing it to that group's members. Returns 400 pull_phase_no_assign on a pull phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
group_id* | string (UUID) | Routing group to assign |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/assign-group" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"group_id": "a7b8c9d0-e1f2-3456-0123-567890123456"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}/api/v1/workflows/items/{item_id}/routeRoute Item
Move the item to a target phase following the workflow's transition graph. Over the target's max_passes, a person (sign-in token or member principal), or anyone moving an item out of Exceptions, gets 409 max_passes_exceeded; any other caller (API key, agent, automation) has the item moved to Exceptions instead and gets 200 with diverted set.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
to_phase_id* | string (UUID) | Destination phase |
delay_seconds | integer | null | Keep the item hidden this long after the move (0..604800), if longer than the arrival cooldown. Capped by the destination's defer_max_seconds (400 defer_exceeds_max); not stored on the item |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
diverted | ItemDiversion | null | Set when max_passes sent the item to Exceptions instead of the requested phase (current_phase_id is then the Exceptions phase); null otherwise |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/route" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"to_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"],
"diverted": null
}/api/v1/workflows/items/{item_id}/route-to-exceptionRoute Item To Exception Phase
Move the item into the workflow's built-in exception phase. reason is required. The caller does not send a phase id. The source exit gate and the destination required-field gate are skipped; permission and assignee checks still apply.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
reason* | string | Why the item entered the exception phase |
details | string | Optional longer note |
workflow_id | string (UUID) | Owning workflow. Required for caller-authorized app tool calls. |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
current_phase_id* | string (UUID) | Current phase |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | string (UUID) | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_by_label | string | null | IAM-resolved display label for created_by. Null when the item has no creator, or when IAM cannot resolve the creating user to a principal in this company. Render this, never created_by as a raw UUID. |
created_by_avatar_url | string | null | Avatar for the resolved creator; null when IAM omits one |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | string (UUID) | null | Primary assignee principal |
assigned_group_id | string (UUID) | null | Assigned routing group |
assigned_at | datetime | null | When the item was assigned |
released_at | datetime | null | When the item was last released |
assignees | array<AssigneeRef> | Multi-assignee seatsDefault: [] |
card_fields | array<CardField> | show_on_card fields rendered as tagsDefault: [] |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Per-phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | When the global timeout clock started |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
visible_after | datetime | null | Item hidden until this timestamp |
visible_field_ids | array<string> | null | Field IDs the caller may see |
ignored_fields | array<{name, reason, suggestion?}> | null | Set only by a create or update that sent field_values: submitted fields that were not stored. reason is unknown_field (no field of the workflow has that name; suggestion carries the likely field name), not_editable_here or hidden_by_rule |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/route-to-exception" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"reason": "Missing document"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer asked for a refund on order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_by_label": "ada@example.com",
"created_by_avatar_url": null,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_at": "2026-06-02T09:30:00Z",
"assigned_via_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_primary": true
}
],
"card_fields": [
{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Priority",
"field_type": "select",
"is_list": false,
"description": null,
"values": [{"value": "High", "bg": "#fee2e2", "text": "#991b1b"}]
}
],
"field_values": [
{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Priority", "value": "High"}
],
"phase_has_assignment_group": true,
"timeout_minutes": 120,
"global_timeout_minutes": 1440,
"global_clock_started_at": "2026-06-01T12:00:00Z",
"visible_field_ids": ["d4e5f6a7-b8c9-0123-def0-234567890123"]
}/api/v1/workflows/items/{item_id}/claimabilityGet Item Claimability
Return whether the calling principal can claim the item right now. Drives the Claim button: a stable code is returned when ineligible so the UI can map it to a reason-specific message.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
claimable* | boolean | Whether the caller can claim now |
group_id | string (UUID) | Routing group via which the item is claimable (when claimable) |
code | string | Stable reason enum when not claimable |
detail | object | Extra context for the ineligibility reason |
curl "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/claimability" \
-H "Authorization: Bearer {token}"Response
200 OK{
"claimable": true,
"group_id": "a7b8c9d0-e1f2-3456-0123-567890123456"
}/api/v1/workflows/items/{item_id}/assignable-principalsList Item Assignable Principals
Principals allowed as assign targets from the workflow context. Includes direct workflow/phase claim-holders plus principals who can claim through any saved view containing the item. Matching assignment-group bindings still narrow both pools.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
(array)* | array<EligiblePrincipal> | Eligible assign targets |
curl "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/assignable-principals" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_type": "user",
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"label": "Ada Lovelace",
"display_name": "Ada Lovelace",
"avatar_url": null
}
]/api/v1/workflows/items/{item_id}/form-contextGet Item Form Context
Return the item, its current phase and workflow fields, applicable field rules, and resolved record labels in one permission-filtered response. Use this to render or reason about the complete current item form without stitching together multiple reads.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
item* | ItemResponse | Current item and its field values |
phase_fields* | array<FieldResponse> | Visible fields owned by the current phase |
workflow_fields* | array<FieldResponse> | Visible workflow-level fields |
field_rules* | array<FieldRuleResponse> | Field visibility and editability rules the caller may view |
record_labels* | object | Field ID to selected row ID to resolved display label |
curl "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/form-context" \
-H "Authorization: Bearer {token}"Response
200 OK{
"item": {"id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "title": "Refund request #4821", "field_values": []},
"phase_fields": [],
"workflow_fields": [],
"field_rules": [],
"record_labels": {}
}/api/v1/workflows/items/{item_id}/messaging-optionsGet Item Messaging Options
Per-item outbound messaging options for the support-pane composer. Derives the channel addresses bound to the item's current-phase routing groups and enriches them with channel metadata. Empty lists are a valid response.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
workflow_id* | string (UUID) | Owning workflow |
folder_id* | string (UUID) | Owning folder |
company_id* | string (UUID) | Organization ID |
phase_id* | string (UUID) | Current phase |
addresses | array<MessagingOptionAddress> | Sendable channel addressesDefault: [] |
allowed_address_ids | array<string> | IDs of permitted addressesDefault: [] |
allowed_channel_types | array<string> | Permitted channel typesDefault: [] |
curl "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/messaging-options" \
-H "Authorization: Bearer {token}"Response
200 OK{
"item_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"folder_id": "01234567-89ab-cdef-0123-456789abcdef",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"addresses": [
{
"id": "11112222-3333-4444-5555-666677778888",
"channel_type": "email",
"address": "support@acme.example",
"display_name": "Acme Support",
"direction": "outbound",
"status": "active"
}
],
"allowed_address_ids": ["11112222-3333-4444-5555-666677778888"],
"allowed_channel_types": ["email"]
}/api/v1/workflows/items/{item_id}/eventsList Events
Return the item's activity/event history, newest first, with pagination. Pass view_id when loading an item through a saved view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
view_id | string (UUID) | Saved view used to authorize activity access instead of the workflow phase |
limit | integer | Page size (1-500)Default: 50 |
offset | integer | Offset for paginationDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<object> | Page of events |
total | integer | Total matching events |
limit | integer | Page size |
offset | integer | Page offset |
curl "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/events?limit=50&offset=0" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "22223333-4444-5555-6666-777788889999",
"event_type": "item.routed",
"created_at": "2026-06-02T09:30:00Z",
"actor_label": "Ada Lovelace",
"actor_type": "user",
"data": {"from_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "to_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"}
}
],
"total": 1,
"limit": 50,
"offset": 0
}/api/v1/workflows/items/grantedList Granted Items
Return items inside workflows granted to a service, for the cascading scope picker's workflow → phase → item leg. Optionally narrow to a specific workflow and/or phase.
Bearer token required.
Query Parameters
| Name | Type | Description |
|---|---|---|
service* | string | Consumer service the grant targets |
resource_id | string | null | Optional resource filter |
workflow_id | string | null | Narrow to a single granted workflow |
phase_id | string | null | Narrow to a single phase |
Response Fields
| Name | Type | Description |
|---|---|---|
(array)* | array<GrantedItemResponse> | Items in granted workflows |
curl "https://platform.ergondata.ai/api/v1/workflows/items/granted?service=automations&workflow_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"title": "Refund request #4821"
}
]Item Exports
Choose authorized columns and queue large CSV/XLSX exports from workflow Tables or saved-view Tables. The export applies the current search, filters, and sort when creating a job. Table fields can be exported as compact raw JSON or mapped schema columns. Mapped columns expand each Table row, repeat item values, and add Table Field/Table Row context; multiple Tables append their rows independently instead of producing a Cartesian product. JSON fields stay as compact valid JSON and multi-select fields are comma-separated. Row and cell limits and row_count use the expanded output. Available data includes the searchable UI ID (for example #5A601473), full UUID, item details, caller-visible custom fields, and permission-filtered parent/child metadata; cross-tenant relations are never included. Child relationship columns include at most 100 children per item and end with a [+N more] marker when additional children exist. Deleting a workflow or saved view hard-deletes remaining non-expired artifacts for that tenant; already-expired files were removed by the retention sweep.
/api/v1/workflows/workflows/{workflow_id}/item-exports/columnsList Workflow Item Export Columns
Return authorized workflow item columns without querying item rows.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | UUID | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<ItemExportColumn> | Ordered authorized columns available for selection |
total* | integer | Number of available columns |
curl https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/item-exports/columns -H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{"key":"item_code","label":"Item ID","field_id":null,"field_type":null,"is_list":null},
{"key":"title","label":"Title","field_id":null,"field_type":null,"is_list":null},
{"key":"field:11111111-2222-3333-4444-555555555555:sku","label":"Line Items — SKU","field_id":"11111111-2222-3333-4444-555555555555","field_type":"object","is_list":true,"table_subfield_key":"sku","table_field_name":"Line Items"}
],
"total": 3
}/api/v1/workflows/workflows/{workflow_id}/item-exports/columnsList Populated Workflow Export Columns
Return authorized columns that contain data for the submitted item query snapshot.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | UUID | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
query | ItemQuery | Current filters, search, assignee, and sort used to keep only columns with matching data. |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<ItemExportColumn> | Ordered authorized columns available for selection |
total* | integer | Number of available columns |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/item-exports/columns -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"query":{"search":"Acme"}}'Response
200 OK{
"items": [
{"key":"item_code","label":"Item ID","field_id":null,"field_type":null,"is_list":null},
{"key":"title","label":"Title","field_id":null,"field_type":null,"is_list":null},
{"key":"field:11111111-2222-3333-4444-555555555555:sku","label":"Line Items — SKU","field_id":"11111111-2222-3333-4444-555555555555","field_type":"object","is_list":true,"table_subfield_key":"sku","table_field_name":"Line Items"}
],
"total": 3
}/api/v1/workflows/workflows/{workflow_id}/item-exportsCreate Workflow Item Export
Queue an export of filtered workflow items.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | UUID | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
output_format* | string | csv or xlsx |
query | ItemQuery | Current filters, search, assignee, and sort. Pagination is ignored. |
column_keys | array<string> | 1–1000 unique keys returned by the columns endpoint, in the requested output order. Table schema columns use field:<field_id>:<schema_key>. Omit to export every authorized column with raw Table JSON. |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Export job ID |
status* | string | queued, running, succeeded, empty, failed, cancelled, or expired |
progress* | integer | Completion percentage |
row_count* | integer | Rows written so far |
byte_count* | integer | Final artifact size |
filename* | string | null | Workflow slug plus UTC export timestamp |
error_message* | string | null | Bounded failure detail |
expires_at* | datetime | null | Retention deadline, set when the job reaches a terminal state |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/item-exports -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"output_format":"xlsx","query":{"search":"Acme","sort":"updated_at","sort_dir":"desc"}}'Response
202 Accepted{
"id": "12345678-abcd-4321-abcd-1234567890ab",
"company_id": "00000000-0000-0000-0000-000000000001",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"view_id": null,
"source_type": "workflow",
"output_format": "xlsx",
"status": "running",
"progress": 42,
"row_count": 420,
"byte_count": 0,
"filename": null,
"error_message": null,
"created_at": "2026-09-09T17:00:00Z",
"started_at": "2026-09-09T17:00:01Z",
"finished_at": null,
"expires_at": null,
"cancelled_at": null
}/api/v1/workflows/workflows/{workflow_id}/item-exports/{job_id}Get Workflow Item Export
Poll requester-owned export progress.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | UUID | Workflow ID |
job_id* | UUID | Export job ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Export job ID |
status* | string | queued, running, succeeded, empty, failed, cancelled, or expired |
progress* | integer | Completion percentage |
row_count* | integer | Rows written so far |
byte_count* | integer | Final artifact size |
filename* | string | null | Workflow slug plus UTC export timestamp |
error_message* | string | null | Bounded failure detail |
expires_at* | datetime | null | Retention deadline, set when the job reaches a terminal state |
curl https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/item-exports/12345678-abcd-4321-abcd-1234567890ab -H "Authorization: Bearer {token}"Response
200 OK{
"id": "12345678-abcd-4321-abcd-1234567890ab",
"company_id": "00000000-0000-0000-0000-000000000001",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"view_id": null,
"source_type": "workflow",
"output_format": "xlsx",
"status": "running",
"progress": 42,
"row_count": 420,
"byte_count": 0,
"filename": null,
"error_message": null,
"created_at": "2026-09-09T17:00:00Z",
"started_at": "2026-09-09T17:00:01Z",
"finished_at": null,
"expires_at": null,
"cancelled_at": null
}/api/v1/workflows/workflows/{workflow_id}/item-exports/{job_id}/cancelCancel Workflow Item Export
Cancel a queued or running requester-owned export.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | UUID | Workflow ID |
job_id* | UUID | Export job ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Export job ID |
status* | string | queued, running, succeeded, empty, failed, cancelled, or expired |
progress* | integer | Completion percentage |
row_count* | integer | Rows written so far |
byte_count* | integer | Final artifact size |
filename* | string | null | Workflow slug plus UTC export timestamp |
error_message* | string | null | Bounded failure detail |
expires_at* | datetime | null | Retention deadline, set when the job reaches a terminal state |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/item-exports/12345678-abcd-4321-abcd-1234567890ab/cancel -H "Authorization: Bearer {token}"Response
200 OK{
"id": "12345678-abcd-4321-abcd-1234567890ab",
"company_id": "00000000-0000-0000-0000-000000000001",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"view_id": null,
"source_type": "workflow",
"output_format": "xlsx",
"status": "cancelled",
"progress": 42,
"row_count": 420,
"byte_count": 0,
"filename": null,
"error_message": null,
"created_at": "2026-09-09T17:00:00Z",
"started_at": "2026-09-09T17:00:01Z",
"finished_at": null,
"expires_at": null,
"cancelled_at": null
}/api/v1/workflows/workflows/{workflow_id}/item-exports/{job_id}/download-urlDownload Workflow Item Export
Return a short-lived Buckets download URL for a completed export. Re-checks the stored phase, field, and related-phase snapshot and returns 403 if the requester no longer covers it.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | UUID | Workflow ID |
job_id* | UUID | Export job ID |
Response Fields
| Name | Type | Description |
|---|---|---|
url* | string | Presigned Buckets download URL |
filename* | string | Suggested download filename |
expires_in | integer | null | URL lifetime in seconds |
curl https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/item-exports/12345678-abcd-4321-abcd-1234567890ab/download-url -H "Authorization: Bearer {token}"Response
200 OK{
"url": "https://storage.example/presigned/items.xlsx?sig=...",
"filename": "customer-onboarding-2026-09-09T170000Z.xlsx",
"expires_in": 300
}/api/v1/workflows/workflow-views/{view_id}/item-exports/columnsList Saved View Item Export Columns
Return the saved view's authorized projected columns without querying items.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | UUID | View ID |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<ItemExportColumn> | Ordered authorized columns available for selection |
total* | integer | Number of available columns |
curl https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/item-exports/columns -H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{"key":"item_code","label":"Item ID","field_id":null,"field_type":null,"is_list":null},
{"key":"title","label":"Title","field_id":null,"field_type":null,"is_list":null},
{"key":"field:11111111-2222-3333-4444-555555555555:sku","label":"Line Items — SKU","field_id":"11111111-2222-3333-4444-555555555555","field_type":"object","is_list":true,"table_subfield_key":"sku","table_field_name":"Line Items"}
],
"total": 3
}/api/v1/workflows/workflow-views/{view_id}/item-exports/columnsList Populated Saved View Export Columns
Return authorized saved-view columns that contain data for the submitted item query snapshot.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | UUID | View ID |
Request Body
| Name | Type | Description |
|---|---|---|
query | ItemQuery | Current filters, search, assignee, and sort used to keep only columns with matching data. |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<ItemExportColumn> | Ordered authorized columns available for selection |
total* | integer | Number of available columns |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/item-exports/columns -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"query":{"search":"Acme"}}'Response
200 OK{
"items": [
{"key":"item_code","label":"Item ID","field_id":null,"field_type":null,"is_list":null},
{"key":"title","label":"Title","field_id":null,"field_type":null,"is_list":null},
{"key":"field:11111111-2222-3333-4444-555555555555:sku","label":"Line Items — SKU","field_id":"11111111-2222-3333-4444-555555555555","field_type":"object","is_list":true,"table_subfield_key":"sku","table_field_name":"Line Items"}
],
"total": 3
}/api/v1/workflows/workflow-views/{view_id}/item-exportsCreate Saved View Item Export
Queue an export with the saved view's locked filters and field projection.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | UUID | View ID |
Request Body
| Name | Type | Description |
|---|---|---|
output_format* | string | csv or xlsx |
query | ItemQuery | Current filters, search, assignee, and sort. Pagination is ignored. |
column_keys | array<string> | 1–1000 unique keys returned by the columns endpoint, in the requested output order. Table schema columns use field:<field_id>:<schema_key>. Omit to export every authorized column with raw Table JSON. |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Export job ID |
status* | string | queued, running, succeeded, empty, failed, cancelled, or expired |
progress* | integer | Completion percentage |
row_count* | integer | Rows written so far |
byte_count* | integer | Final artifact size |
filename* | string | null | Workflow slug plus UTC export timestamp |
error_message* | string | null | Bounded failure detail |
expires_at* | datetime | null | Retention deadline, set when the job reaches a terminal state |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/item-exports -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"output_format":"csv","query":{}}'Response
202 Accepted{
"id": "12345678-abcd-4321-abcd-1234567890ab",
"company_id": "00000000-0000-0000-0000-000000000001",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"view_id": "f6a7b8c9-d0e1-2345-6789-012345678901",
"source_type": "view",
"output_format": "csv",
"status": "running",
"progress": 42,
"row_count": 420,
"byte_count": 0,
"filename": null,
"error_message": null,
"created_at": "2026-09-09T17:00:00Z",
"started_at": "2026-09-09T17:00:01Z",
"finished_at": null,
"expires_at": null,
"cancelled_at": null
}/api/v1/workflows/workflow-views/{view_id}/item-exports/{job_id}Get Saved View Item Export
Poll requester-owned saved-view export progress.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | UUID | View ID |
job_id* | UUID | Export job ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Export job ID |
status* | string | queued, running, succeeded, empty, failed, cancelled, or expired |
progress* | integer | Completion percentage |
row_count* | integer | Rows written so far |
byte_count* | integer | Final artifact size |
filename* | string | null | Workflow slug plus UTC export timestamp |
error_message* | string | null | Bounded failure detail |
expires_at* | datetime | null | Retention deadline, set when the job reaches a terminal state |
curl https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/item-exports/12345678-abcd-4321-abcd-1234567890ab -H "Authorization: Bearer {token}"Response
200 OK{
"id": "12345678-abcd-4321-abcd-1234567890ab",
"company_id": "00000000-0000-0000-0000-000000000001",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"view_id": "f6a7b8c9-d0e1-2345-6789-012345678901",
"source_type": "view",
"output_format": "xlsx",
"status": "running",
"progress": 42,
"row_count": 420,
"byte_count": 0,
"filename": null,
"error_message": null,
"created_at": "2026-09-09T17:00:00Z",
"started_at": "2026-09-09T17:00:01Z",
"finished_at": null,
"expires_at": null,
"cancelled_at": null
}/api/v1/workflows/workflow-views/{view_id}/item-exports/{job_id}/cancelCancel Saved View Item Export
Cancel a queued or running saved-view export.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | UUID | View ID |
job_id* | UUID | Export job ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Export job ID |
status* | string | queued, running, succeeded, empty, failed, cancelled, or expired |
progress* | integer | Completion percentage |
row_count* | integer | Rows written so far |
byte_count* | integer | Final artifact size |
filename* | string | null | Workflow slug plus UTC export timestamp |
error_message* | string | null | Bounded failure detail |
expires_at* | datetime | null | Retention deadline, set when the job reaches a terminal state |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/item-exports/12345678-abcd-4321-abcd-1234567890ab/cancel -H "Authorization: Bearer {token}"Response
200 OK{
"id": "12345678-abcd-4321-abcd-1234567890ab",
"company_id": "00000000-0000-0000-0000-000000000001",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"view_id": "f6a7b8c9-d0e1-2345-6789-012345678901",
"source_type": "view",
"output_format": "xlsx",
"status": "cancelled",
"progress": 42,
"row_count": 420,
"byte_count": 0,
"filename": null,
"error_message": null,
"created_at": "2026-09-09T17:00:00Z",
"started_at": "2026-09-09T17:00:01Z",
"finished_at": null,
"expires_at": null,
"cancelled_at": null
}/api/v1/workflows/workflow-views/{view_id}/item-exports/{job_id}/download-urlDownload Saved View Item Export
Return a short-lived Buckets download URL for a completed saved-view export. Re-checks the stored snapshot and returns 403 if the requester no longer covers it.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | UUID | View ID |
job_id* | UUID | Export job ID |
Response Fields
| Name | Type | Description |
|---|---|---|
url* | string | Presigned Buckets download URL |
filename* | string | Suggested download filename |
expires_in | integer | null | URL lifetime in seconds |
curl https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/item-exports/12345678-abcd-4321-abcd-1234567890ab/download-url -H "Authorization: Bearer {token}"Response
200 OK{
"url": "https://storage.example/presigned/items.xlsx?sig=...",
"filename": "customer-onboarding-2026-09-09T170000Z.xlsx",
"expires_in": 300
}Child Items & Bulk Operations
Manage the parent->child lineage surface of workflow items (list children, unlink, discover spawn targets and capabilities) plus the high-throughput bulk endpoints for creating, deleting, and routing items — both the workflow-in-body root collection and the workflow-scoped subtree.
/api/v1/workflows/items/{item_id}/childrenList Item Children
List a parent item's linked children (lineage surface). Gated by child-items:view on the parent's phase; returns every link in full. Opening a child's own detail is still separately gated by items:view in its workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Parent item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
(root)* | array<ChildLinkResponse> | The parent's child links |
curl "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/children" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"link_id": "bbbbcccc-dddd-eeee-ffff-000011112222",
"child_item_id": "aaaabbbb-cccc-dddd-eeee-ffff00001111",
"title": "Sub-task: collect documents",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"workflow_name": "Onboarding",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "In progress",
"created_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/items/{item_id}/children/{child_item_id}Link Existing Item Child
Link an existing item under a parent without creating or deleting either item. Requires child-items:create on the parent's phase and items:view on the child. Rejects duplicate parents and cycles.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Parent item ID |
child_item_id* | string (UUID) | Existing item to link as the child |
Response Fields
| Name | Type | Description |
|---|---|---|
link_id* | UUID | Parent->child link ID |
child_item_id* | UUID | Linked child item ID |
title* | string | Child item title |
workflow_id* | UUID | Workflow the child lives in |
workflow_name* | string | Child's workflow name |
current_phase_id* | UUID | Child's current phase ID |
current_phase_name* | string | Child's current phase name |
created_at* | datetime | When the link was created |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/children/aaaabbbb-cccc-dddd-eeee-ffff00001111" \
-H "Authorization: Bearer {token}"Response
201 Created{
"link_id": "bbbbcccc-dddd-eeee-ffff-000011112222",
"child_item_id": "aaaabbbb-cccc-dddd-eeee-ffff00001111",
"title": "Existing task",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"workflow_name": "Onboarding",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "In progress",
"created_at": "2026-06-01T12:00:00Z"
}/api/v1/workflows/items/{item_id}/children/{child_item_id}Unlink Item Child
Remove a parent->child link (unlink). Does NOT delete the child item. Gated by child-items:delete on the parent's phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Parent item ID |
child_item_id* | string (UUID) | Child item ID to unlink |
curl -X DELETE "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/children/aaaabbbb-cccc-dddd-eeee-ffff00001111" \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/items/{item_id}/child-capabilitiesGet Item Child Capabilities
Lineage-surface capabilities for a parent item (drives UI gating). Each flag is a live check_permission of the matching child-items:* action against the parent's current-phase resource. A token whose company is not the item's, including one with no company, gets 404.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Parent item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
can_create* | boolean | May spawn child items from this parent |
can_view* | boolean | May view the parent's children |
can_unlink* | boolean | May remove parent->child links |
curl "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/child-capabilities" \
-H "Authorization: Bearer {token}"Response
200 OK{
"can_create": true,
"can_view": true,
"can_unlink": false
}/api/v1/workflows/items/{item_id}/child-targetsList Child Targets
Folder -> workflow -> phase tree of places a child could be created. Gated by child-items:create on the parent's phase; only workflows where the caller has items:create and phases with allow_create_items are returned.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Parent item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
folders | array<ChildTargetNode> | Root folder nodes of the spawn-target treeDefault: [] |
curl "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/child-targets" \
-H "Authorization: Bearer {token}"Response
200 OK{
"folders": [
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Operations",
"kind": "folder",
"eligible": false,
"children": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Onboarding",
"kind": "workflow",
"eligible": false,
"children": [
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Intake",
"kind": "phase",
"eligible": true,
"children": []
}
]
}
]
}
]
}/api/v1/workflows/items/bulk-createBulk Create Items (workflow in body)
Create up to 1000 items in one workflow in a single call. The workflow_id travels in the body; each entry mirrors the single-item create body. Gated by items:create.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
workflow_id* | UUID | Target workflow |
items* | array<BulkItemCreateEntry> | 1-1000 items to create |
response_format | string (full | ids_only) | Whether to echo full rows or just idsDefault: full |
Response Fields
| Name | Type | Description |
|---|---|---|
succeeded* | array<UUID> | Created item IDs in input order |
created* | array<BulkCreatedItemRef> | Slim id + client_ref pairs in input order |
items | array<ItemResponse> | null | Full inserted rows when response_format='full' |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/bulk-create" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "items": [{"title": "Row 1", "phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "client_ref": "csv-1"}, {"title": "Row 2", "client_ref": "csv-2"}], "response_format": "ids_only"}'Response
201 Created{
"succeeded": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"],
"created": [
{"id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "client_ref": "csv-1"},
{"id": "c3d4e5f6-a7b8-9012-cdef-123456789013", "client_ref": "csv-2"}
],
"items": null
}/api/v1/workflows/items/bulk-deleteBulk Delete Items (workflow in body)
Delete up to 1000 items in one workflow. The workflow_id travels in the body (same path family as single-item delete). Gated by items:delete.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
workflow_id* | UUID | Workflow the items belong to |
item_ids* | array<UUID> | 1-1000 item IDs to delete |
response_format | string (full | ids_only) | Whether to echo full rows or just idsDefault: full |
Response Fields
| Name | Type | Description |
|---|---|---|
succeeded* | array<UUID> | Affected item IDs in input order |
items | array<ItemResponse> | null | Full rows when response_format='full' and the entities still exist (route, not delete) |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/bulk-delete" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "item_ids": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"], "response_format": "ids_only"}'Response
200 OK{
"succeeded": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"],
"items": null
}/api/v1/workflows/items/bulk-routeBulk Route Items (workflow in body)
Move up to 1000 items to a target phase in one workflow. The workflow_id travels in the body. Gated by items:route. Over the target's max_passes, items moved by a person (sign-in token or member principal), and any item leaving Exceptions, reject the whole batch with 409 and detail.errors[] entries with code max_passes_exceeded (detail.limit, detail.passes); for any other caller (API key, agent, automation) those items go to Exceptions instead and are listed in diverted, not succeeded.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
workflow_id* | UUID | Workflow the items belong to |
item_ids* | array<UUID> | 1-1000 item IDs to route |
to_phase_id* | UUID | Target phase |
delay_seconds | integer | null | Keep the item hidden this long after the move (0..604800), if longer than the arrival cooldown. Capped by the destination's defer_max_seconds (400 defer_exceeds_max); not stored on the item |
response_format | string (full | ids_only) | Whether to echo full rows or just idsDefault: full |
Response Fields
| Name | Type | Description |
|---|---|---|
succeeded* | array<UUID> | Item IDs that reached the target phase, in input order |
diverted | array<BulkItemDiversion> | Items max_passes sent to Exceptions instead of the target, in input order; they are not in succeeded |
items | array<ItemResponse> | null | Full rows of succeeded and diverted items when response_format='full' |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/bulk-route" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "item_ids": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"], "to_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678902"}'Response
200 OK{
"succeeded": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"],
"diverted": [],
"items": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678902",
"current_phase_name": "Review",
"title": "Invoice #1042",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z"
}
]
}/api/v1/workflows/items/bulk-route-to-exceptionBulk Route Items To Exception Phase
Move up to 1000 items into the workflow's built-in exception phase. reason is required. One failure rejects the whole batch. The source exit gate and the destination required-field gate are skipped.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
workflow_id* | UUID | Workflow the items belong to |
item_ids* | array<UUID> | 1-1000 item IDs to route |
reason* | string | Why the items entered the exception phase |
details | string | Optional longer note |
response_format | string (full | ids_only) | Whether to echo full rows or just idsDefault: full |
Response Fields
| Name | Type | Description |
|---|---|---|
succeeded* | array<UUID> | Affected item IDs in input order |
items | array<ItemResponse> | null | Full rows when response_format='full' and the entities still exist (route, not delete) |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/bulk-route-to-exception" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "item_ids": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"], "reason": "Missing document"}'Response
200 OK{
"succeeded": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"],
"items": null
}/api/v1/workflows/workflows/{workflow_id}/itemsCreate Item
Create a single item inside a workflow. Omitting phase_id seeds the item into the workflow's first phase. Gated by items:create.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
title* | string | Item title (1-500 chars) |
phase_id | UUID | null | Starting phase; defaults to the workflow's first phase |
description | string | null | Item description (<=100000 chars) |
field_values | object | null | Map of field name -> value. An unknown name is dropped and returned in that entry's ignored_fields as unknown_field. |
parent_item_id | UUID | null | Link the new item as a child of this parent |
timeout_minutes | number | null | Per-phase timeout |
global_timeout_minutes | number | null | Global (cross-phase) timeout |
visibility_timeout_on_create_minutes | integer | null | Hide the item for N minutes after creation |
visibility_timeout_on_release_minutes | integer | null | Hide the item for N minutes after release |
visibility_timeout_on_transition_minutes | integer | null | Hide the item for N minutes after a transition |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
description | string | null | Item description |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
assigned_to | UUID | null | Assigned principal ID |
assigned_group_id | UUID | null | Assigned group ID |
assigned_at | datetime | null | When assigned |
field_values | array<FieldValueResponse> | Resolved field valuesDefault: [] |
card_fields | array<CardField> | Fields surfaced on the item cardDefault: [] |
parent | ParentLinkResponse | null | Parent lineage when this item is linked as a child; null unless the caller can view the parent on the board or through a saved view that contains it |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"title": "Invoice #1042", "phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "field_values": {"Invoice number": 1042}}'Response
201 Created{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Intake",
"title": "Invoice #1042",
"description": null,
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z",
"assigned_to": null,
"field_values": [{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "field_name": "Invoice number", "value": 1042}],
"card_fields": []
}/api/v1/workflows/workflows/{workflow_id}/itemsList Items
List items in a workflow with rich filtering (phases, assignment, date ranges, claimability) and sorting. Respects field-level view permissions. Gated by items:view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
phase_id | string (UUID) | null | Single phase UUID (legacy, prefer phase_ids) |
phase_ids | string | null | Comma-separated phase UUIDs |
search | string | null | Case-insensitive substring match on title, description, current phase name, assignee display name, or a stored field value (limited to fields the caller can view), or an item UUID prefix (a leading '#' is ignored) |
assigned_to | string | null | Filter by assigned principal ID |
assigned | string | null | 'yes' = only assigned, 'no' = only unassigned |
created_from | string | null | ISO date lower bound for created_at |
created_to | string | null | ISO date upper bound for created_at |
updated_from | string | null | ISO date lower bound for updated_at |
updated_to | string | null | ISO date upper bound for updated_at |
claimable_for | string | null | Restrict to items the named principal could currently claim; pass 'me' for the caller |
sort | string | Sort field: created_at, updated_at, titleDefault: created_at |
sort_dir | string | Sort direction: asc or descDefault: desc |
limit | integer | Page size (0–500). 0 returns the first 500 itemsDefault: 50 |
offset | integer | Offset for paginationDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<ItemListItem> | Page of items |
total* | integer | Total matching items |
limit* | integer | Page size |
offset* | integer | Page offset |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items?phase_ids=b2c3d4e5-f6a7-8901-bcde-f12345678901&sort=updated_at&sort_dir=desc&limit=50&offset=0" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"title": "Invoice #1042",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Intake",
"assigned_to": null,
"is_visible": true,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}/api/v1/workflows/workflows/{workflow_id}/items/queryQuery Items
Filtered, paginated item listing with structured, type-aware conditions. Matches configured fields by field_id, applies type-correct operators via the shared filter engine, supports json dotted paths, and enforces field-level view permissions. Gated by items:view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
filters | array<ItemFieldFilter> | Up to 30 AND-combined, type-aware filters |
phase_ids | array<UUID> | null | Restrict to these phases |
search | string | null | Free-text search (<=500 chars): title, description, current phase name, assignee display name, stored field values (limited to fields the caller can view), or an item UUID prefix (a leading '#' is ignored) |
assigned | string (yes | no) | null | Only assigned / only unassigned |
assigned_to | UUID | null | Filter by assigned principal ID |
sort | string | Sort fieldDefault: created_at |
sort_dir | string (asc | desc) | Sort directionDefault: desc |
limit | integer | Page size (0–500). 0 returns the first 500 itemsDefault: 50 |
offset | integer | Offset for paginationDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<ItemListItem> | Page of items |
total* | integer | Total matching items |
limit* | integer | Page size |
offset* | integer | Page offset |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/query" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"filters": [{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "operator": "gte", "value": 1000}], "phase_ids": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"], "limit": 50}'Response
200 OK{
"items": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"title": "Invoice #1042",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Intake",
"assigned_to": null,
"is_visible": true,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}/api/v1/workflows/workflows/{workflow_id}/items/bulk-createBulk Create Items
Path-scoped bulk create: insert up to 1000 items into the workflow named in the URL. Each entry mirrors the single-item create body, with per-entry phase support.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
items* | array<BulkItemCreateEntry> | 1-1000 items to create |
response_format | string (full | ids_only) | Whether to echo full rows or just idsDefault: full |
Response Fields
| Name | Type | Description |
|---|---|---|
succeeded* | array<UUID> | Created item IDs in input order |
created* | array<BulkCreatedItemRef> | Slim id + client_ref pairs in input order |
items | array<ItemResponse> | null | Full inserted rows when response_format='full' |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/bulk-create" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"items": [{"title": "Row 1", "phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "client_ref": "csv-1"}, {"title": "Row 2", "client_ref": "csv-2"}], "response_format": "ids_only"}'Response
201 Created{
"succeeded": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"],
"created": [
{"id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "client_ref": "csv-1"},
{"id": "c3d4e5f6-a7b8-9012-cdef-123456789013", "client_ref": "csv-2"}
],
"items": null
}/api/v1/workflows/workflows/{workflow_id}/items/bulk-deleteBulk Delete Items
Path-scoped bulk delete: remove up to 1000 items from the workflow named in the URL.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
item_ids* | array<UUID> | 1-1000 item IDs to delete |
response_format | string (full | ids_only) | Whether to echo full rows or just idsDefault: full |
Response Fields
| Name | Type | Description |
|---|---|---|
succeeded* | array<UUID> | Affected item IDs in input order |
items | array<ItemResponse> | null | Full rows when response_format='full' and the entities still exist (route, not delete) |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/bulk-delete" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"item_ids": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"], "response_format": "ids_only"}'Response
200 OK{
"succeeded": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"],
"items": null
}/api/v1/workflows/workflows/{workflow_id}/items/bulk-routeBulk Route Items
Path-scoped bulk route: move up to 1000 items in the workflow named in the URL to a target phase. Over the target's max_passes, items moved by a person (sign-in token or member principal), and any item leaving Exceptions, reject the whole batch with 409 and detail.errors[] entries with code max_passes_exceeded (detail.limit, detail.passes); for any other caller (API key, agent, automation) those items go to Exceptions instead and are listed in diverted, not succeeded.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
item_ids* | array<UUID> | 1-1000 item IDs to route |
to_phase_id* | UUID | Target phase |
delay_seconds | integer | null | Keep the item hidden this long after the move (0..604800), if longer than the arrival cooldown. Capped by the destination's defer_max_seconds (400 defer_exceeds_max); not stored on the item |
response_format | string (full | ids_only) | Whether to echo full rows or just idsDefault: full |
Response Fields
| Name | Type | Description |
|---|---|---|
succeeded* | array<UUID> | Item IDs that reached the target phase, in input order |
diverted | array<BulkItemDiversion> | Items max_passes sent to Exceptions instead of the target, in input order; they are not in succeeded |
items | array<ItemResponse> | null | Full rows of succeeded and diverted items when response_format='full' |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/bulk-route" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"item_ids": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"], "to_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678902"}'Response
200 OK{
"succeeded": ["c3d4e5f6-a7b8-9012-cdef-123456789012", "c3d4e5f6-a7b8-9012-cdef-123456789013"],
"diverted": [],
"items": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678902",
"current_phase_name": "Review",
"title": "Invoice #1042",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z"
}
]
}Comments
Read and write the discussion thread on a workflow item. Comments are listed and created under their item, then edited or removed by comment ID. Each comment may carry file attachments and tracks its author and timestamps. Callers whose only access is a saved view use the /workflow-views/{view_id}/... variants (or pass view_id on the board routes).
/api/v1/workflows/items/{item_id}/commentsList Comments
Return the full comment thread for an item, newest first.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
view_id | string (UUID) | null | Saved workflow view used to authorize the item read when the caller has view-scoped access |
workflow_id | string (UUID) | null | Owning workflow. Required for caller-authorized App tool calls and validated against item_id; optional for direct API clients. 400 when it does not own the item |
Response Fields
| Name | Type | Description |
|---|---|---|
(root)* | array<CommentResponse> | List of comments on the item |
curl "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/comments" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "33334444-5555-6666-7777-88889999aaaa",
"item_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"author_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"content": "Following up with the customer today.",
"attachments": [],
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/items/{item_id}/commentsCreate Comment
Add a new comment to an item, optionally with file attachments. Requires workflows:workflows:items:comment on the item's phase, or pass view_id to comment through a saved view where you can edit items. Caller-authorized Apps pass workflow_id so the tool policy can anchor on that workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
item_id* | string (UUID) | Item ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
view_id | string (UUID) | null | Saved workflow view to authorize through instead of the board: the item must be inside the view (404 otherwise) and the caller needs workflows:workflows:views:items:edit on it |
workflow_id | string (UUID) | null | Owning workflow. Required for caller-authorized App tool calls and validated against item_id; optional for direct API clients. 400 when it does not own the item |
Request Body
| Name | Type | Description |
|---|---|---|
content | string | Comment body (max 5000 characters)Default: "" |
attachments | array<CommentAttachment> | Files to attach to the comment |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Comment ID |
item_id* | UUID | Item the comment belongs to |
author_id* | UUID | null | Author principal (null for system comments) |
content* | string | Comment body |
attachments | array<CommentAttachment> | Files attached to the comment |
created_at* | datetime | When the comment was created |
updated_at* | datetime | When the comment was last edited |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/comments \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"content": "Following up with the customer today."}'Response
201 Created{
"id": "33334444-5555-6666-7777-88889999aaaa",
"item_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"author_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"content": "Following up with the customer today.",
"attachments": [],
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z"
}/api/v1/workflows/comments/{comment_id}Update Comment
Edit the content or attachments of your own comment. Authorized like Create Comment (board permission, or view_id).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
comment_id* | string (UUID) | Comment ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
view_id | string (UUID) | null | Saved workflow view to authorize through instead of the board: the item must be inside the view (404 otherwise) and the caller needs workflows:workflows:views:items:edit on it |
Request Body
| Name | Type | Description |
|---|---|---|
content | string | Replacement comment body (max 5000 characters)Default: "" |
attachments | array<CommentAttachment> | null | Replacement attachment list |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Comment ID |
item_id* | UUID | Item the comment belongs to |
author_id* | UUID | null | Author principal (null for system comments) |
content* | string | Comment body |
attachments | array<CommentAttachment> | Files attached to the comment |
created_at* | datetime | When the comment was created |
updated_at* | datetime | When the comment was last edited |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/comments/33334444-5555-6666-7777-88889999aaaa \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"content": "Customer confirmed, closing out."}'Response
200 OK{
"id": "33334444-5555-6666-7777-88889999aaaa",
"item_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"author_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"content": "Customer confirmed, closing out.",
"attachments": [],
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:05:00Z"
}/api/v1/workflows/comments/{comment_id}Delete Comment
Permanently remove your own comment from its item thread. Authorized like Create Comment (board permission, or view_id).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
comment_id* | string (UUID) | Comment ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
view_id | string (UUID) | null | Saved workflow view to authorize through instead of the board: the item must be inside the view (404 otherwise) and the caller needs workflows:workflows:views:items:edit on it |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/comments/33334444-5555-6666-7777-88889999aaaa \
-H "Authorization: Bearer {token}"Response
204 No Content(204 No Content)/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/commentsList Comments Through a View
Return an item's comment thread, newest first, through a saved view. Requires workflows:workflows:views:items:view on the view (or the item's view phase); 404 when the item is not inside the view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Saved view ID |
item_id* | string (UUID) | Item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
(root)* | array<CommentResponse> | List of comments on the item |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/99990000-1111-2222-3333-444455556666/items/c3d4e5f6-a7b8-9012-cdef-123456789012/comments" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "33334444-5555-6666-7777-88889999aaaa",
"item_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"author_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"content": "Following up with the customer today.",
"attachments": [],
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/commentsCreate Comment Through a View
Add a comment to an item through a saved view. Requires workflows:workflows:views:items:edit on the view or on the item's view phase (a grant on a single view field is not enough); 404 when the item is not inside the view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Saved view ID |
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
content | string | Comment body (max 5000 characters)Default: "" |
attachments | array<CommentAttachment> | Files to attach to the comment |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Comment ID |
item_id* | UUID | Item the comment belongs to |
author_id* | UUID | null | Author principal (null for system comments) |
content* | string | Comment body |
attachments | array<CommentAttachment> | Files attached to the comment |
created_at* | datetime | When the comment was created |
updated_at* | datetime | When the comment was last edited |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/99990000-1111-2222-3333-444455556666/items/c3d4e5f6-a7b8-9012-cdef-123456789012/comments \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"content": "Following up with the customer today."}'Response
201 Created{
"id": "33334444-5555-6666-7777-88889999aaaa",
"item_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"author_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"content": "Following up with the customer today.",
"attachments": [],
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z"
}/api/v1/workflows/workflow-views/{view_id}/comments/{comment_id}Update Comment Through a View
Edit your own comment through a saved view. Authorized like Create Comment Through a View; only the author may edit.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Saved view ID |
comment_id* | string (UUID) | Comment ID |
Request Body
| Name | Type | Description |
|---|---|---|
content | string | Replacement comment body (max 5000 characters)Default: "" |
attachments | array<CommentAttachment> | null | Replacement attachment list |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Comment ID |
item_id* | UUID | Item the comment belongs to |
author_id* | UUID | null | Author principal (null for system comments) |
content* | string | Comment body |
attachments | array<CommentAttachment> | Files attached to the comment |
created_at* | datetime | When the comment was created |
updated_at* | datetime | When the comment was last edited |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/workflow-views/99990000-1111-2222-3333-444455556666/comments/33334444-5555-6666-7777-88889999aaaa \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"content": "Customer confirmed, closing out."}'Response
200 OK{
"id": "33334444-5555-6666-7777-88889999aaaa",
"item_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"author_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"content": "Customer confirmed, closing out.",
"attachments": [],
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:05:00Z"
}/api/v1/workflows/workflow-views/{view_id}/comments/{comment_id}Delete Comment Through a View
Permanently remove your own comment through a saved view. Authorized like Create Comment Through a View; only the author may delete.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Saved view ID |
comment_id* | string (UUID) | Comment ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/workflow-views/99990000-1111-2222-3333-444455556666/comments/33334444-5555-6666-7777-88889999aaaa \
-H "Authorization: Bearer {token}"Response
204 No Content(204 No Content)Attachments
Upload and manage file attachments on workflow items using S3-style presigned URLs. The flow is: request a presigned upload URL, PUT the bytes directly to storage, then confirm the upload to persist attachment metadata on a field. A file that is already in Buckets can be attached by its file ID instead. Download URLs are short-lived presigned GET links. Buckets-backed attachments expose pipeline status and flattened extraction results. Comment attachments use a dedicated upload-url endpoint gated on the item's comment permission.
/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments/upload-urlRequest Upload URL
Request a short-lived presigned PUT URL to upload an attachment for an item field. Upload the file bytes directly to the returned upload_url, then call Confirm Upload with the returned object_key to persist the attachment. Exposed to Apps as the App-only tool workflows.attachments.request_upload_url; Apps call window.ergon.files.upload and the host runs this handshake.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
item_id* | string (UUID) | Item ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
view_id | string (UUID) | null | Saved workflow view used to authorize this operation with view-scoped item and field permissions |
Request Body
| Name | Type | Description |
|---|---|---|
field_id* | string | Attachment field the upload targets |
filename* | string | Original filename (1-500 chars) |
content_type* | string | MIME type (1-200 chars) |
size* | integer | File size in bytes (> 0) |
Response Fields
| Name | Type | Description |
|---|---|---|
upload_url* | string | Short-lived presigned PUT URL — use it exactly as returned; do not parse, cache, or reconstruct it. |
object_key* | string | Storage key to pass to Confirm Upload |
expires_in* | integer | Seconds until the URL expires |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/attachments/upload-url \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"filename": "contract.pdf",
"content_type": "application/pdf",
"size": 482910
}'Response
200 OK{
"upload_url": "https://ergon-files.s3.us-east-1.amazonaws.com/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/contract.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=...",
"object_key": "workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/contract.pdf",
"expires_in": 300
}/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments/confirmConfirm Upload
Confirm a completed presigned upload and persist the attachment metadata on the field. Returns the full list of attachments currently stored on the field. Exposed to Apps as the App-only tool workflows.attachments.confirm_upload (called by the host for window.ergon.files.upload).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
item_id* | string (UUID) | Item ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
view_id | string (UUID) | null | Saved workflow view used to authorize this operation with view-scoped item and field permissions |
Request Body
| Name | Type | Description |
|---|---|---|
field_id* | string | Attachment field the upload targets |
object_key* | string | Storage key returned by Request Upload URL |
filename* | string | Original filename |
content_type* | string | MIME type |
size* | integer | File size in bytes (> 0) |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<AttachmentMeta> | All attachments now stored on the field |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/attachments/confirm \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"object_key": "workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/contract.pdf",
"filename": "contract.pdf",
"content_type": "application/pdf",
"size": 482910
}'Response
200 OK[
{
"object_key": "workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/contract.pdf",
"filename": "contract.pdf",
"content_type": "application/pdf",
"size": 482910,
"uploaded_at": "2026-06-01T12:00:00Z",
"bucket_id": "b1111111-2222-3333-4444-555555555555",
"buckets_file_id": "bf222222-3333-4444-5555-666666666666",
"folder_id": null
}
]/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments/attach-fileAttach Bucket File
Attach a file that already lives in Buckets and that the caller can view, such as a file in an agent's conversation bucket. The file is copied into the field's folder as a new Buckets file (with its own ID and storage key) and recorded like a confirmed upload; the original stays where it is. The field's file count, type and size rules apply, and the copy is processed by the folder's pipeline when it has one. Requires edit permission on the item and field. Returns 404 when the file doesn't exist or the caller can't view it, and 409 when the field has no backing folder. Exposed to agents as the tool workflows.attachments.attach_file.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
item_id* | string (UUID) | Item ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
view_id | string (UUID) | null | Saved workflow view used to authorize this operation with view-scoped item and field permissions |
Request Body
| Name | Type | Description |
|---|---|---|
field_id* | string | Attachment field to attach the file to |
file_id* | string (UUID) | Buckets file ID of a file the caller can view |
filename | string | null | Name for the attachment (1-500 chars); defaults to the file's own name |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<AttachmentMeta> | All attachments now stored on the field |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/attachments/attach-file \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"file_id": "5f333333-4444-5555-6666-777777777777"
}'Response
201 Created[
{
"object_key": "buckets/b1111111-2222-3333-4444-555555555555/files/bf222222-3333-4444-5555-666666666666/raw/contract.pdf",
"filename": "contract.pdf",
"content_type": "application/pdf",
"size": 482910,
"uploaded_at": "2026-06-01T12:00:00Z",
"bucket_id": "b1111111-2222-3333-4444-555555555555",
"buckets_file_id": "bf222222-3333-4444-5555-666666666666",
"folder_id": "f0444444-5555-6666-7777-888888888888"
}
]/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments/download-urlRequest Download URL
Return a short-lived presigned GET URL to download a stored attachment by its object_key. Exposed to Apps as the App-only tool workflows.attachments.get_download_url (open the result with ergon:navigate, or preview the attachment over the App with window.ergon.files.preview).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
item_id* | string (UUID) | Item ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
object_key* | string | Storage key of the attachment |
buckets_file_id | string | null | Optional Buckets file ID when the attachment lives in a custom bucket |
field_id | string | null | Attachment field ID; required with view_id for item-field attachments and omitted for comment images |
view_id | string (UUID) | null | Saved workflow view used to authorize this operation with view-scoped item and field permissions |
disposition | inline | attachment | inline (default) renders the file in the browser tab; attachment forces a download. Forwarded to Buckets for Buckets-backed attachments. |
Response Fields
| Name | Type | Description |
|---|---|---|
download_url* | string | Short-lived presigned GET URL — use it exactly as returned; do not parse, cache, or reconstruct it. |
expires_in* | integer | Seconds until the URL expires |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/attachments/download-url?object_key=workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/contract.pdf" \
-H "Authorization: Bearer {token}"Response
200 OK{
"download_url": "https://ergon-files.s3.us-east-1.amazonaws.com/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/contract.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=...",
"expires_in": 300
}/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments/resultsAttachment Pipeline Results
Return flattened schema results for a single Buckets-backed attachment.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
item_id* | string (UUID) | Item ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
buckets_file_id* | string | Buckets file ID of the attachment to fetch results for |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | object | Flattened extraction/schema results for the attachment (shape depends on the pipeline) |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/attachments/results?buckets_file_id=bf222222-3333-4444-5555-666666666666" \
-H "Authorization: Bearer {token}"Response
200 OK{
"buckets_file_id": "bf222222-3333-4444-5555-666666666666",
"fields": {
"invoice_number": "INV-2026-0042",
"total_amount": 482.91,
"currency": "USD"
}
}/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments/statusAttachment Pipeline Status
Return pipeline status for each Buckets-backed attachment on a field.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
item_id* | string (UUID) | Item ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
field_id* | string | Attachment field to report status for |
view_id | string (UUID) | null | Saved workflow view used to authorize this operation with view-scoped item and field permissions |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<AttachmentStatusEntry> | Pipeline status per Buckets-backed attachment |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/attachments/status?field_id=d4e5f6a7-b8c9-0123-def0-234567890123" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"buckets_file_id": "bf222222-3333-4444-5555-666666666666",
"status": "processed",
"process_skip_reason": null
}
]/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachmentsRemove Attachment
Remove a single attachment from a field, identified by field_id and object_key. Returns the remaining attachments on the field. Exposed to agents and Apps as the tool workflows.attachments.delete; Apps see it as a mutation that requires confirmation, so ask the user before calling it.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
item_id* | string (UUID) | Item ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
view_id | string (UUID) | null | Saved workflow view used to authorize this operation with view-scoped item and field permissions |
Request Body
| Name | Type | Description |
|---|---|---|
field_id* | string | Attachment field to remove from |
object_key* | string | Storage key of the attachment to remove |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<AttachmentMeta> | Remaining attachments on the field |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/attachments \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"object_key": "workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/contract.pdf"
}'Response
200 OK[]/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/comment-attachments/upload-urlRequest Comment Upload URL
Request a presigned PUT URL for an image attached to a comment. The object is keyed under the item's comment prefix so the item attachment download-url endpoint can serve it back. Gated on the item's comment permission, matching the gate on posting the comment itself.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
item_id* | string (UUID) | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
filename* | string | Original filename (1-500 chars) |
content_type* | string | MIME type (1-200 chars) |
size* | integer | File size in bytes (> 0) |
Response Fields
| Name | Type | Description |
|---|---|---|
upload_url* | string | Short-lived presigned PUT URL — use it exactly as returned; do not parse, cache, or reconstruct it. |
object_key* | string | Storage key under the comment prefix |
expires_in* | integer | Seconds until the URL expires |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/comment-attachments/upload-url \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"filename": "screenshot.png",
"content_type": "image/png",
"size": 18422
}'Response
200 OK{
"upload_url": "https://ergon-files.s3.us-east-1.amazonaws.com/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/comment/screenshot.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=...",
"object_key": "workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/items/c3d4e5f6-a7b8-9012-cdef-123456789012/comment/screenshot.png",
"expires_in": 300
}Assignment Groups
Assignment groups bundle principals (members) and channel addresses, then bind to workflow phases to drive item routing and claiming. A phase with no group is shared (anyone with edit permission may act); linking a group makes the phase owned, so items must be claimed. Per-(phase, group, principal) capacity caps limit how many concurrent items each member can hold.
/api/v1/workflows/workflows/{workflow_id}/assignment-groupsList Assignment Groups
List all assignment groups defined on a workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<GroupResponse> | Assignment groups |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/assignment-groups" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Tier-1 agents",
"description": "Front-line support queue",
"created_at": "2026-06-01T12:00:00Z",
"member_count": 4,
"channel_count": 2,
"linked_phases": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]
}
]/api/v1/workflows/workflows/{workflow_id}/assignment-groupsCreate Assignment Group
Create a new assignment group on a workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Group name (1-200 chars) |
description | string | null | Optional description |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Assignment group ID |
workflow_id* | UUID | Owning workflow |
name* | string | Group name |
description* | string | null | Group description |
created_at* | datetime | When the group was created |
member_count | integer | Number of principals in the groupDefault: 0 |
channel_count | integer | Number of bound channel addressesDefault: 0 |
linked_phases | array<UUID> | Phase IDs this group is linked toDefault: [] |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/assignment-groups \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Tier-1 agents", "description": "Front-line support queue"}'Response
201 Created{
"id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Tier-1 agents",
"description": "Front-line support queue",
"created_at": "2026-06-01T12:00:00Z",
"member_count": 0,
"channel_count": 0,
"linked_phases": []
}/api/v1/workflows/assignment-groups/{group_id}Update Assignment Group
Rename an assignment group or change its description.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
group_id* | string (UUID) | Assignment group ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name (1-200 chars) |
description | string | null | New description |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Assignment group ID |
workflow_id* | UUID | Owning workflow |
name* | string | Group name |
description* | string | null | Group description |
created_at* | datetime | When the group was created |
member_count | integer | Number of principals in the groupDefault: 0 |
channel_count | integer | Number of bound channel addressesDefault: 0 |
linked_phases | array<UUID> | Phase IDs this group is linked toDefault: [] |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456 \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Tier-1 agents (EMEA)"}'Response
200 OK{
"id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Tier-1 agents (EMEA)",
"description": "Front-line support queue",
"created_at": "2026-06-01T12:00:00Z",
"member_count": 4,
"channel_count": 2,
"linked_phases": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]
}/api/v1/workflows/assignment-groups/{group_id}Delete Assignment Group
Delete an assignment group and unlink it from all phases.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
group_id* | string (UUID) | Assignment group ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456 \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/assignment-groups/{group_id}/membersList Group Members
List the principals that belong to an assignment group.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
group_id* | string (UUID) | Assignment group ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<MemberResponse> | Group members |
curl "https://platform.ergondata.ai/api/v1/workflows/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456/members" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "11112222-3333-4444-5555-666677778888",
"group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"created_at": "2026-06-01T12:05:00Z"
}
]/api/v1/workflows/assignment-groups/{group_id}/membersAdd Group Member
Add a principal to an assignment group.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
group_id* | string (UUID) | Assignment group ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_id* | UUID | Principal to add |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Membership row ID |
group_id* | UUID | Owning assignment group |
principal_id* | UUID | Member principal |
created_at* | datetime | When the principal was added |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456/members \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee"}'Response
201 Created{
"id": "11112222-3333-4444-5555-666677778888",
"group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"created_at": "2026-06-01T12:05:00Z"
}/api/v1/workflows/assignment-groups/{group_id}/members/{principal_id}Remove Group Member
Remove a principal from an assignment group.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
group_id* | string (UUID) | Assignment group ID |
principal_id* | string (UUID) | Principal to remove |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456/members/77778888-9999-aaaa-bbbb-ccccddddeeee \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/assignment-groups/{group_id}/channelsList Group Channels
List the channel addresses bound to an assignment group.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
group_id* | string (UUID) | Assignment group ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<GroupChannelResponse> | Bound channel addresses |
curl "https://platform.ergondata.ai/api/v1/workflows/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456/channels" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"address_id": "22223333-4444-5555-6666-777788889999",
"address": "+15551234567",
"channel_name": "Support WhatsApp",
"channel_type": "whatsapp",
"direction": "inbound",
"display_name": "Support WhatsApp"
}
]/api/v1/workflows/assignment-groups/{group_id}/channelsSet Group Channels
Atomically replace the channel addresses bound to a group. Each address must already be granted to this workflow on the channels service.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
group_id* | string (UUID) | Assignment group ID |
Request Body
| Name | Type | Description |
|---|---|---|
channels* | array<GroupChannelLink> | Full replacement set of channel links |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<GroupChannelResponse> | Resulting bound channels |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456/channels \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"channels": [{"address_id": "22223333-4444-5555-6666-777788889999"}]}'Response
200 OK[
{
"address_id": "22223333-4444-5555-6666-777788889999",
"address": "+15551234567",
"channel_name": "Support WhatsApp",
"channel_type": "whatsapp",
"direction": "inbound",
"display_name": "Support WhatsApp"
}
]/api/v1/workflows/assignment-groups/{group_id}/phasesList Group Phases
List the phases an assignment group is linked to, with per-phase routing config.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
group_id* | string (UUID) | Assignment group ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<GroupPhaseResponse> | Linked phases |
curl "https://platform.ergondata.ai/api/v1/workflows/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456/phases" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"is_default": true,
"assignment_strategy": "round_robin",
"assignment_active": true,
"assignment_config": {"cooldown_seconds": 30}
}
]/api/v1/workflows/assignment-groups/{group_id}/phasesSet Group Phases
Atomically replace the phases linked to a group. All phases must belong to the group's workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
group_id* | string (UUID) | Assignment group ID |
Request Body
| Name | Type | Description |
|---|---|---|
phases* | array<GroupPhaseLink> | Full replacement set of phase links |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<GroupPhaseResponse> | Resulting linked phases |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456/phases \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"phases": [{"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "is_default": true}]}'Response
200 OK[
{
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"is_default": true,
"assignment_strategy": "manual",
"assignment_active": true,
"assignment_config": {}
}
]/api/v1/workflows/phases/{phase_id}/assignment-groupsSet Phase Groups
Atomically replace the assignment groups linked to a phase. Linking at least one group makes the phase owned (items must be claimed).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
Request Body
| Name | Type | Description |
|---|---|---|
groups* | array<PhaseAssignmentGroupLink> | Full replacement set of group links |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<PhaseAssignmentGroupResponse> | Resulting phase-group bindings |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/assignment-groups \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"groups": [{"group_id": "a7b8c9d0-e1f2-3456-0123-567890123456", "is_default": true}]}'Response
200 OK[
{
"id": "33334444-5555-6666-7777-88889999aaaa",
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"group_name": "Tier-1 agents",
"is_default": true,
"created_at": "2026-06-01T12:10:00Z"
}
]/api/v1/workflows/phases/{phase_id}/assignment-groups/{group_id}/configGet Phase Group Routing
Return the routing configuration for a single phase-group binding.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
group_id* | string (UUID) | Assignment group ID |
Response Fields
| Name | Type | Description |
|---|---|---|
phase_id* | UUID | Phase the binding belongs to |
group_id* | UUID | Assignment group the binding targets |
assignment_strategy* | string | Routing strategy (manual, round_robin, least_loaded, random) |
assignment_active* | boolean | Whether automatic assignment is active |
assignment_config | object | Strategy-specific configuration blob |
condition | object | null | Item-scoping predicate ({"logic": "all"|"any", "filters": [...]}, route exit-gate vocabulary, field_id filters only). null covers every item |
curl "https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456/config" \
-H "Authorization: Bearer {token}"Response
200 OK{
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assignment_strategy": "round_robin",
"assignment_active": true,
"assignment_config": {"cooldown_seconds": 30}
}/api/v1/workflows/phases/{phase_id}/assignment-groups/{group_id}/configUpdate Phase Group Routing
Update the routing strategy, active flag, config blob, or item-scoping condition for a phase-group binding.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
group_id* | string (UUID) | Assignment group ID |
Request Body
| Name | Type | Description |
|---|---|---|
assignment_strategy | string | null | Routing strategy (manual, round_robin, ...). Pull phases accept only manual (400 pull_phase_manual_assignment_only) |
assignment_active | boolean | null | Whether automatic assignment is active |
assignment_config | object | null | Strategy-specific configuration blob |
condition | object | null | Item-scoping predicate ({"logic", "filters"}); matching items are owned and auto-routed by this group ahead of the default. Omit to leave unchanged; null or empty filters clears it |
Response Fields
| Name | Type | Description |
|---|---|---|
phase_id* | UUID | Phase the binding belongs to |
group_id* | UUID | Assignment group the binding targets |
assignment_strategy* | string | Routing strategy (manual, round_robin, least_loaded, random) |
assignment_active* | boolean | Whether automatic assignment is active |
assignment_config | object | Strategy-specific configuration blob |
condition | object | null | Item-scoping predicate ({"logic": "all"|"any", "filters": [...]}, route exit-gate vocabulary, field_id filters only). null covers every item |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456/config \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"assignment_strategy": "round_robin", "assignment_active": true}'Response
200 OK{
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assignment_strategy": "round_robin",
"assignment_active": true,
"assignment_config": {}
}/api/v1/workflows/phases/{phase_id}/assignment-groups/{group_id}Unlink Phase Group
Unlink an assignment group from a phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
group_id* | string (UUID) | Assignment group ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456 \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/phases/{phase_id}/assignment-groups/{group_id}/capacitiesSet Phase Group Capacities
Upsert per-principal concurrency caps for one phase-group binding. A null max_items clears a principal's cap (unlimited).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
phase_id* | string (UUID) | Phase ID |
group_id* | string (UUID) | Assignment group ID |
Request Body
| Name | Type | Description |
|---|---|---|
capacities* | array<CapacityEntry> | Per-principal caps to upsert |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<CapacityResponse> | Resulting capacity rows |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/phases/b2c3d4e5-f6a7-8901-bcde-f12345678901/assignment-groups/a7b8c9d0-e1f2-3456-0123-567890123456/capacities \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"capacities": [{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "max_items": 5}]}'Response
200 OK[
{
"phase_assignment_group_id": "33334444-5555-6666-7777-88889999aaaa",
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"max_items": 5
}
]/api/v1/workflows/workflows/{workflow_id}/assignment-capacitiesList Workflow Capacities
Return every per-(binding, principal) capacity row in the workflow. Powers the member x phase capacity matrix.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | array<CapacityResponse> | Capacity rows |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/assignment-capacities" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"phase_assignment_group_id": "33334444-5555-6666-7777-88889999aaaa",
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"max_items": 5
}
]Saved Views
Saved views are filtered, scoped projections over a workflow's items. A view pins a set of phases, a field projection, locked filters, and a default layout, then reads items/fields/records constrained to that scope. Views are created and listed under a workflow; individual views are read, updated, deleted, favorited, and queried by id.
/api/v1/workflows/workflow-views/{view_id}Get View
Return a single saved view with its config and the caller's capabilities.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | View ID |
workflow_id* | UUID | Owning workflow |
name* | string | View name |
type* | string | View type (e.g. board) |
config* | object (WorkflowViewConfig) | View configuration (layouts, projected fields/phases, locked filters) |
created_at* | datetime | Creation time |
created_by | UUID | null | Creating principal |
is_favorite | boolean | Whether the caller favorited the viewDefault: false |
position | integer | Default tab orderDefault: 0 |
user_position | integer | null | Caller's per-user tab order override |
capabilities | object | Caller's capability flags for this view |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "f6a7b8c9-d0e1-2345-6789-012345678901",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "My open tasks",
"type": "board",
"config": {
"default_layout": "kanban",
"allowed_layouts": ["kanban", "table"],
"fields": [{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "visible": true}],
"phases": [{"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "position": 0, "filters": []}],
"global_filters": [
{"operator": "eq", "system_field": "assigned_to", "value": "77778888-9999-aaaa-bbbb-ccccddddeeee", "value_labels": "Me"}
],
"sort": "created_at",
"icon": "inbox"
},
"is_favorite": true,
"position": 0,
"user_position": 1,
"created_by": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"created_at": "2026-06-01T12:00:00Z",
"capabilities": {"can_edit": true, "can_view_items": true, "can_create_items": true, "creatable_phase_ids": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]}
}/api/v1/workflows/workflow-views/{view_id}Update View
Update a view's name, type, position, or config (layouts, fields, phases, filters). Name, type, position and non-filter config changes require views:edit, filter changes require views:filters:edit, and a request that changes nothing requires either.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name (1-200 chars) |
type | string | null | New view type |
position | integer | null | New default tab order |
config | object (WorkflowViewConfig) | null | Replacement view config |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | View ID |
workflow_id* | UUID | Owning workflow |
name* | string | View name |
type* | string | View type (e.g. board) |
config* | object (WorkflowViewConfig) | View configuration (layouts, projected fields/phases, locked filters) |
created_at* | datetime | Creation time |
created_by | UUID | null | Creating principal |
is_favorite | boolean | Whether the caller favorited the viewDefault: false |
position | integer | Default tab orderDefault: 0 |
user_position | integer | null | Caller's per-user tab order override |
capabilities | object | Caller's capability flags for this view |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901 \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "My open tasks", "config": {"default_layout": "table"}}'Response
200 OK{
"id": "f6a7b8c9-d0e1-2345-6789-012345678901",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "My open tasks",
"type": "board",
"config": {
"default_layout": "kanban",
"allowed_layouts": ["kanban", "table"],
"fields": [{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "visible": true}],
"phases": [{"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "position": 0, "filters": []}],
"global_filters": [
{"operator": "eq", "system_field": "assigned_to", "value": "77778888-9999-aaaa-bbbb-ccccddddeeee", "value_labels": "Me"}
],
"sort": "created_at",
"icon": "inbox"
},
"is_favorite": true,
"position": 0,
"user_position": 1,
"created_by": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"created_at": "2026-06-01T12:00:00Z",
"capabilities": {"can_edit": true, "can_view_items": true, "can_create_items": true, "creatable_phase_ids": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]}
}/api/v1/workflows/workflow-views/{view_id}Delete View
Delete a saved view. Items are unaffected; only the projection is removed. Remaining non-expired view-export artifacts are purged first.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901 \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/workflow-views/{view_id}/favoriteSet View Favorite
Toggle the caller's favorite flag on a view. Returns the updated view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
Request Body
| Name | Type | Description |
|---|---|---|
is_favorite* | boolean | Whether to favorite the view |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | View ID |
workflow_id* | UUID | Owning workflow |
name* | string | View name |
type* | string | View type (e.g. board) |
config* | object (WorkflowViewConfig) | View configuration (layouts, projected fields/phases, locked filters) |
created_at* | datetime | Creation time |
created_by | UUID | null | Creating principal |
is_favorite | boolean | Whether the caller favorited the viewDefault: false |
position | integer | Default tab orderDefault: 0 |
user_position | integer | null | Caller's per-user tab order override |
capabilities | object | Caller's capability flags for this view |
curl -X PUT https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/favorite \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"is_favorite": true}'Response
200 OK{
"id": "f6a7b8c9-d0e1-2345-6789-012345678901",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "My open tasks",
"type": "board",
"config": {
"default_layout": "kanban",
"allowed_layouts": ["kanban", "table"],
"fields": [{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "visible": true}],
"phases": [{"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "position": 0, "filters": []}],
"global_filters": [
{"operator": "eq", "system_field": "assigned_to", "value": "77778888-9999-aaaa-bbbb-ccccddddeeee", "value_labels": "Me"}
],
"sort": "created_at",
"icon": "inbox"
},
"is_favorite": true,
"position": 0,
"user_position": 1,
"created_by": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"created_at": "2026-06-01T12:00:00Z",
"capabilities": {"can_edit": true, "can_view_items": true, "can_create_items": true, "creatable_phase_ids": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]}
}/api/v1/workflows/workflows/{workflow_id}/viewsList Views
List the saved views the caller can see for a workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | View ID |
workflow_id* | UUID | Owning workflow |
name* | string | View name |
type* | string | View type (e.g. board) |
config* | object (WorkflowViewConfig) | View configuration (layouts, projected fields/phases, locked filters) |
created_at* | datetime | Creation time |
created_by | UUID | null | Creating principal |
is_favorite | boolean | Whether the caller favorited the viewDefault: false |
position | integer | Default tab orderDefault: 0 |
user_position | integer | null | Caller's per-user tab order override |
capabilities | object | Caller's capability flags for this view |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/views" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "f6a7b8c9-d0e1-2345-6789-012345678901",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "My open tasks",
"type": "board",
"config": {"default_layout": "kanban", "phases": [{"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "position": 0}]},
"is_favorite": true,
"position": 0,
"user_position": 0,
"created_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/workflows/{workflow_id}/viewsCreate View
Create a saved view scoped to a workflow's phases, fields, and locked filters.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | View name (1-200 chars) |
type | string | View typeDefault: board |
config | object (WorkflowViewConfig) | View configuration (layouts, projected fields/phases, locked filters) |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | View ID |
workflow_id* | UUID | Owning workflow |
name* | string | View name |
type* | string | View type (e.g. board) |
config* | object (WorkflowViewConfig) | View configuration (layouts, projected fields/phases, locked filters) |
created_at* | datetime | Creation time |
created_by | UUID | null | Creating principal |
is_favorite | boolean | Whether the caller favorited the viewDefault: false |
position | integer | Default tab orderDefault: 0 |
user_position | integer | null | Caller's per-user tab order override |
capabilities | object | Caller's capability flags for this view |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/views \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "My open tasks", "type": "board", "config": {"default_layout": "kanban", "phases": [{"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "position": 0}]}}'Response
201 Created{
"id": "f6a7b8c9-d0e1-2345-6789-012345678901",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "My open tasks",
"type": "board",
"config": {
"default_layout": "kanban",
"allowed_layouts": ["kanban", "table"],
"fields": [{"field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "visible": true}],
"phases": [{"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "position": 0, "filters": []}],
"global_filters": [
{"operator": "eq", "system_field": "assigned_to", "value": "77778888-9999-aaaa-bbbb-ccccddddeeee", "value_labels": "Me"}
],
"sort": "created_at",
"icon": "inbox"
},
"is_favorite": true,
"position": 0,
"user_position": 1,
"created_by": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"created_at": "2026-06-01T12:00:00Z",
"capabilities": {"can_edit": true, "can_view_items": true, "can_create_items": true, "creatable_phase_ids": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]}
}/api/v1/workflows/workflows/{workflow_id}/views/orderReorder Views
Set the caller's per-user tab order (position overrides) for a workflow's views.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
order | array<ViewOrderEntry> | Per-user tab order overrides (max 200) |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | View ID |
workflow_id* | UUID | Owning workflow |
name* | string | View name |
type* | string | View type (e.g. board) |
config* | object (WorkflowViewConfig) | View configuration (layouts, projected fields/phases, locked filters) |
created_at* | datetime | Creation time |
created_by | UUID | null | Creating principal |
is_favorite | boolean | Whether the caller favorited the viewDefault: false |
position | integer | Default tab orderDefault: 0 |
user_position | integer | null | Caller's per-user tab order override |
capabilities | object | Caller's capability flags for this view |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/views/order \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"order": [{"view_id": "f6a7b8c9-d0e1-2345-6789-012345678901", "position": 0}, {"view_id": "0b1c2d3e-4f5a-6789-0abc-def123456789", "position": 1}]}'Response
200 OK[
{"id": "f6a7b8c9-d0e1-2345-6789-012345678901", "name": "My open tasks", "user_position": 0},
{"id": "0b1c2d3e-4f5a-6789-0abc-def123456789", "name": "Backlog", "user_position": 1}
]/api/v1/workflows/workflows/{workflow_id}/views/all/itemsList All View Items
List items across all of the workflow's views the caller can see, paginated.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<ItemListItem> | Page of items |
total* | integer | Total matching items |
limit* | integer | Page size |
offset* | integer | Page offset |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/views/all/items" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"title": "Investigate latency spike",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"is_visible": true,
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}/api/v1/workflows/workflows/{workflow_id}/views/all/items/queryQuery All View Items
Filtered, paginated item listing across the workflow's views. Search matches title, description, current phase, assignee, caller-visible field values, a full UUID, or the UI code form #XXXXXXXX. Structured filters match fields by field_id with the full type-aware operator set.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
search | string | null | Title, description, current phase, assignee, caller-visible field value, full item UUID, or #XXXXXXXX item code (max 500 chars) |
phase_ids | array<UUID> | null | Restrict to these phases |
assigned | string (yes | no) | null | Filter by assignment state |
assigned_to | UUID | null | Filter by assignee |
filters | array<ItemFieldFilter> | AND-combined locked filters. Each entry targets a configured field_id or a system_field column. |
sort | string | Sort fieldDefault: created_at |
sort_dir | string (asc | desc) | Sort directionDefault: desc |
limit | integer | Page size (0–500). 0 returns the first 500 items; total still reports the full countDefault: 50 |
offset | integer | Offset for paginationDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<ItemListItem> | Page of items |
total* | integer | Total matching items |
limit* | integer | Page size |
offset* | integer | Page offset |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/views/all/items/query \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"search": "latency", "filters": [{"operator": "eq", "field_id": "d4e5f6a7-b8c9-0123-def0-234567890123", "value": "open"}], "limit": 50}'Response
200 OK{
"items": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"title": "Investigate latency spike",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}/api/v1/workflows/workflow-views/{view_id}/phasesList View Phases
List the phases exposed by a view, in view order.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Phase ID |
workflow_id* | UUID | Owning workflow |
name* | string | Phase name |
description* | string | null | Description |
position* | integer | Order within the workflow |
color | string | Display colorDefault: #3b82f6 |
is_terminal | boolean | Whether this is an end phaseDefault: false |
kind* | string | `standard` or `exception`. A view shows the exception phase only when its phase list includes it.Default: standard |
allow_create_items | boolean | Whether items can be created hereDefault: true |
item_count | integer | Items currently in the phaseDefault: 0 |
field_count | integer | Phase-scoped fieldsDefault: 0 |
max_assignees_per_item | integer | null | Assignee cap per item |
timeout_minutes | number | null | Phase timeout |
timeout_target_phase_id | UUID | null | Phase items move to on timeout |
created_at* | datetime | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/phases" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Triage",
"description": null,
"position": 0,
"color": "#3b82f6",
"is_terminal": false,
"kind": "standard",
"item_count": 12,
"created_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/workflow-views/{view_id}/routesList View Routes
List the workflow routes leaving the view's phases the caller can see, including routes whose target phase is outside the view (moving an item along one takes it out of the view). These are exactly the moves Route View Item accepts; cross-workflow routes are excluded.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Route ID |
workflow_id* | UUID | Owning workflow |
from_phase_id* | UUID | Source phase |
from_phase_name* | string | Source phase name |
to_phase_id* | UUID | Destination phase |
to_phase_name* | string | Destination phase name |
annotation | string | null | Route label |
carry_assignment | boolean | Keep the assignee across the moveDefault: true |
cross_workflow | boolean | Whether the route crosses workflowsDefault: false |
required_field_ids | array<UUID> | Fields required before routing |
to_workflow_id | UUID | null | Destination workflow (cross-workflow routes) |
to_workflow_name | string | null | Destination workflow name |
created_at* | datetime | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/routes" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"from_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"from_phase_name": "Triage",
"to_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"to_phase_name": "In Progress",
"annotation": "Start work",
"carry_assignment": true,
"cross_workflow": false,
"required_field_ids": [],
"created_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/workflow-views/{view_id}/claimersList View Claimers
Principals who may claim items through this view — the pool behind the view board's claimer avatar quick-filter.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_id* | string | Principal ID |
principal_type* | string | Principal type (user, group, service, ...) |
label* | string | Display label |
display_name | string | null | Display name |
avatar_url | string | null | Avatar URL |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/claimers" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"principal_type": "user",
"label": "Ada Lovelace",
"display_name": "Ada Lovelace",
"avatar_url": null
}
]/api/v1/workflows/workflow-views/{view_id}/fieldsList View Fields
Field definitions for the view's detail/create forms — workflow fields plus the view's phase fields, filtered to the caller's visible fields and annotated with can_edit_value.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Field ID |
name* | string | Field name |
field_type* | string | Field data type |
required* | boolean | Whether the field is required |
is_list* | boolean | Whether the field accepts multiple values |
options* | object | null | Type-specific options (select choices, record source, ...) |
editable_from_phase_ids* | array<UUID> | null | Phases the field is editable from |
position* | integer | Display order |
phase_id | UUID | null | Phase the field belongs to (null = workflow field) |
workflow_id | UUID | null | Owning workflow |
description | string | null | Description |
show_on_card | boolean | Whether shown on the cardDefault: false |
can_edit_value | boolean | null | Whether the caller may edit this field's value through the view |
created_at* | datetime | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/fields" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Status",
"field_type": "select",
"required": true,
"is_list": false,
"options": {"choices": ["open", "closed"]},
"editable_from_phase_ids": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"],
"position": 0,
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"show_on_card": true,
"can_edit_value": true,
"created_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/workflow-views/{view_id}/fields/{field_id}/records/searchSearch View Records
Typeahead for a record field through a view. Results are restricted to the view's locked eq/in value-set on the field (when present); cascade dependencies are applied on top.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
field_id* | string (UUID) | Record field ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
q | string | Search text |
limit | integer | Max results (1-100)Default: 20 |
deps | string (JSON) | null | JSON object mapping dependency source field IDs to their current value |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/fields/d4e5f6a7-b8c9-0123-def0-234567890123/records/search?q=acme&limit=20" \
-H "Authorization: Bearer {token}"Response
200 OK{
"results": [
{"id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff", "label": "Acme Corp"}
]
}/api/v1/workflows/workflow-views/{view_id}/fields/{field_id}/records/{row_id}Get View Record
Resolve a single linked row through a view; the row must satisfy the view's locked filters.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
field_id* | string (UUID) | Record field ID |
row_id* | string | Linked row ID |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/fields/d4e5f6a7-b8c9-0123-def0-234567890123/records/88889999-aaaa-bbbb-cccc-ddddeeeeffff" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff",
"label": "Acme Corp",
"values": {"name": "Acme Corp", "tier": "enterprise"}
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/fields/{field_id}/records/{row_id}Update View Record Cells
Edit cells of an item's linked row through a view. The item must be in the view, the caller must be able to edit the record field through it, and the row must pass the view's locked filters on the field (404 otherwise); otherwise the same rules as Update Record Cells apply, including a null cell_values when the row cannot be read back.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
item_id* | string (UUID) | Item ID |
field_id* | string (UUID) | Record field ID |
row_id* | string (UUID) | Linked row ID |
Request Body
| Name | Type | Description |
|---|---|---|
cell_values* | array | Cells to write: column_id (an editable column of the field) and value. |
curl -X PATCH "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/{item_id}/fields/d4e5f6a7-b8c9-0123-def0-234567890123/records/88889999-aaaa-bbbb-cccc-ddddeeeeffff" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"cell_values": [{"column_id": "col-uuid", "value": "enterprise"}]}'Response
200 OK{
"id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff",
"cell_values": [{"column_id": "col-uuid", "value": "enterprise"}]
}/api/v1/workflows/workflow-views/{view_id}/fields/{field_id}/records/columns/{column_id}/optionsList View Record Reference Options
Typeahead the rows an editable reference column of a record field can point at, through a view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | View ID |
field_id* | string (UUID) | Record field ID |
column_id* | string (UUID) | Reference column ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
q | string | Search text |
limit | integer | Max results (1-100)Default: 20 |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/fields/d4e5f6a7-b8c9-0123-def0-234567890123/records/columns/col-uuid/options?q=sp" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [{"row_id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff", "display_value": "São Paulo"}],
"has_more": false
}View Items
Item operations performed through a saved view's scope. The view constrains which items are visible and which fields can be read or edited: creates (including child creation with parent_item_id) and edits are re-checked against the view's locked filters (422 if the item would fall outside), field writes are restricted to the caller's editable view fields, and assign/claim/release/route are authorized view-relative rather than at the workflow level.
/api/v1/workflows/workflow-views/{view_id}/itemsList View Items
List items visible through a saved view, with search, assignment filter, sorting, and pagination. Search matches title, description, current phase, assignee, caller-visible field values, a full UUID, or the UI code form #XXXXXXXX.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
search | string | null | Title, description, current phase, assignee, caller-visible field value, full item UUID, or #XXXXXXXX item code (max 500 chars) |
assigned_to | UUID | null | Filter by assignee principal |
sort | string | Sort fieldDefault: created_at |
sort_dir | string | Sort direction (asc | desc)Default: desc |
limit | integer | Page size (0–500). 0 returns the first 500 items; total still reports the full countDefault: 50 |
offset | integer | Offset for paginationDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<ItemListItem> | Page of items visible through the view |
total* | integer | Total matching items |
limit* | integer | Page size |
offset* | integer | Page offset |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items?limit=50&offset=0" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"title": "Refund request #4821",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"workflow_name": "Support queue",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": null,
"assigned_at": "2026-06-02T09:30:00Z",
"assignees": [{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "is_primary": true, "assigned_at": "2026-06-02T09:30:00Z", "assigned_via_group_id": null}],
"card_fields": [{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "name": "Priority", "field_type": "select", "is_list": false, "description": null, "values": [{"value": "high", "bg": "#fee2e2", "text": "#991b1b"}]}],
"is_visible": true
}
],
"total": 1,
"limit": 50,
"offset": 0
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}Get View Item
Return a single item through a saved view, with field values restricted to the view's visible fields.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | UUID | null | Primary assignee |
assigned_group_id | UUID | null | Assigned group |
assigned_at | datetime | null | When assigned |
released_at | datetime | null | When last released |
assignees | array<AssigneeRef> | Assignee seats |
field_values | array<FieldValueResponse> | Item field values (restricted to view-visible fields) |
card_fields | array<CardField> | show_on_card field values rendered as tags |
visible_field_ids | array<string> | null | Field IDs the caller may see through the view |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | Global clock start time |
visible_after | datetime | null | Item becomes visible after this time |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer requests a refund for order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": null,
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "is_primary": true, "assigned_at": "2026-06-02T09:30:00Z", "assigned_via_group_id": null}
],
"field_values": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "field_name": "Priority", "value": "high"}
],
"card_fields": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "name": "Priority", "field_type": "select", "is_list": false, "description": null, "values": [{"value": "high", "bg": "#fee2e2", "text": "#991b1b"}]}
],
"visible_field_ids": ["44445555-6666-7777-8888-9999aaaabbbb"],
"phase_has_assignment_group": false,
"timeout_minutes": null,
"global_timeout_minutes": null,
"global_clock_started_at": null,
"visible_after": null,
"visibility_timeout_on_create_minutes": null,
"visibility_timeout_on_release_minutes": null,
"visibility_timeout_on_transition_minutes": null
}/api/v1/workflows/workflow-views/{view_id}/itemsCreate View Item
Create an item through a view, optionally linking it atomically as a child of parent_item_id. The target phase and parent must be exposed by the same view. Concrete locked filter values are seeded when omitted, and the complete view predicate is re-checked before commit; a non-matching child is rejected (422) and rolled back.
Bearer token required. Requires views:items:create on the target view phase. Supplying parent_item_id also requires views:child-items:create on the parent's exposed view phase.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
Request Body
| Name | Type | Description |
|---|---|---|
title* | string | Item title (1–500 chars) |
description | string | null | Item description (max 100000 chars) |
phase_id | UUID | null | Target phase (must be exposed by the view) |
parent_item_id | UUID | null | Parent item visible in this view to link under atomically |
field_values | object | null | Field name → value map (non-editable fields dropped). Keys are field names (not ids or labels); an unknown name is dropped and returned in ignored_fields as unknown_field, with a suggestion limited to fields visible through the view. Each value may serialize to at most 2 MB; a larger value fails the request with 413 and nothing is written. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Ignored by view routes |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Ignored by view routes |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Ignored by view routes |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | UUID | null | Primary assignee |
assigned_group_id | UUID | null | Assigned group |
assigned_at | datetime | null | When assigned |
released_at | datetime | null | When last released |
assignees | array<AssigneeRef> | Assignee seats |
field_values | array<FieldValueResponse> | Item field values (restricted to view-visible fields) |
card_fields | array<CardField> | show_on_card field values rendered as tags |
visible_field_ids | array<string> | null | Field IDs the caller may see through the view |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | Global clock start time |
visible_after | datetime | null | Item becomes visible after this time |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"title": "Refund request #4821", "phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "field_values": {"Priority": "high"}}'Response
201 Created{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer requests a refund for order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": null,
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "is_primary": true, "assigned_at": "2026-06-02T09:30:00Z", "assigned_via_group_id": null}
],
"field_values": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "field_name": "Priority", "value": "high"}
],
"card_fields": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "name": "Priority", "field_type": "select", "is_list": false, "description": null, "values": [{"value": "high", "bg": "#fee2e2", "text": "#991b1b"}]}
],
"visible_field_ids": ["44445555-6666-7777-8888-9999aaaabbbb"],
"phase_has_assignment_group": false,
"timeout_minutes": null,
"global_timeout_minutes": null,
"global_clock_started_at": null,
"visible_after": null,
"visibility_timeout_on_create_minutes": null,
"visibility_timeout_on_release_minutes": null,
"visibility_timeout_on_transition_minutes": null
}/api/v1/workflows/workflow-views/{view_id}/items/queryQuery View Items
Filtered, paginated item listing through a view. Search matches title, description, current phase, assignee, caller-visible field values, a full UUID, or the UI code form #XXXXXXXX. Filters match by field_id (not name, which collides across phases) and support the full type-aware operator set, including dotted path access into json field values.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
Request Body
| Name | Type | Description |
|---|---|---|
filters | array<ItemFieldFilter> | AND-combined filters (max 30) |
search | string | null | Title, description, current phase, assignee, caller-visible field value, full item UUID, or #XXXXXXXX item code (max 500 chars) |
assigned | string | null | Assignment presence filter (yes | no) |
assigned_to | UUID | null | Filter by assignee principal |
phase_ids | array<UUID> | null | Restrict to specific phases |
sort | string | Sort fieldDefault: created_at |
sort_dir | string | Sort direction (asc | desc)Default: desc |
limit | integer | Page size (0–500). 0 returns the first 500 items; total still reports the full countDefault: 50 |
offset | integer | Offset for paginationDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<ItemListItem> | Page of items visible through the view |
total* | integer | Total matching items |
limit* | integer | Page size |
offset* | integer | Page offset |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/query \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"filters": [{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "operator": "eq", "value": "high"}], "limit": 50}'Response
200 OK{
"items": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"title": "Refund request #4821",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"is_visible": true
}
],
"total": 1,
"limit": 50,
"offset": 0
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}Update View Item
Edit an item's title, description, and fields through a view. By default only the current phase's fields (plus workflow fields) are writable; pass target_phase_id (a phase the view exposes and the caller may edit) to write the destination phase's fields before routing, so a required-on-landing field can be filled first — the same cross-phase branch and missing_required_fields gate as the direct item PATCH. target_phase_id does not bypass the editability allow-list: each destination field must still list the item's current phase in editable_from_phase_ids (403 otherwise). The caller still needs the view-scoped item edit permission and field access. After those IAM checks, the same shared/owned content-edit matrix as the direct item PATCH applies. Cross-phase moves go through the route endpoint, which applies the same shared/owned matrix. Field values remain restricted to the caller's editable view fields; after applying changes the item is re-checked against the view predicate (422 if it would fall out).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
title | string | null | New title (1–500 chars) |
description | string | null | New description (max 100000 chars) |
field_values | object | null | Field name → value map (restricted to editable view fields). Keys are field names (not ids or labels); an unknown name is dropped and returned in ignored_fields as unknown_field, with a suggestion limited to fields visible through the view. Each value may serialize to at most 2 MB; a larger value fails the request with 413 and nothing is written. |
target_phase_id | UUID | null | Destination phase whose fields may be written (must be exposed by the view and editable by the caller; each field must list the current phase in editable_from_phase_ids). The item stays in its current phase; route it afterwards. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Ignored by view routes |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Ignored by view routes |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Ignored by view routes |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | UUID | null | Primary assignee |
assigned_group_id | UUID | null | Assigned group |
assigned_at | datetime | null | When assigned |
released_at | datetime | null | When last released |
assignees | array<AssigneeRef> | Assignee seats |
field_values | array<FieldValueResponse> | Item field values (restricted to view-visible fields) |
card_fields | array<CardField> | show_on_card field values rendered as tags |
visible_field_ids | array<string> | null | Field IDs the caller may see through the view |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | Global clock start time |
visible_after | datetime | null | Item becomes visible after this time |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012 \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"title": "Refund request #4821 (urgent)", "field_values": {"Priority": "critical"}}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer requests a refund for order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": null,
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "is_primary": true, "assigned_at": "2026-06-02T09:30:00Z", "assigned_via_group_id": null}
],
"field_values": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "field_name": "Priority", "value": "high"}
],
"card_fields": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "name": "Priority", "field_type": "select", "is_list": false, "description": null, "values": [{"value": "high", "bg": "#fee2e2", "text": "#991b1b"}]}
],
"visible_field_ids": ["44445555-6666-7777-8888-9999aaaabbbb"],
"phase_has_assignment_group": false,
"timeout_minutes": null,
"global_timeout_minutes": null,
"global_clock_started_at": null,
"visible_after": null,
"visibility_timeout_on_create_minutes": null,
"visibility_timeout_on_release_minutes": null,
"visibility_timeout_on_transition_minutes": null
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}Delete View Item
Delete an item through a saved view. Returns 204 No Content on success.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012 \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/assignable-principalsList View Item Assignable Principals
List principals assignable to an item through a saved view. The caller must be able to assign items on the view; returned targets are principals that can claim items on the same view (team grants expanded to concrete members) and are narrowed by matching assignment-group bindings for the item.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal type |
principal_id* | UUID | Principal ID |
label* | string | Display label |
via_team_id | UUID | null | Team principal ID when this concrete member was surfaced through a team grant |
eligible | boolean | null | Advisory target eligibility; assignment re-checks authoritatively |
curl https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/assignable-principals \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_type": "team",
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"label": "Creta Squad",
"via_team_id": null,
"eligible": null
},
{
"principal_type": "member",
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"label": "member@example.com",
"via_team_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"eligible": true
}
]/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/form-contextGet View Item Form Context
Return a saved-view-locked item and its complete current form in one response. Phase fields, workflow fields, rules, and record labels are filtered by both the view projection and the caller's view-scoped permissions.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID in the view |
Response Fields
| Name | Type | Description |
|---|---|---|
item* | ItemResponse | View-filtered item and field values |
phase_fields* | array<FieldResponse> | Visible current-phase fields |
workflow_fields* | array<FieldResponse> | Visible workflow-level fields |
field_rules* | array<FieldRuleResponse> | Applicable field rules the caller may view |
record_labels* | object | Field ID to selected row ID to resolved display label |
curl https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/form-context \
-H "Authorization: Bearer {token}"Response
200 OK{
"item": {"id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "title": "Refund request #4821", "field_values": []},
"phase_fields": [],
"workflow_fields": [],
"field_rules": [],
"record_labels": {}
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/assignAssign View Item
Assign an item to a principal through a saved view (view-scoped).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_id* | UUID | Principal to assign the item to |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | UUID | null | Primary assignee |
assigned_group_id | UUID | null | Assigned group |
assigned_at | datetime | null | When assigned |
released_at | datetime | null | When last released |
assignees | array<AssigneeRef> | Assignee seats |
field_values | array<FieldValueResponse> | Item field values (restricted to view-visible fields) |
card_fields | array<CardField> | show_on_card field values rendered as tags |
visible_field_ids | array<string> | null | Field IDs the caller may see through the view |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | Global clock start time |
visible_after | datetime | null | Item becomes visible after this time |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/assign \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer requests a refund for order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": null,
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "is_primary": true, "assigned_at": "2026-06-02T09:30:00Z", "assigned_via_group_id": null}
],
"field_values": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "field_name": "Priority", "value": "high"}
],
"card_fields": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "name": "Priority", "field_type": "select", "is_list": false, "description": null, "values": [{"value": "high", "bg": "#fee2e2", "text": "#991b1b"}]}
],
"visible_field_ids": ["44445555-6666-7777-8888-9999aaaabbbb"],
"phase_has_assignment_group": false,
"timeout_minutes": null,
"global_timeout_minutes": null,
"global_clock_started_at": null,
"visible_after": null,
"visibility_timeout_on_create_minutes": null,
"visibility_timeout_on_release_minutes": null,
"visibility_timeout_on_transition_minutes": null
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/claimClaim View Item
Claim an item through a saved view (view-scoped pickup). The eligibility check evaluates the view-scoped claim permission on the view resource rather than on the phase; seat/headcount semantics match the board claim.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | UUID | null | Primary assignee |
assigned_group_id | UUID | null | Assigned group |
assigned_at | datetime | null | When assigned |
released_at | datetime | null | When last released |
assignees | array<AssigneeRef> | Assignee seats |
field_values | array<FieldValueResponse> | Item field values (restricted to view-visible fields) |
card_fields | array<CardField> | show_on_card field values rendered as tags |
visible_field_ids | array<string> | null | Field IDs the caller may see through the view |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | Global clock start time |
visible_after | datetime | null | Item becomes visible after this time |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/claim \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer requests a refund for order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": null,
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "is_primary": true, "assigned_at": "2026-06-02T09:30:00Z", "assigned_via_group_id": null}
],
"field_values": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "field_name": "Priority", "value": "high"}
],
"card_fields": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "name": "Priority", "field_type": "select", "is_list": false, "description": null, "values": [{"value": "high", "bg": "#fee2e2", "text": "#991b1b"}]}
],
"visible_field_ids": ["44445555-6666-7777-8888-9999aaaabbbb"],
"phase_has_assignment_group": false,
"timeout_minutes": null,
"global_timeout_minutes": null,
"global_clock_started_at": null,
"visible_after": null,
"visibility_timeout_on_create_minutes": null,
"visibility_timeout_on_release_minutes": null,
"visibility_timeout_on_transition_minutes": null
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/releaseRelease View Item
Remove one assignee seat through a saved view. Pass principal_id to remove that specific assignee; omit it for self-release. A non-holder must provide principal_id, and only removing the final seat emits workflows.items.released. A full release hides the item for the phase release cooldown. On a phase with max_attempts, a full release of a stay that has used its last attempt moves the item to Exceptions instead (source system, reason attempt_limit_reached) and may leave the view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_id | string (UUID) | null | Specific assignee to remove; omit for self-release |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | UUID | null | Primary assignee |
assigned_group_id | UUID | null | Assigned group |
assigned_at | datetime | null | When assigned |
released_at | datetime | null | When last released |
assignees | array<AssigneeRef> | Assignee seats |
field_values | array<FieldValueResponse> | Item field values (restricted to view-visible fields) |
card_fields | array<CardField> | show_on_card field values rendered as tags |
visible_field_ids | array<string> | null | Field IDs the caller may see through the view |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | Global clock start time |
visible_after | datetime | null | Item becomes visible after this time |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/release \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer requests a refund for order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": null,
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "is_primary": true, "assigned_at": "2026-06-02T09:30:00Z", "assigned_via_group_id": null}
],
"field_values": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "field_name": "Priority", "value": "high"}
],
"card_fields": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "name": "Priority", "field_type": "select", "is_list": false, "description": null, "values": [{"value": "high", "bg": "#fee2e2", "text": "#991b1b"}]}
],
"visible_field_ids": ["44445555-6666-7777-8888-9999aaaabbbb"],
"phase_has_assignment_group": false,
"timeout_minutes": null,
"global_timeout_minutes": null,
"global_clock_started_at": null,
"visible_after": null,
"visibility_timeout_on_create_minutes": null,
"visibility_timeout_on_release_minutes": null,
"visibility_timeout_on_transition_minutes": null
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/extend-claimExtend View Item Claim
Push back the claim expiry of an item through a saved view, like Extend Claim on the board. Requires views:items:claim on the view; the caller must hold the item.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
seconds | integer | null | New claim length in seconds; defaults to the phase claim timeout |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | UUID | null | Primary assignee |
assigned_group_id | UUID | null | Assigned group |
assigned_at | datetime | null | When assigned |
released_at | datetime | null | When last released |
assignees | array<AssigneeRef> | Assignee seats |
field_values | array<FieldValueResponse> | Item field values (restricted to view-visible fields) |
card_fields | array<CardField> | show_on_card field values rendered as tags |
visible_field_ids | array<string> | null | Field IDs the caller may see through the view |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | Global clock start time |
visible_after | datetime | null | Item becomes visible after this time |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/extend-claim \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"seconds": 600}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer requests a refund for order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": null,
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "is_primary": true, "assigned_at": "2026-06-02T09:30:00Z", "assigned_via_group_id": null}
],
"field_values": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "field_name": "Priority", "value": "high"}
],
"card_fields": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "name": "Priority", "field_type": "select", "is_list": false, "description": null, "values": [{"value": "high", "bg": "#fee2e2", "text": "#991b1b"}]}
],
"visible_field_ids": ["44445555-6666-7777-8888-9999aaaabbbb"],
"phase_has_assignment_group": false,
"timeout_minutes": null,
"global_timeout_minutes": null,
"global_clock_started_at": null,
"visible_after": null,
"visibility_timeout_on_create_minutes": null,
"visibility_timeout_on_release_minutes": null,
"visibility_timeout_on_transition_minutes": null
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/deferDefer View Item
Hand a held item back to its phase through a saved view, hidden for delay_seconds, like Defer Item on the board. On the stay's last allowed attempt the item moves to Exceptions instead and may leave the view. A hold that no claim counted (assign, group auto-assign, a seat carried by a route) counts as an attempt when it fails or defers. Requires views:items:claim on the view; the caller must hold the item.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
delay_seconds* | integer | Seconds the item stays hidden (1-604800); a phase with defer_max_seconds rejects longer delays with 400 defer_exceeds_max |
reason | string | null | Why the item was deferred |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | UUID | null | Primary assignee |
assigned_group_id | UUID | null | Assigned group |
assigned_at | datetime | null | When assigned |
released_at | datetime | null | When last released |
assignees | array<AssigneeRef> | Assignee seats |
field_values | array<FieldValueResponse> | Item field values (restricted to view-visible fields) |
card_fields | array<CardField> | show_on_card field values rendered as tags |
visible_field_ids | array<string> | null | Field IDs the caller may see through the view |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | Global clock start time |
visible_after | datetime | null | Item becomes visible after this time |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/defer \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"delay_seconds": 3600}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer requests a refund for order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": null,
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "is_primary": true, "assigned_at": "2026-06-02T09:30:00Z", "assigned_via_group_id": null}
],
"field_values": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "field_name": "Priority", "value": "high"}
],
"card_fields": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "name": "Priority", "field_type": "select", "is_list": false, "description": null, "values": [{"value": "high", "bg": "#fee2e2", "text": "#991b1b"}]}
],
"visible_field_ids": ["44445555-6666-7777-8888-9999aaaabbbb"],
"phase_has_assignment_group": false,
"timeout_minutes": null,
"global_timeout_minutes": null,
"global_clock_started_at": null,
"visible_after": null,
"visibility_timeout_on_create_minutes": null,
"visibility_timeout_on_release_minutes": null,
"visibility_timeout_on_transition_minutes": null
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/failFail View Item
Record a failed attempt through a saved view, like Fail Item on the board. At the attempt limit the item moves to Exceptions and may leave the view. A hold that no claim counted (assign, group auto-assign, a seat carried by a route) counts as an attempt when it fails or defers. Requires views:items:claim on the view; the caller must hold the item.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
reason* | string | Why the attempt failed (1-4000 characters) |
details | string | null | Longer diagnostic text |
delay_seconds | integer | null | Retry delay (0-604800); defaults to the phase policy's retry delay, 0 when the phase has none |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | UUID | null | Primary assignee |
assigned_group_id | UUID | null | Assigned group |
assigned_at | datetime | null | When assigned |
released_at | datetime | null | When last released |
assignees | array<AssigneeRef> | Assignee seats |
field_values | array<FieldValueResponse> | Item field values (restricted to view-visible fields) |
card_fields | array<CardField> | show_on_card field values rendered as tags |
visible_field_ids | array<string> | null | Field IDs the caller may see through the view |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | Global clock start time |
visible_after | datetime | null | Item becomes visible after this time |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/fail \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"reason": "upstream returned 503"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer requests a refund for order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": null,
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "is_primary": true, "assigned_at": "2026-06-02T09:30:00Z", "assigned_via_group_id": null}
],
"field_values": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "field_name": "Priority", "value": "high"}
],
"card_fields": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "name": "Priority", "field_type": "select", "is_list": false, "description": null, "values": [{"value": "high", "bg": "#fee2e2", "text": "#991b1b"}]}
],
"visible_field_ids": ["44445555-6666-7777-8888-9999aaaabbbb"],
"phase_has_assignment_group": false,
"timeout_minutes": null,
"global_timeout_minutes": null,
"global_clock_started_at": null,
"visible_after": null,
"visibility_timeout_on_create_minutes": null,
"visibility_timeout_on_release_minutes": null,
"visibility_timeout_on_transition_minutes": null
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/completeComplete View Item
Mark the current stay done through a saved view and follow the phase's declared route, like Complete Item on the board. System routes into Exceptions do not count; the routes out of Exceptions back to each phase do. With one route the item moves along it; with several, target_phase_id picks one (400 ambiguous_route without it, 400 route_not_declared for a phase that is not a route). Unlike the board, the destination must be in the view's workflow; a route into another workflow returns 400. The move runs the exit gate, landing gate and max_passes like a route, and the item may leave the view. With no route the item stays and leaves every claim path until it is routed. Requires views:items:edit on the view; the caller must hold the item.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
reason | string | null | Optional note recorded on the event |
target_phase_id | string (UUID) | null | Destination when several declared routes leave the phase; must be one of them |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | UUID | null | Primary assignee |
assigned_group_id | UUID | null | Assigned group |
assigned_at | datetime | null | When assigned |
released_at | datetime | null | When last released |
assignees | array<AssigneeRef> | Assignee seats |
field_values | array<FieldValueResponse> | Item field values (restricted to view-visible fields) |
card_fields | array<CardField> | show_on_card field values rendered as tags |
visible_field_ids | array<string> | null | Field IDs the caller may see through the view |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | Global clock start time |
visible_after | datetime | null | Item becomes visible after this time |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
diverted | ItemDiversion | null | Set when max_passes sent the item to Exceptions instead of the requested phase (current_phase_id is then the Exceptions phase); null otherwise |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/complete \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"reason": "verified"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"title": "Refund request #4821",
"description": "Customer requests a refund for order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-02T09:30:00Z",
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assigned_group_id": null,
"assigned_at": "2026-06-02T09:30:00Z",
"released_at": null,
"assignees": [
{"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "is_primary": true, "assigned_at": "2026-06-02T09:30:00Z", "assigned_via_group_id": null}
],
"field_values": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "field_name": "Priority", "value": "high"}
],
"card_fields": [
{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "name": "Priority", "field_type": "select", "is_list": false, "description": null, "values": [{"value": "high", "bg": "#fee2e2", "text": "#991b1b"}]}
],
"visible_field_ids": ["44445555-6666-7777-8888-9999aaaabbbb"],
"phase_has_assignment_group": false,
"timeout_minutes": null,
"global_timeout_minutes": null,
"global_clock_started_at": null,
"visible_after": null,
"visibility_timeout_on_create_minutes": null,
"visibility_timeout_on_release_minutes": null,
"visibility_timeout_on_transition_minutes": null,
"diverted": null
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/childrenList View Item Children
List child links for a parent item visible through a saved view. Gated by views:child-items:view on the parent's exposed view phase. Returns 404 when the parent is not in the view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Saved view ID |
item_id* | string (UUID) | Parent item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
(root)* | array<ChildLinkResponse> | The parent's child links |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/children" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"link_id": "bbbbcccc-dddd-eeee-ffff-000011112222",
"child_item_id": "aaaabbbb-cccc-dddd-eeee-ffff00001111",
"title": "Sub-task",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"workflow_name": "Onboarding",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "In progress",
"created_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/children/{child_item_id}Link View Item Child
Link an existing item under a parent through a saved view. Requires views:child-items:create on the parent's exposed view phase, and the child must be visible to the caller: items:view on its phase or views:items:view through any saved view that contains it.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Saved view ID |
item_id* | string (UUID) | Parent item ID |
child_item_id* | string (UUID) | Existing item to link as the child |
Response Fields
| Name | Type | Description |
|---|---|---|
link_id* | UUID | Parent->child link ID |
child_item_id* | UUID | Linked child item ID |
title* | string | Child item title |
workflow_id* | UUID | Workflow the child lives in |
workflow_name* | string | Child's workflow name |
current_phase_id* | UUID | Child's current phase ID |
current_phase_name* | string | Child's current phase name |
created_at* | datetime | When the link was created |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/children/aaaabbbb-cccc-dddd-eeee-ffff00001111" \
-H "Authorization: Bearer {token}"Response
201 Created{
"link_id": "bbbbcccc-dddd-eeee-ffff-000011112222",
"child_item_id": "aaaabbbb-cccc-dddd-eeee-ffff00001111",
"title": "Existing task",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"workflow_name": "Onboarding",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "In progress",
"created_at": "2026-06-01T12:00:00Z"
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/children/{child_item_id}Unlink View Item Child
Remove a parent→child link through a saved view without deleting the child item. Gated by views:child-items:delete on the parent's exposed view phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Saved view ID |
item_id* | string (UUID) | Parent item ID |
child_item_id* | string (UUID) | Child item ID to unlink |
curl -X DELETE "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/children/aaaabbbb-cccc-dddd-eeee-ffff00001111" \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/child-capabilitiesGet View Item Child Capabilities
View-scoped lineage capability flags for UI gating. Loads the parent with views:items:view, then evaluates views:child-items:* against the parent's exposed view phase.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Saved view ID |
item_id* | string (UUID) | Parent item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
can_create* | boolean | May link or spawn child items from this parent through the view |
can_view* | boolean | May view the parent's children through the view |
can_unlink* | boolean | May remove parent→child links through the view |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/child-capabilities" \
-H "Authorization: Bearer {token}"Response
200 OK{
"can_create": true,
"can_view": true,
"can_unlink": false
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/child-targetsList View Item Child Targets
Folder → workflow → phase tree containing only create-enabled phases exposed by this saved view. Children created at these targets use the view item-create path, including locked-filter seeding and final predicate validation.
Bearer token required. Requires views:child-items:create on the parent's exposed view phase; returned targets also require views:items:create.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Saved view ID |
item_id* | string (UUID) | Parent item ID |
Response Fields
| Name | Type | Description |
|---|---|---|
folders | array<ChildTargetNode> | Root folder nodes of the spawn-target treeDefault: [] |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/child-targets" \
-H "Authorization: Bearer {token}"Response
200 OK{
"folders": []
}/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/routeRoute View Item
Route an item to another phase through a saved view. Authorized by the view-scoped edit permission (not the workflow-level route permission), then runs the same engine primitives as board routing. The item must be inside the view (configured phases and locked filters), otherwise 404. The target only needs an explicit workflow route from the current phase, so the item may leave the view when a route allows it. When the route carries assignments, assignees stay if they can claim in the target phase on the board or through a saved view that contains the item there (this view first). Over the target's max_passes, a person (sign-in token or member principal), or anyone moving an item out of Exceptions, gets 409 max_passes_exceeded; any other caller (API key, agent, automation) has the item moved to Exceptions instead and gets 200 with diverted set.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string | Saved view ID |
item_id* | string | Item ID |
Request Body
| Name | Type | Description |
|---|---|---|
to_phase_id* | UUID | Target phase to route the item to |
delay_seconds | integer | null | Keep the item hidden this long after the move (0..604800), if longer than the arrival cooldown. Capped by the destination's defer_max_seconds (400 defer_exceeds_max); not stored on the item |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Item ID |
workflow_id* | UUID | Owning workflow |
current_phase_id* | UUID | Current phase ID |
current_phase_name* | string | Current phase name |
title* | string | Item title |
created_by* | UUID | null | IAM user id of the creator (not an organization principal id). Provenance/audit metadata only; it does not grant content-edit rights. |
created_at* | datetime | Creation time |
updated_at* | datetime | Last update time |
description | string | null | Item description |
assigned_to | UUID | null | Primary assignee |
assigned_group_id | UUID | null | Assigned group |
assigned_at | datetime | null | When assigned |
released_at | datetime | null | When last released |
assignees | array<AssigneeRef> | Assignee seats |
field_values | array<FieldValueResponse> | Item field values (restricted to view-visible fields) |
card_fields | array<CardField> | show_on_card field values rendered as tags |
visible_field_ids | array<string> | null | Field IDs the caller may see through the view |
phase_has_assignment_group | boolean | null | True when at least one assignment-group binding matches this item (owned). False/absent means shared: content stays editable after IAM even if claimed. |
timeout_minutes | number | null | Phase timeout in minutes |
global_timeout_minutes | number | null | Global timeout in minutes |
global_clock_started_at | datetime | null | Global clock start time |
visible_after | datetime | null | Item becomes visible after this time |
visibility_timeout_on_create_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on create; cleared once used |
visibility_timeout_on_release_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next release; cleared once used |
visibility_timeout_on_transition_minutes | integer | null | Deprecated, removed on 2026-11-27. Pending item override for the cooldown on the next phase move; cleared once used |
claim | {owner, expires_at} | null | Claim on a held item: owner is the X-Ergon-Consumer-Id fencing it (null when claimed without one), expires_at when it lapses unless extended. Null when the item has no claim |
processing | object | null | Ledger of the current stay in the phase: pass_id, entered_at, attempt_count, defer_count, fail_count, passes (entries into this phase), last_consumer_id, last_error, next_visible_at, completed_at, exception_at, exception_reason, exhausted_at (the automatic timeout move stopped for this stay, on any phase; exception_reason says why: max_passes_exceeded, route_blocked or target_missing), exhausted_detail (what blocked it: rule_id, gate and fields, missing target), arrival_blocked_at and arrival_blocked_detail (an on-arrival rule matched but could not move the item: reason, rule_id and the same specifics; the timeout scan skips on-arrival rules for the stay while it is set; any item or attachment edit tries the move again, and a field, attachment, rules, phase timeout or route edit clears it), timeout_deadline (when the phase timeout fires for this stay, resolved by the matching timeout rule; null when no wait applies). Null when the stay has no ledger row |
diverted | ItemDiversion | null | Set when max_passes sent the item to Exceptions instead of the requested phase (current_phase_id is then the Exceptions phase); null otherwise |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/f6a7b8c9-d0e1-2345-6789-012345678901/items/c3d4e5f6-a7b8-9012-cdef-123456789012/route \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"to_phase_id": "d4e5f6a7-b8c9-0123-def0-234567890123"}'Response
200 OK{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"current_phase_id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"current_phase_name": "In Review",
"title": "Refund request #4821",
"description": "Customer requests a refund for order 4821.",
"created_by": "99991111-2222-4333-8444-555566667777",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-03T08:15:00Z",
"assigned_to": null,
"assigned_group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"assigned_at": null,
"released_at": "2026-06-03T08:15:00Z",
"assignees": [],
"field_values": [{"field_id": "44445555-6666-7777-8888-9999aaaabbbb", "field_name": "Priority", "value": "high"}],
"card_fields": [],
"visible_field_ids": ["44445555-6666-7777-8888-9999aaaabbbb"],
"phase_has_assignment_group": true,
"timeout_minutes": null,
"global_timeout_minutes": null,
"global_clock_started_at": null,
"visible_after": null,
"visibility_timeout_on_create_minutes": null,
"visibility_timeout_on_release_minutes": null,
"visibility_timeout_on_transition_minutes": null,
"diverted": null
}View Access
Manage who can use a workflow view and what they can do with it. Inspect the principals eligible for access, the grants currently in effect, and the permissions and resource types available to grant, then create or revoke individual grants.
/api/v1/workflows/workflow-views/{view_id}/access/eligibleList Eligible Principals
Return the principals (members, roles, agents, etc.) that can be granted access to the view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Workflow view ID |
Response Fields
| Name | Type | Description |
|---|---|---|
(root)* | array<EligiblePrincipal> | Principals eligible to receive access to the view |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/eligible" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_type": "member",
"principal_id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff",
"label": "Ada Lovelace",
"display_name": "Ada Lovelace",
"avatar_url": null
}
]/api/v1/workflows/workflow-views/{view_id}/access/grantsList Grants
Return the access grants currently in effect on the view, paginated.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Workflow view ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (minimum 1)Default: 1 |
limit | integer | Items per page (1–500)Default: 100 |
Response Fields
| Name | Type | Description |
|---|---|---|
(root)* | object | Paginated grant listing payload |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/grants?page=1&limit=100" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "11112222-3333-4444-5555-66667777aaaa",
"permission_id": "perm_view_items",
"name": "View Items",
"resource": "workflow-view:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"effect": "allow",
"is_system": false,
"granted_at": "2026-06-01T12:00:00Z"
}
],
"page": 1,
"limit": 100,
"total": 1
}/api/v1/workflows/workflow-views/{view_id}/access/permissionsList Permissions
Return the permissions that can be granted on the view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Workflow view ID |
Response Fields
| Name | Type | Description |
|---|---|---|
(root)* | array<PermissionOption> | Permissions available to grant on the view |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/permissions" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "perm_view_items",
"name": "views:items:view",
"friendly_name": "View Items",
"friendly_name_singular": "View Item",
"friendly_name_plural": "View Items",
"description": "Can view items through this view",
"description_singular": null,
"description_plural": null,
"resource_type_id": null,
"parent_resource_type_slug": null,
"scope_anchor": "instance",
"display_order": 0
}
]/api/v1/workflows/workflow-views/{view_id}/access/resource-typesList Resource Types
Return the resource-type tree and permissions available for scoping grants on the view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Workflow view ID |
Response Fields
| Name | Type | Description |
|---|---|---|
resource_types* | array<ResourceTypeNode> | Hierarchy of resource types that grants can target |
permissions* | array<PermissionOption> | Permissions associated with the resource types |
curl "https://platform.ergondata.ai/api/v1/workflows/workflow-views/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/resource-types" \
-H "Authorization: Bearer {token}"Response
200 OK{
"resource_types": [
{
"id": "rt_view",
"name": "Workflow View",
"slug": "workflow-view",
"parent_id": null,
"children": []
}
],
"permissions": [
{
"id": "perm_view_items",
"name": "views:items:view",
"friendly_name": "View Items",
"scope_anchor": "instance",
"display_order": 0
}
]
}/api/v1/workflows/workflow-views/{view_id}/access/grantsCreate Grant
Grant a principal a permission on the saved view. Agent-callable ToolDef slug: workflows.view_access_grants.create.
Bearer token required. Permission: workflows:permissions:workflows:manage on org/{company_id}/folder/{folder_id}/workflow/{workflow_id}/view/{view_id}.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Workflow view ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal kind: one of member, api_key, agent, automation, workflow, worksheet, role |
principal_id* | string | Identifier of the principal receiving the grant |
permission_id* | string | Permission to grant |
effect | string | Grant effect (allow or deny)Default: "allow" |
resource | string | null | Optional specific resource the grant is scoped to |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Grant ID |
permission_id* | string | Permission this grant confers |
name* | string | Permission / grant name |
resource* | string | Resource the grant applies to |
effect* | string | Grant effect (allow or deny) |
is_system* | boolean | Whether the grant is system-managed |
granted_at* | string | When the grant was created |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/grants \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"principal_type": "member", "principal_id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff", "permission_id": "perm_view_items"}'Response
201 Created{
"id": "11112222-3333-4444-5555-66667777aaaa",
"permission_id": "perm_view_items",
"name": "View Items",
"resource": "workflow-view:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"effect": "allow",
"is_system": false,
"granted_at": "2026-06-01T12:00:00Z"
}/api/v1/workflows/workflow-views/{view_id}/access/grants/{grant_id}Revoke Grant
Remove an access grant from the view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
view_id* | string (UUID) | Workflow view ID |
grant_id* | string | Grant ID to revoke |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/workflow-views/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/grants/11112222-3333-4444-5555-66667777aaaa \
-H "Authorization: Bearer {token}"Response
204 No Content(204 No Content)Connections
Wire a workflow's principal into another workflow zone and manage the cross-workflow / cross-principal connection-request handshake. The requester opens a connection (which connects immediately or opens a pending request) and can withdraw it; the approver lists inbound requests and approves or rejects them, then lists and severs the resulting inbound connections.
/api/v1/workflows/workflows/{workflow_id}/connectionsList Workflow Connections
List the outbound connections this workflow's principal owns, plus any still-pending outgoing connection requests.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow whose connections to list |
Response Fields
| Name | Type | Description |
|---|---|---|
connections* | array<ConnectionEntry> | Active connections owned by this workflow's principal |
pending_requests* | array<OutgoingRequestEntry> | Outgoing connection requests still awaiting a decision |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/11112222-3333-4444-5555-666677778888/connections" \
-H "Authorization: Bearer {token}"Response
200 OK{
"connections": [
{
"id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"principal_id": "workflow:11112222-3333-4444-5555-666677778888",
"target_service": "workflows",
"target_resource": "99990000-1111-2222-3333-444455556666",
"created_at": "2026-06-01T12:00:00Z",
"label": "Billing intake",
"created_by": "member:42424242-4242-4242-4242-424242424242",
"created_by_label": "Ada Lovelace",
"requested_by": "member:42424242-4242-4242-4242-424242424242",
"requested_by_label": "Ada Lovelace",
"system_managed_by": null,
"system_managed_key": null
}
],
"pending_requests": []
}/api/v1/workflows/workflows/{workflow_id}/connectionsCreate Workflow Connection
Connect this workflow's principal to a target resource. Returns the live connection when access is immediate, or an outgoing request when the target requires approval.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow whose principal initiates the connection |
Request Body
| Name | Type | Description |
|---|---|---|
target_service* | string | Service of the resource to connect to (e.g. "workflows") |
target_resource* | string | Resource to connect to (e.g. the target workflow ID) |
label | string | null | Human-friendly label for the connection |
message | string | null | Message sent to the approver when a request is required |
permissions | array<string> | null | Permissions to request on the target resource |
Response Fields
| Name | Type | Description |
|---|---|---|
status* | string | Outcome of the connect attempt (e.g. "connected", "requested") |
connection | ConnectionEntry | null | The established connection (present when connected immediately) |
request | OutgoingRequestEntry | null | The opened connection request (present when approval is required) |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/11112222-3333-4444-5555-666677778888/connections \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"target_service": "workflows", "target_resource": "99990000-1111-2222-3333-444455556666", "label": "Billing intake", "message": "Requesting read access to route items."}'Response
201 Created{
"status": "requested",
"connection": null,
"request": {
"id": "bbbb5555-cccc-6666-dddd-7777eeee8888",
"principal_id": "workflow:11112222-3333-4444-5555-666677778888",
"target_service": "workflows",
"target_resource": "99990000-1111-2222-3333-444455556666",
"status": "pending",
"created_at": "2026-06-01T12:00:00Z",
"connection_id": null,
"message": "Requesting read access to route items.",
"requested_by": "member:42424242-4242-4242-4242-424242424242",
"requested_permissions": null,
"decided_at": null,
"decided_by": null
}
}/api/v1/workflows/workflows/{workflow_id}/connections/{connection_id}Delete Workflow Connection
Tear down an outbound connection owned by this workflow's principal.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow that owns the connection |
connection_id* | string (UUID) | Connection to delete |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/workflows/11112222-3333-4444-5555-666677778888/connections/aaaa1111-bbbb-2222-cccc-3333dddd4444 \
-H "Authorization: Bearer {token}"Response
204 No Content(204 No Content)/api/v1/workflows/workflows/{workflow_id}/access/connectionsList Inbound Connections
List active connections where another principal connects into this workflow zone — the approver-side counterpart to the requester connections surface.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow zone being connected into |
Response Fields
| Name | Type | Description |
|---|---|---|
(root)* | array<InboundConnectionEntry> | Principals currently wired into this workflow zone |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/11112222-3333-4444-5555-666677778888/access/connections" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"principal_id": "workflow:99990000-1111-2222-3333-444455556666",
"target_service": "workflows",
"target_resource": "11112222-3333-4444-5555-666677778888",
"created_at": "2026-06-01T12:00:00Z",
"label": "Billing intake",
"principal_label": "Billing workflow",
"principal_type": "workflow",
"created_by": "member:42424242-4242-4242-4242-424242424242",
"created_by_label": "Ada Lovelace",
"requested_by": "member:42424242-4242-4242-4242-424242424242",
"requested_by_label": "Ada Lovelace",
"system_managed_by": null
}
]/api/v1/workflows/workflows/{workflow_id}/access/connections/{connection_id}Revoke Inbound Connection
Sever an inbound connection into this workflow, cutting the connected principal's runtime access. The connection is validated to actually target this zone before deletion.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow zone the connection targets |
connection_id* | string (UUID) | Inbound connection to revoke |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/workflows/11112222-3333-4444-5555-666677778888/access/connections/aaaa1111-bbbb-2222-cccc-3333dddd4444 \
-H "Authorization: Bearer {token}"Response
204 No Content(204 No Content)/api/v1/workflows/workflows/{workflow_id}/access/connection-requestsList Connection Requests
List connection requests targeting this workflow (pending by default).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow being targeted by the requests |
Query Parameters
| Name | Type | Description |
|---|---|---|
status | string | Filter requests by status (e.g. pending, approved, rejected)Default: "pending" |
Response Fields
| Name | Type | Description |
|---|---|---|
(root)* | array<ConnectionRequestEntry> | Connection requests targeting this workflow |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/11112222-3333-4444-5555-666677778888/access/connection-requests?status=pending" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "bbbb5555-cccc-6666-dddd-7777eeee8888",
"principal_id": "workflow:99990000-1111-2222-3333-444455556666",
"target_service": "workflows",
"target_resource": "11112222-3333-4444-5555-666677778888",
"status": "pending",
"created_at": "2026-06-01T12:00:00Z",
"connection_id": null,
"message": "Requesting read access to route items.",
"requested_by": "member:42424242-4242-4242-4242-424242424242",
"requested_permissions": ["workflows:workflows:items:view"],
"decided_at": null,
"decided_by": null
}
]/api/v1/workflows/workflows/{workflow_id}/access/connection-requests/{request_id}/approveApprove Connection Request
Approve a request targeting this workflow: connect the principal (idempotent) and optionally grant the requested permissions.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow being targeted by the request |
request_id* | string (UUID) | Connection request to approve |
Request Body
| Name | Type | Description |
|---|---|---|
grant | boolean | Whether to grant the requested permissions on approvalDefault: true |
label | string | null | Label to apply to the created connection |
permissions | array<string> | null | Override the permissions to grant (defaults to the requested set) |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Connection request ID |
principal_id* | string | Principal asking to connect into this workflow |
target_service* | string | Service of the targeted resource |
target_resource* | string | Resource (this workflow zone) being targeted |
status* | string | Request status (pending, approved, rejected, withdrawn) |
created_at* | string | When the request was opened |
connection_id | string | null | Connection created once approved |
message | string | null | Message from the requester |
requested_by | string | null | Principal that submitted the request |
requested_permissions | array<string> | null | Permissions the requester asked for |
decided_at | string | null | When the request was approved or rejected |
decided_by | string | null | Principal that decided the request |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/11112222-3333-4444-5555-666677778888/access/connection-requests/bbbb5555-cccc-6666-dddd-7777eeee8888/approve \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"grant": true, "label": "Billing intake"}'Response
200 OK{
"id": "bbbb5555-cccc-6666-dddd-7777eeee8888",
"principal_id": "workflow:99990000-1111-2222-3333-444455556666",
"target_service": "workflows",
"target_resource": "11112222-3333-4444-5555-666677778888",
"status": "approved",
"created_at": "2026-06-01T12:00:00Z",
"connection_id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"message": "Requesting read access to route items.",
"requested_by": "member:42424242-4242-4242-4242-424242424242",
"requested_permissions": ["workflows:workflows:items:view"],
"decided_at": "2026-06-01T12:05:00Z",
"decided_by": "member:55556666-7777-8888-9999-aaaabbbbcccc"
}/api/v1/workflows/workflows/{workflow_id}/access/connection-requests/{request_id}/rejectReject Connection Request
Reject a pending connection request targeting this workflow, optionally recording a reason.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow being targeted by the request |
request_id* | string (UUID) | Connection request to reject |
Request Body
| Name | Type | Description |
|---|---|---|
reason | string | null | Optional reason recorded on the rejected request |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Connection request ID |
principal_id* | string | Principal asking to connect into this workflow |
target_service* | string | Service of the targeted resource |
target_resource* | string | Resource (this workflow zone) being targeted |
status* | string | Request status (pending, approved, rejected, withdrawn) |
created_at* | string | When the request was opened |
connection_id | string | null | Connection created once approved |
message | string | null | Message from the requester |
requested_by | string | null | Principal that submitted the request |
requested_permissions | array<string> | null | Permissions the requester asked for |
decided_at | string | null | When the request was approved or rejected |
decided_by | string | null | Principal that decided the request |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/11112222-3333-4444-5555-666677778888/access/connection-requests/bbbb5555-cccc-6666-dddd-7777eeee8888/reject \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"reason": "Out of scope for this workflow."}'Response
200 OK{
"id": "bbbb5555-cccc-6666-dddd-7777eeee8888",
"principal_id": "workflow:99990000-1111-2222-3333-444455556666",
"target_service": "workflows",
"target_resource": "11112222-3333-4444-5555-666677778888",
"status": "rejected",
"created_at": "2026-06-01T12:00:00Z",
"connection_id": null,
"message": "Requesting read access to route items.",
"requested_by": "member:42424242-4242-4242-4242-424242424242",
"requested_permissions": ["workflows:workflows:items:view"],
"decided_at": "2026-06-01T12:05:00Z",
"decided_by": "member:55556666-7777-8888-9999-aaaabbbbcccc"
}/api/v1/workflows/folders/{folder_id}/access/connection-requestsList Folder Connection Requests
List inbound connection requests targeting a workflow folder. The caller must manage access on the folder.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Target workflow folder |
Query Parameters
| Name | Type | Description |
|---|---|---|
status | string | Request status filterDefault: "pending" |
Response Fields
| Name | Type | Description |
|---|---|---|
(root)* | array<ConnectionRequestEntry> | Requests targeting this folder |
curl "https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/access/connection-requests?status=pending" \
-H "Authorization: Bearer {token}"Response
200 OK[]/api/v1/workflows/folders/{folder_id}/access/connection-requests/{request_id}/approveApprove Folder Connection Request
Approve a connection request targeting this folder and optionally grant the requested permissions.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Target folder |
request_id* | string (UUID) | Connection request |
Request Body
| Name | Type | Description |
|---|---|---|
grant | boolean | Grant requested permissions when approvingDefault: true |
permissions | array<string> | null | Optional permission override |
label | string | null | Connection label |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Connection request ID |
principal_id* | string | Principal asking to connect into this workflow |
target_service* | string | Service of the targeted resource |
target_resource* | string | Resource (this workflow zone) being targeted |
status* | string | Request status (pending, approved, rejected, withdrawn) |
created_at* | string | When the request was opened |
connection_id | string | null | Connection created once approved |
message | string | null | Message from the requester |
requested_by | string | null | Principal that submitted the request |
requested_permissions | array<string> | null | Permissions the requester asked for |
decided_at | string | null | When the request was approved or rejected |
decided_by | string | null | Principal that decided the request |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/access/connection-requests/bbbb5555-cccc-6666-dddd-7777eeee8888/approve \
-H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"grant":true}'Response
200 OK{"id":"bbbb5555-cccc-6666-dddd-7777eeee8888","status":"approved","connection_id":"aaaa1111-bbbb-2222-cccc-3333dddd4444"}/api/v1/workflows/folders/{folder_id}/access/connection-requests/{request_id}/rejectReject Folder Connection Request
Reject a pending connection request targeting this folder.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Target folder |
request_id* | string (UUID) | Connection request |
Request Body
| Name | Type | Description |
|---|---|---|
reason | string | null | Optional rejection reason |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Connection request ID |
principal_id* | string | Principal asking to connect into this workflow |
target_service* | string | Service of the targeted resource |
target_resource* | string | Resource (this workflow zone) being targeted |
status* | string | Request status (pending, approved, rejected, withdrawn) |
created_at* | string | When the request was opened |
connection_id | string | null | Connection created once approved |
message | string | null | Message from the requester |
requested_by | string | null | Principal that submitted the request |
requested_permissions | array<string> | null | Permissions the requester asked for |
decided_at | string | null | When the request was approved or rejected |
decided_by | string | null | Principal that decided the request |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/access/connection-requests/bbbb5555-cccc-6666-dddd-7777eeee8888/reject \
-H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"reason":"Out of scope"}'Response
200 OK{"id":"bbbb5555-cccc-6666-dddd-7777eeee8888","status":"rejected","connection_id":null}/api/v1/workflows/folders/{folder_id}/access/connectionsList Folder Inbound Connections
List active principal connections targeting this workflow folder.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Target folder |
Response Fields
| Name | Type | Description |
|---|---|---|
(root)* | array<InboundConnectionEntry> | Active inbound connections |
curl https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/access/connections \
-H "Authorization: Bearer {token}"Response
200 OK[]/api/v1/workflows/folders/{folder_id}/access/connections/{connection_id}Revoke Folder Inbound Connection
Sever an active principal connection targeting this workflow folder.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Target folder |
connection_id* | string (UUID) | Connection to revoke |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/access/connections/aaaa1111-bbbb-2222-cccc-3333dddd4444 \
-H "Authorization: Bearer {token}"Response
204 No Content(204 No Content)/api/v1/workflows/workflows/{workflow_id}/connection-requests/{request_id}/withdrawWithdraw Workflow Connection Request
Withdraw an outgoing connection request this workflow's principal opened, before the approver decides on it.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow whose principal opened the request |
request_id* | string (UUID) | Outgoing connection request to withdraw |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Connection request ID |
principal_id* | string | Principal that opened the request |
target_service* | string | Service of the requested resource |
target_resource* | string | Resource the principal wants to connect to |
status* | string | Request status (pending, approved, rejected, withdrawn) |
created_at* | string | When the request was opened |
connection_id | string | null | Connection created once the request is approved |
message | string | null | Message sent to the approver |
requested_by | string | null | Principal that submitted the request |
requested_permissions | array<string> | null | Permissions requested on the target |
decided_at | string | null | When the request was approved or rejected |
decided_by | string | null | Principal that decided the request |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/11112222-3333-4444-5555-666677778888/connection-requests/bbbb5555-cccc-6666-dddd-7777eeee8888/withdraw \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "bbbb5555-cccc-6666-dddd-7777eeee8888",
"principal_id": "workflow:11112222-3333-4444-5555-666677778888",
"target_service": "workflows",
"target_resource": "99990000-1111-2222-3333-444455556666",
"status": "withdrawn",
"created_at": "2026-06-01T12:00:00Z",
"connection_id": null,
"message": "Requesting read access to route items.",
"requested_by": "member:42424242-4242-4242-4242-424242424242",
"requested_permissions": null,
"decided_at": "2026-06-01T12:05:00Z",
"decided_by": "member:42424242-4242-4242-4242-424242424242"
}Access & Grants
Zero-trust access control for workflows and folders. Each workflow and folder is a federated security zone: discover eligible principals, inspect current grants (flat or grouped by principal), enumerate the grantable permissions and resource-type tree, then create and revoke individual permission grants. All endpoints require the corresponding manage permission (workflows:permissions:workflows:manage for workflows, workflows:permissions:folders:manage for folders).
/api/v1/workflows/workflows/{workflow_id}/access/eligibleList Eligible Principals (Workflow)
List principals that can be granted access to the workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal type (member, api_key, agent, automation, workflow, worksheet, role) |
principal_id* | string | Principal ID |
label* | string | Display label |
display_name | string | null | Human display name |
avatar_url | string | null | Avatar URL |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/eligible" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_type": "member",
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"label": "Ada Lovelace",
"display_name": "Ada Lovelace",
"avatar_url": null
},
{
"principal_type": "role",
"principal_id": "9f9f8e8e-7d7d-6c6c-5b5b-4a4a39392828",
"label": "Support Agents",
"display_name": null,
"avatar_url": null
}
]/api/v1/workflows/workflows/{workflow_id}/access/grantsList Grants (Workflow)
List the permission grants currently held on the workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Page size (1-500)Default: 100 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<GrantResponse> | Page of grants |
page* | integer | Current page |
limit* | integer | Page size |
total* | integer | Total matching grants |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/grants?page=1&limit=100" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "11112222-3333-4444-5555-666677778888",
"permission_id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"name": "Manage items",
"resource": "workflow:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"effect": "allow",
"is_system": false,
"granted_at": "2026-06-01T12:00:00Z"
}
],
"page": 1,
"limit": 100,
"total": 1
}/api/v1/workflows/workflows/{workflow_id}/access/grants/groupedList Grants Grouped (Workflow)
Return grants grouped by principal for the workflow security table.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Page size (1-100)Default: 25 |
q | string | null | Search filter (max 200 chars) |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<PrincipalGrants> | Grants grouped by principal |
page* | integer | Current page |
limit* | integer | Page size |
total* | integer | Total matching principals |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/grants/grouped?page=1&limit=25" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"principal_type": "member",
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"label": "Ada Lovelace",
"display_name": "Ada Lovelace",
"avatar_url": null,
"grants": [
{
"id": "11112222-3333-4444-5555-666677778888",
"permission_id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"name": "Manage items",
"resource": "workflow:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"effect": "allow",
"is_system": false,
"granted_at": "2026-06-01T12:00:00Z"
}
]
}
],
"page": 1,
"limit": 25,
"total": 1
}/api/v1/workflows/workflows/{workflow_id}/access/permissionsList Workflow Permissions
Return the set of grantable workflow permissions.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Permission ID |
name* | string | Permission slug |
friendly_name | string | null | Human label |
friendly_name_singular | string | null | Singular human label |
friendly_name_plural | string | null | Plural human label |
description | string | null | Description |
description_singular | string | null | Singular description |
description_plural | string | null | Plural description |
scope_anchor | string | Where the permission anchorsDefault: instance |
display_order | integer | Sort orderDefault: 0 |
resource_type_id | string | null | Owning resource type |
parent_resource_type_slug | string | null | Parent resource type slug |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/permissions" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"name": "workflows:workflows:items:edit",
"friendly_name": "Edit items",
"description": "Edit items in this workflow",
"scope_anchor": "instance",
"display_order": 10,
"resource_type_id": "c1c1c1c1-d2d2-e3e3-f4f4-a5a5b6b6c7c7",
"parent_resource_type_slug": "workflow"
}
]/api/v1/workflows/workflows/{workflow_id}/access/resource-typesList Resource Types (Workflow)
Return the resource type tree for the workflows service.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
resource_types* | array<ResourceTypeNode> | Resource type tree |
permissions* | array<PermissionOption> | Flat list of grantable permissions |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/resource-types" \
-H "Authorization: Bearer {token}"Response
200 OK{
"resource_types": [
{
"id": "c1c1c1c1-d2d2-e3e3-f4f4-a5a5b6b6c7c7",
"name": "Workflow",
"slug": "workflow",
"parent_id": null,
"children": [
{
"id": "d2d2d2d2-e3e3-f4f4-a5a5-b6b6c7c7d8d8",
"name": "Phase",
"slug": "phase",
"parent_id": "c1c1c1c1-d2d2-e3e3-f4f4-a5a5b6b6c7c7",
"children": []
}
]
}
],
"permissions": [
{
"id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"name": "workflows:workflows:items:edit",
"friendly_name": "Edit items",
"scope_anchor": "instance",
"display_order": 10
}
]
}/api/v1/workflows/workflows/{workflow_id}/access/grantsCreate Grant (Workflow)
Grant a permission to a principal on the workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal type (member, api_key, agent, automation, workflow, worksheet, role) |
principal_id* | string | Principal receiving the grant |
permission_id* | string | Permission to grant |
effect | string | allow or denyDefault: allow |
resource | string | null | Sub-resource the grant applies to |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Grant ID |
permission_id* | string | Granted permission |
name* | string | Grant display name |
resource* | string | Resource path the grant targets |
effect* | string | allow or deny |
is_system* | boolean | Whether the grant is system-managed |
granted_at* | string | When the grant was created |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/grants \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"principal_type": "member", "principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "permission_id": "aaaa1111-bbbb-2222-cccc-3333dddd4444", "effect": "allow"}'Response
201 Created{
"id": "11112222-3333-4444-5555-666677778888",
"permission_id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"name": "Manage items",
"resource": "workflow:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"effect": "allow",
"is_system": false,
"granted_at": "2026-06-01T12:00:00Z"
}/api/v1/workflows/workflows/{workflow_id}/access/grants/{grant_id}Delete Grant (Workflow)
Revoke a permission grant from the workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
grant_id* | string (UUID) | Grant ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/access/grants/11112222-3333-4444-5555-666677778888 \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/api/v1/workflows/folders/{folder_id}/access/eligibleList Eligible Principals (Folder)
List principals that can be granted access to the folder.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Folder ID |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal type (member, api_key, agent, automation, workflow, worksheet, role) |
principal_id* | string | Principal ID |
label* | string | Display label |
display_name | string | null | Human display name |
avatar_url | string | null | Avatar URL |
curl "https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/access/eligible" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_type": "member",
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"label": "Ada Lovelace",
"display_name": "Ada Lovelace",
"avatar_url": null
},
{
"principal_type": "role",
"principal_id": "9f9f8e8e-7d7d-6c6c-5b5b-4a4a39392828",
"label": "Support Agents",
"display_name": null,
"avatar_url": null
}
]/api/v1/workflows/folders/{folder_id}/access/grantsList Grants (Folder)
List the permission grants currently held on the folder.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Folder ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Page size (1-500)Default: 100 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<GrantResponse> | Page of grants |
page* | integer | Current page |
limit* | integer | Page size |
total* | integer | Total matching grants |
curl "https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/access/grants?page=1&limit=100" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "11112222-3333-4444-5555-666677778888",
"permission_id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"name": "Manage items",
"resource": "folder:01234567-89ab-cdef-0123-456789abcdef",
"effect": "allow",
"is_system": false,
"granted_at": "2026-06-01T12:00:00Z"
}
],
"page": 1,
"limit": 100,
"total": 1
}/api/v1/workflows/folders/{folder_id}/access/permissionsList Folder Permissions
Return the set of grantable folder permissions.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Folder ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Permission ID |
name* | string | Permission slug |
friendly_name | string | null | Human label |
friendly_name_singular | string | null | Singular human label |
friendly_name_plural | string | null | Plural human label |
description | string | null | Description |
description_singular | string | null | Singular description |
description_plural | string | null | Plural description |
scope_anchor | string | Where the permission anchorsDefault: instance |
display_order | integer | Sort orderDefault: 0 |
resource_type_id | string | null | Owning resource type |
parent_resource_type_slug | string | null | Parent resource type slug |
curl "https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/access/permissions" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"name": "workflows:folders:edit",
"friendly_name": "Edit items",
"description": "Edit items in this workflow",
"scope_anchor": "instance",
"display_order": 10,
"resource_type_id": "c1c1c1c1-d2d2-e3e3-f4f4-a5a5b6b6c7c7",
"parent_resource_type_slug": "workflow"
}
]/api/v1/workflows/folders/{folder_id}/access/resource-typesList Resource Types (Folder)
Return the resource type tree for the workflows service.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Folder ID |
Response Fields
| Name | Type | Description |
|---|---|---|
resource_types* | array<ResourceTypeNode> | Resource type tree |
permissions* | array<PermissionOption> | Flat list of grantable permissions |
curl "https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/access/resource-types" \
-H "Authorization: Bearer {token}"Response
200 OK{
"resource_types": [
{
"id": "c1c1c1c1-d2d2-e3e3-f4f4-a5a5b6b6c7c7",
"name": "Workflow",
"slug": "workflow",
"parent_id": null,
"children": [
{
"id": "d2d2d2d2-e3e3-f4f4-a5a5-b6b6c7c7d8d8",
"name": "Phase",
"slug": "phase",
"parent_id": "c1c1c1c1-d2d2-e3e3-f4f4-a5a5b6b6c7c7",
"children": []
}
]
}
],
"permissions": [
{
"id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"name": "workflows:workflows:items:edit",
"friendly_name": "Edit items",
"scope_anchor": "instance",
"display_order": 10
}
]
}/api/v1/workflows/folders/{folder_id}/access/grantsCreate Grant (Folder)
Grant a permission to a principal on the folder.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Folder ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal type (member, api_key, agent, automation, workflow, worksheet, role) |
principal_id* | string | Principal receiving the grant |
permission_id* | string | Permission to grant |
effect | string | allow or denyDefault: allow |
resource | string | null | Sub-resource the grant applies to |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Grant ID |
permission_id* | string | Granted permission |
name* | string | Grant display name |
resource* | string | Resource path the grant targets |
effect* | string | allow or deny |
is_system* | boolean | Whether the grant is system-managed |
granted_at* | string | When the grant was created |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/access/grants \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"principal_type": "member", "principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee", "permission_id": "aaaa1111-bbbb-2222-cccc-3333dddd4444", "effect": "allow"}'Response
201 Created{
"id": "11112222-3333-4444-5555-666677778888",
"permission_id": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
"name": "Manage items",
"resource": "folder:01234567-89ab-cdef-0123-456789abcdef",
"effect": "allow",
"is_system": false,
"granted_at": "2026-06-01T12:00:00Z"
}/api/v1/workflows/folders/{folder_id}/access/grants/{grant_id}Delete Grant (Folder)
Revoke a permission grant from the folder.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Folder ID |
grant_id* | string (UUID) | Grant ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/access/grants/11112222-3333-4444-5555-666677778888 \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No ContentCross-Service Grants
Cross-service consumer grants share a workflow with another platform service (such as `automations`) so that service can act against the workflow on the company's behalf. List and create grants under a workflow; consumer services discover the workflows shared with them through their own `/granted` endpoints, and a grant is revoked by id at `workflow-grants/{grant_id}`. This is distinct from the per-resource `/access/grants` IAM subtree, which manages principal permissions on a single resource.
/api/v1/workflows/workflows/{workflow_id}/grantsList Grants
List the cross-service grants that share this workflow with consumer services.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Grant ID |
company_id* | string | Owning company ID |
service_name* | string | Consumer service the workflow is shared with |
resource_id* | string | null | Consumer-side resource the grant is scoped to |
resource_label* | string | null | Human label for the consumer-side resource |
label* | string | null | Display label for the grant |
created_by* | string | null | Principal that created the grant |
created_at* | datetime | When the grant was created |
workflow_id* | string (UUID) | Workflow the grant shares |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/grants" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "11112222-3333-4444-5555-666677778888",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"service_name": "automations",
"resource_id": "auto-7f3a9c12-4b6d-4e8a-9f01-2c3d4e5f6a7b",
"resource_label": "Onboarding Automation",
"label": "Automations access",
"created_by": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"created_at": "2026-06-19T18:30:00Z",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
]/api/v1/workflows/workflows/{workflow_id}/grantsCreate Grant
Share this workflow with a consumer service by creating a cross-service grant. The consumer then discovers the workflow through its own `/granted` endpoints.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Request Body
| Name | Type | Description |
|---|---|---|
service_name* | string | Consumer service to share the workflow with (1-50 chars) |
label | string | null | Display label for the grant |
resource_id | string | null | Consumer-side resource to scope the grant to |
resource_label | string | null | Human label for the consumer-side resource |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Grant ID |
company_id* | string | Owning company ID |
service_name* | string | Consumer service the workflow is shared with |
resource_id* | string | null | Consumer-side resource the grant is scoped to |
resource_label* | string | null | Human label for the consumer-side resource |
label* | string | null | Display label for the grant |
created_by* | string | null | Principal that created the grant |
created_at* | datetime | When the grant was created |
workflow_id* | string (UUID) | Workflow the grant shares |
curl -X POST "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/grants" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"service_name": "automations",
"label": "Automations access",
"resource_id": "auto-7f3a9c12-4b6d-4e8a-9f01-2c3d4e5f6a7b",
"resource_label": "Onboarding Automation"
}'Response
201 Created{
"id": "11112222-3333-4444-5555-666677778888",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"service_name": "automations",
"resource_id": "auto-7f3a9c12-4b6d-4e8a-9f01-2c3d4e5f6a7b",
"resource_label": "Onboarding Automation",
"label": "Automations access",
"created_by": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"created_at": "2026-06-19T18:30:00Z",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}/api/v1/workflows/workflow-grants/{grant_id}Revoke Grant
Revoke a cross-service grant by id, removing the consumer service's shared access to the workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
grant_id* | string (UUID) | Grant ID |
curl -X DELETE "https://platform.ergondata.ai/api/v1/workflows/workflow-grants/11112222-3333-4444-5555-666677778888" \
-H "Authorization: Bearer {token}"Response
204 No Content# 204 No ContentBatch Access Grants
Collection-level grant creation across workflow folder, workflow, and saved-view roots. Every route uses the shared grouped BatchCreateGrantsRequest and ordered BatchCreateGrantsResponse contract.
/api/v1/workflows/folders/access/grants/batchCreate Folder Access Grants Batch
Create grants across workflow-folder roots with ordered, independent results. Group a subject with resources and permission UUIDs; operations expand resources first and permission IDs second, to at most 200 grants total. Invalid or unauthorized items fail without blocking valid items, and partial success returns 200. Whole-request retries are safe because existing natural grant tuples return already_exists. A side_effect_error reports failed post-write reconciliation while the grant exists. ToolDef slug: workflows.folder_access_grants.create_grants_batch.
Bearer token required. Permission: workflows:permissions:folders:manage on every target folder root.
Request Body
| Name | Type | Description |
|---|---|---|
operations* | array | 1–200 grouped operations; resources × permission_ids across all operations must expand to at most 200 grants |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | array | One result per expanded grant, ordered by operation, then resource, then permission |
summary* | object | Outcome counts |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/folders/access/grants/batch \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"operations":[{"client_ref":"folder-reviewers","principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/folder/{folder_id}"],"permission_ids":["{permission_id}"]}]}'Response
200 OK{
"results": [{
"index": 0,
"client_ref": "folder-reviewers",
"status": "created",
"principal_type": "member",
"principal_id": "{principal_id}",
"permission_id": "{permission_id}",
"resource": "org/{company_id}/folder/{folder_id}",
"effect": "allow",
"grant": {"id": "{grant_id}", "permission_id": "{permission_id}", "name": "workflows:folders:view", "resource": "org/{company_id}/folder/{folder_id}", "effect": "allow", "is_system": false, "granted_at": "2026-07-15T16:30:00Z"},
"error_status": null,
"error_detail": null,
"side_effect_error_status": null,
"side_effect_error_detail": null
}],
"summary": {"created": 1, "already_exists": 0, "failed": 0}
}/api/v1/workflows/workflows/access/grants/batchCreate Workflow Access Grants Batch
Apply the grouped BatchCreateGrantsRequest across workflow roots, with at most 200 expanded grants in operation/resource/permission order. Primary validation or write failures are item-local, so partial success returns 200. Retry failed items or the whole request safely; existing tuples return already_exists. side_effect_error outcomes already hold a grant and can be retried to reconcile parent navigation and workflow activity. ToolDef slug: workflows.access_grants.create_grants_batch.
Bearer token required. Permission: workflows:permissions:workflows:manage on every target workflow root.
Request Body
| Name | Type | Description |
|---|---|---|
operations* | array | 1–200 grouped operations; resources × permission_ids across all operations must expand to at most 200 grants |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | array | One result per expanded grant, ordered by operation, then resource, then permission |
summary* | object | Outcome counts |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/access/grants/batch \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"operations":[{"principal_type":"agent","principal_id":"{principal_id}","resources":["org/{company_id}/folder/{folder_id}/workflow/{workflow_id}"],"permission_ids":["{permission_id}"],"effect":"allow"}]}'Response
200 OK{"results":[{"index":0,"client_ref":null,"status":"already_exists","principal_type":"agent","principal_id":"{principal_id}","permission_id":"{permission_id}","resource":"org/{company_id}/folder/{folder_id}/workflow/{workflow_id}","effect":"allow","grant":{"id":"{grant_id}","permission_id":"{permission_id}","name":"workflows:workflows:view","resource":"org/{company_id}/folder/{folder_id}/workflow/{workflow_id}","effect":"allow","is_system":false,"granted_at":"2026-07-15T16:30:00Z"},"error_status":null,"error_detail":null,"side_effect_error_status":null,"side_effect_error_detail":null}],"summary":{"created":0,"already_exists":1,"failed":0}}/api/v1/workflows/workflow-views/access/grants/batchCreate Saved-View Access Grants Batch
Apply the grouped BatchCreateGrantsRequest across workflow saved-view roots, with at most 200 expanded grants and ordered, independent outcomes. Partial success returns 200. Whole-request retries are safe: natural duplicates return already_exists, while side_effect_error identifies a successful grant whose post-write parent-navigation reconciliation should be retried. ToolDef slug: workflows.view_access_grants.create_grants_batch.
Bearer token required. Permission: workflows:permissions:workflows:manage on every target saved-view root.
Request Body
| Name | Type | Description |
|---|---|---|
operations* | array | 1–200 grouped operations; resources × permission_ids across all operations must expand to at most 200 grants |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | array | One result per expanded grant, ordered by operation, then resource, then permission |
summary* | object | Outcome counts |
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflow-views/access/grants/batch \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/folder/{folder_id}/workflow/{workflow_id}/view/{view_id}"],"permission_ids":["{permission_id}"]}]}'Response
200 OK{"results":[{"index":0,"client_ref":null,"status":"created","principal_type":"member","principal_id":"{principal_id}","permission_id":"{permission_id}","resource":"org/{company_id}/folder/{folder_id}/workflow/{workflow_id}/view/{view_id}","effect":"allow","grant":{"id":"{grant_id}","permission_id":"{permission_id}","name":"workflows:workflows:views:view","resource":"org/{company_id}/folder/{folder_id}/workflow/{workflow_id}/view/{view_id}","effect":"allow","is_system":false,"granted_at":"2026-07-15T16:30:00Z"},"error_status":null,"error_detail":null,"side_effect_error_status":null,"side_effect_error_detail":null}],"summary":{"created":1,"already_exists":0,"failed":0}}Activity, Inbox & Discovery
Read-only feeds and cross-service discovery surfaces. Per-workflow and folder activity feeds expose the audit trail; the company inbox is the per-member work queue across every workflow the caller can see; the `/granted` endpoints let another service discover the workflows, folders, phases, and fields it has been granted; and the claimers/eligible-principals/phase-groups endpoints back the assignment and board UIs.
/api/v1/workflows/workflows/{workflow_id}/activityList Workflow Activity
Return the paginated activity feed for a single workflow. This is the in-workflow detail view, gated by workflows:workflows:activity:view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
event_type | string | null | Filter by event type slug |
correlation_id | string | null | Filter by correlation ID |
search | string | null | Case-insensitive match on the item title, including the title a deleted item had (max 200 characters; % and _ match literally) |
actor_principal_id | string (UUID) | null | Only events by this principal |
created_from | datetime | null | Only events at or after this instant |
created_to | datetime | null | Only events at or before this instant (422 if before created_from) |
include_event_types | boolean | Also return event_types: every workflow event type, for building a filterDefault: false |
include_actors | boolean | Also return actors (at most 500, past actors first), for building a filter: everyone who ever acted here, removed and deleted principals included, plus everyone connected now (an IAM connection on the workflow, its folder or the organization, held directly, through a team or through a role)Default: false |
page | integer | 1-indexed page numberDefault: 1 |
limit | integer | Page size (max 100)Default: 50 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<WorkflowEvent> | Page of activity events |
total* | integer | Total matching events |
page* | integer | Current page |
limit* | integer | Page size |
event_types | array<EventType> | null | Workflow event type catalog, present when include_event_types=true |
actors | array<ActivityActor> | null | Who the feed can be filtered by, present when include_actors=true |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/activity?event_type=workflows.items.routed&page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "22223333-4444-5555-6666-777788889999",
"event_type": "workflows.items.routed",
"actor_type": "user",
"actor_label": "Ada Lovelace",
"data": {
"from_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"to_phase_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
},
"created_at": "2026-06-01T12:00:00Z",
"correlation_id": "44445555-6666-7777-8888-9999aaaabbbb",
"item_id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff",
"item_title": "Refund request #4821",
"refs": {
"b2c3d4e5-f6a7-8901-bcde-f12345678901": "Triage",
"c3d4e5f6-a7b8-9012-cdef-123456789012": "In progress"
}
}
],
"total": 1,
"page": 1,
"limit": 50,
"event_types": null,
"actors": null
}/api/v1/workflows/workflows/{workflow_id}/activity/{event_id}Get Workflow Activity Event
Fetch a single activity event by ID within a workflow.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
event_id* | string (UUID) | Event ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Event ID |
event_type* | string | Event type slug (e.g. workflows.items.created) |
actor_type* | string | null | Actor kind (user, service, system) |
actor_label* | string | null | Human-readable actor label |
data* | object | null | Event-type-specific payload |
created_at* | datetime | When the event occurred |
correlation_id | UUID | null | Correlation ID linking related events |
item_id | UUID | null | Item the event relates to, if any |
item_title | string | null | Item title. For workflows.items.deleted, the title the item had when it was deleted |
refs | object | Names for the ids in data (phases, fields, people, assignment groups, views, items, workflows, folders), keyed by id. Resolved inside the workflow or folder being read; phase and workflow names also resolve elsewhere in the company. A deleted phase or field falls back to the name its event recordedDefault: {} |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/activity/22223333-4444-5555-6666-777788889999" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "22223333-4444-5555-6666-777788889999",
"event_type": "workflows.items.assigned",
"actor_type": "user",
"actor_label": "Ada Lovelace",
"data": {"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee"},
"created_at": "2026-06-01T12:05:00Z",
"correlation_id": "44445555-6666-7777-8888-9999aaaabbbb",
"item_id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff",
"item_title": "Refund request #4821",
"refs": {"77778888-9999-aaaa-bbbb-ccccddddeeee": "Grace Hopper"}
}/api/v1/workflows/folders/{folder_id}/activityList Folder Activity
Aggregated activity across every workflow in the folder. This folder-zone audit lens surfaces events from child workflows the caller may not otherwise open, gated by the folder-level workflows:folders:activity:view grant.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
folder_id* | string (UUID) | Folder ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
event_type | string | null | Filter by event type slug |
search | string | null | Case-insensitive match on the item title, including the title a deleted item had (max 200 characters; % and _ match literally) |
actor_principal_id | string (UUID) | null | Only events by this principal |
created_from | datetime | null | Only events at or after this instant |
created_to | datetime | null | Only events at or before this instant (422 if before created_from) |
include_event_types | boolean | Also return event_types: every workflow event type, for building a filterDefault: false |
include_actors | boolean | Also return actors (at most 500, past actors first), for building a filter: everyone who ever acted here, removed and deleted principals included, plus everyone connected now (an IAM connection on the workflow, its folder or the organization, held directly, through a team or through a role)Default: false |
page | integer | 1-indexed page numberDefault: 1 |
limit | integer | Page size (max 100)Default: 50 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<FolderActivityEvent> | Page of aggregated activity events |
total* | integer | Total matching events |
page* | integer | Current page |
limit* | integer | Page size |
event_types | array<EventType> | null | Workflow event type catalog, present when include_event_types=true |
actors | array<ActivityActor> | null | Who the feed can be filtered by, present when include_actors=true |
curl "https://platform.ergondata.ai/api/v1/workflows/folders/01234567-89ab-cdef-0123-456789abcdef/activity?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "22223333-4444-5555-6666-777788889999",
"event_type": "workflows.items.deleted",
"actor_type": "user",
"actor_label": "Ada Lovelace",
"data": {"title": "Refund request #4821", "phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"},
"created_at": "2026-06-01T12:00:00Z",
"correlation_id": null,
"item_id": null,
"item_title": "Refund request #4821",
"refs": {"b2c3d4e5-f6a7-8901-bcde-f12345678901": "Triage"},
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"workflow_name": "Support queue"
}
],
"total": 1,
"page": 1,
"limit": 50,
"event_types": null,
"actors": null
}/api/v1/workflows/companies/{company_id}/inbox-itemsList Company Inbox Items
Union inbox across workflows and saved views the caller can see. With no filters this returns the deduped set of items reachable through direct workflow item permissions or saved-view item permissions. assigned_to=me narrows to the caller's assigned queue; claimable_for=me to items the caller may claim through either route.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Organization ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
assigned_to | string | null | Pass 'me' for the caller's assigned queue, or a principal UUID to filter by that assignee (mutually exclusive with claimable_for). |
assigned | string | null | 'yes' = only assigned, 'no' = only unassigned |
claimable_for | string | null | Pass 'me' for claimable items (mutually exclusive with assigned_to). |
workflow_ids | string | null | Comma-separated workflow UUIDs to narrow the inbox |
phase_ids | string | null | Comma-separated phase UUIDs |
search | string | null | Case-insensitive substring match on title, description, current phase name, workflow name, assignee display name, or a stored field value (limited to fields the caller can view), or an item UUID prefix (a leading '#' is ignored) |
created_from | datetime | null | Only items created at/after this ISO timestamp |
created_to | datetime | null | Only items created at/before this ISO timestamp |
updated_from | datetime | null | Only items updated at/after this ISO timestamp |
updated_to | datetime | null | Only items updated at/before this ISO timestamp |
sort | string | Sort field: created_at, updated_at, titleDefault: created_at |
sort_dir | string | Sort direction: asc or descDefault: asc |
limit | integer | Page size (0–500). 0 returns the first 500 items.Default: 200 |
offset | integer | Offset for paginationDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array<ItemListItem> | Page of inbox items |
total* | integer | Total matching items |
limit* | integer | Page size |
offset* | integer | Page offset |
curl "https://platform.ergondata.ai/api/v1/workflows/companies/c0ffee00-cafe-babe-dead-beefcafebabe/inbox-items?assigned_to=me&limit=200&offset=0" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff",
"title": "Refund request #4821",
"current_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"current_phase_name": "Triage",
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:05:00Z",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"workflow_name": "Support queue",
"inbox_access_mode": "view",
"inbox_view_id": "11112222-3333-4444-5555-666677778888",
"inbox_view_name": "Escalations",
"inbox_can_claim": true,
"inbox_can_assign": false,
"assigned_to": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"assignees": [],
"card_fields": [],
"is_visible": true
}
],
"total": 1,
"limit": 200,
"offset": 0
}/api/v1/workflows/companies/{company_id}/inbox-workflowsList Company Inbox Workflows
List workflows in a company for the global support inbox, with flags for whether the caller has the items view and the support view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Organization ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Workflow ID |
name* | string | Workflow name |
has_items_view* | boolean | Caller can see the items view |
has_support_view* | boolean | Caller can see the support view |
curl "https://platform.ergondata.ai/api/v1/workflows/companies/c0ffee00-cafe-babe-dead-beefcafebabe/inbox-workflows" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Support queue",
"has_items_view": true,
"has_support_view": false
}
]/api/v1/workflows/workflows/grantedList Granted Workflows
Return workflows granted to the calling service (plus an optional consumer resource). Used by the automations Studio to populate trigger resource-scope and action input pickers when the referenced resource is a workflow.
Bearer token required.
Query Parameters
| Name | Type | Description |
|---|---|---|
service* | string | Consumer service requesting the grants (e.g. automations) |
resource_id | string | null | Optional consumer resource scoping the grant lookup |
folder_id | string | null | Narrow to workflows in a single folder |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Workflow ID |
name* | string | Workflow name |
folder_id* | UUID | Folder the workflow belongs to |
description | string | null | Workflow description |
created_at | datetime | null | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/granted?service=automations" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Support queue",
"folder_id": "01234567-89ab-cdef-0123-456789abcdef",
"description": "Tier-1 intake",
"created_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/folders/grantedList Granted Folders
Return folders that contain workflows granted to the calling service. The Studio cascading scope picker starts at the first link in the workflows resource chain (folder -> workflow -> ...); a folder is selectable when it contains at least one granted workflow.
Bearer token required.
Query Parameters
| Name | Type | Description |
|---|---|---|
service* | string | Consumer service requesting the grants (e.g. automations) |
resource_id | string | null | Optional consumer resource scoping the grant lookup |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Folder ID |
name* | string | Folder name |
description | string | null | Folder description |
created_at | datetime | null | Creation time |
curl "https://platform.ergondata.ai/api/v1/workflows/folders/granted?service=automations" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Customer support",
"description": "Support workflows",
"created_at": "2026-06-01T12:00:00Z"
}
]/api/v1/workflows/phases/grantedList Granted Phases
Return phases inside workflows granted to the calling service. When workflow_id is provided, only phases within that workflow are returned (still restricted to granted workflows).
Bearer token required.
Query Parameters
| Name | Type | Description |
|---|---|---|
service* | string | Consumer service requesting the grants (e.g. automations) |
resource_id | string | null | Optional consumer resource scoping the grant lookup |
workflow_id | string | null | Narrow to a single granted workflow |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Phase ID |
workflow_id* | UUID | Owning workflow |
name* | string | Phase name |
position* | integer | Ordinal position in the workflow |
color | string | null | Phase color |
curl "https://platform.ergondata.ai/api/v1/workflows/phases/granted?service=automations&workflow_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Triage",
"position": 0,
"color": "#4f46e5"
}
]/api/v1/workflows/fields/grantedList Granted Fields
Return phase fields inside workflows granted to the calling service. Mirrors phases/granted for the workflow -> phase -> field leg of the IAM hierarchy. phase_id narrows to a single phase (still restricted to granted workflows).
Bearer token required.
Query Parameters
| Name | Type | Description |
|---|---|---|
service* | string | Consumer service requesting the grants (e.g. automations) |
resource_id | string | null | Optional consumer resource scoping the grant lookup |
workflow_id | string | null | Narrow to a single granted workflow |
phase_id | string | null | Narrow to a single phase |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Field ID |
workflow_id* | UUID | Owning workflow |
name* | string | Field name |
field_type* | string | Field type slug (from field_types) |
position* | integer | Ordinal position |
phase_id | UUID | null | Owning phase (null for workflow-level fields) |
curl "https://platform.ergondata.ai/api/v1/workflows/fields/granted?service=automations&workflow_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Priority",
"field_type": "select",
"position": 0,
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
]/api/v1/workflows/workflows/{workflow_id}/claimersList Workflow Claimers
Principals who may claim items on any phase of the workflow. Backs the board's claimer avatar quick-filter; the pool is IAM's items:claim eligibility unioned across phases.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal kind (user, group, service) |
principal_id* | string | Principal ID |
label* | string | Display label |
display_name | string | null | Display name |
avatar_url | string | null | Avatar URL |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/claimers" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_type": "user",
"principal_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
"label": "Ada Lovelace",
"display_name": "Ada Lovelace",
"avatar_url": "https://ergon-files.s3.us-east-1.amazonaws.com/avatars/77778888-9999-aaaa-bbbb-ccccddddeeee/ada.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&X-Amz-Signature=..."
}
]/api/v1/workflows/workflows/{workflow_id}/eligible-principalsList Eligible Principals
Return principals eligible for routing groups in this workflow. Backs the assignment-group member pickers; assignments:view on the workflow is enforced.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal kind (user, group, service) |
principal_id* | string | Principal ID |
label* | string | Display label |
display_name | string | null | Display name |
avatar_url | string | null | Avatar URL |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/eligible-principals" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_type": "group",
"principal_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"label": "Tier-1 agents",
"display_name": "Tier-1 agents",
"avatar_url": null
}
]/api/v1/workflows/workflows/{workflow_id}/phase-groupsList Phase Groups
Return every phase-to-assignment-group binding in the workflow. Powers the assignment manager's phase x group matrix.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
workflow_id* | string (UUID) | Workflow ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Binding ID |
phase_id* | UUID | Bound phase |
group_id* | UUID | Bound assignment group |
is_default* | boolean | Whether this is the phase's default group |
created_at* | datetime | When the binding was created |
group_name | string | null | Assignment group name snapshot |
curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/phase-groups" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "33334444-5555-6666-7777-88889999aaaa",
"phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"group_id": "a7b8c9d0-e1f2-3456-0123-567890123456",
"is_default": true,
"created_at": "2026-06-01T12:00:00Z",
"group_name": "Tier-1 agents"
}
]