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.

Base URL/api/v1/workflows

Automation 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.

POST/api/v1/workflows/companies/{company_id}/workflows

Create 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`

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
`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",
  "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}
}

GET/api/v1/workflows/companies/{company_id}/workflows

List 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
}

GET/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
`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"
}

PATCH/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
`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
`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"
}

DELETE/api/v1/workflows/workflows/{workflow_id}

Delete Workflow

Delete a workflow and its federated zone.

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

PATCH/api/v1/workflows/workflows/{workflow_id}/folder

Move 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
`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"
}

PUT/api/v1/workflows/workflows/{workflow_id}/graph-layout

Save 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
`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}}}
}

DELETE/api/v1/workflows/workflows/{workflow_id}/graph-layout

Delete 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

GET/api/v1/workflows/workflows/{workflow_id}/attachment-bucket-targets

List 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": []
  }
]

GET/api/v1/workflows/workflows/{workflow_id}/record-worksheets

List 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}
]

GET/api/v1/workflows/workflows/{workflow_id}/record-worksheets/{worksheet_id}/columns

List 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

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"}
  ]
}

GET/api/v1/workflows/workflows/{workflow_id}/record-views

List 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"}
]

GET/api/v1/workflows/workflows/{workflow_id}/record-views/{view_id}/columns

List 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

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"}
  ]
}

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).

GET/api/v1/workflows/companies/{company_id}/folders

List 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"
  }
]

POST/api/v1/workflows/companies/{company_id}/folders

Create 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"
}

GET/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}
}

PATCH/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"
}

DELETE/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

GET/api/v1/workflows/folders/{folder_id}/workflows

List 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"}
  ]
}

GET/api/v1/workflows/companies/{company_id}/folder-order

Get 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"]}

PUT/api/v1/workflows/companies/{company_id}/folder-order

Update 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"]}

GET/api/v1/workflows/companies/{company_id}/workflow-favorites

List 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"
  }]
}

PUT/api/v1/workflows/workflows/{workflow_id}/favorite

Favorite 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"
}

DELETE/api/v1/workflows/workflows/{workflow_id}/favorite

Unfavorite 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 Content

Phases

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.

GET/api/v1/workflows/workflows/{workflow_id}/phases

List 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`
`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
`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,
    "field_count": 2,
    "item_count": 12,
    "created_at": "2026-06-01T12:00:00Z"
  }
]

POST/api/v1/workflows/workflows/{workflow_id}/phases

Create 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
`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`
`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
`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"
}

PATCH/api/v1/workflows/phases/{phase_id}

Update Phase

Update phase settings: name, color, terminal flag, timeouts, visibility windows, and assignee caps.

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
`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
`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`
`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
`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
}

DELETE/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

PUT/api/v1/workflows/workflows/{workflow_id}/phases/reorder

Reorder 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`
`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
`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}
]

GET/api/v1/workflows/phases/{phase_id}/eligible-assignees

List 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"}
  ]
}

GET/api/v1/workflows/phases/{phase_id}/working-hours

Get 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"]]}
}

PUT/api/v1/workflows/phases/{phase_id}/working-hours

Set 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"]]}
}

DELETE/api/v1/workflows/phases/{phase_id}/working-hours

Delete 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

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.

GET/api/v1/workflows/field-types

List 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}
  ]
}

GET/api/v1/workflows/workflows/{workflow_id}/fields

List 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"]}
  }
]

POST/api/v1/workflows/workflows/{workflow_id}/fields

Create 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.
`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
}

PUT/api/v1/workflows/workflows/{workflow_id}/fields/reorder

Reorder 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}
]

GET/api/v1/workflows/phases/{phase_id}/fields

List 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}
]

POST/api/v1/workflows/phases/{phase_id}/fields

Create 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.
`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
}

PUT/api/v1/workflows/phases/{phase_id}/fields/reorder

Reorder 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}
]

PATCH/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.

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
}

DELETE/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

POST/api/v1/workflows/fields/{field_id}/attachment-pipeline/schemas/generate

Generate 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"}]}
}

POST/api/v1/workflows/phases/{phase_id}/fields/attachment-pipeline/schemas/generate

Generate 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"}]}
}

POST/api/v1/workflows/workflows/{workflow_id}/fields/attachment-pipeline/schemas/generate

Generate 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.

GET/api/v1/workflows/workflows/{workflow_id}/field-rules

List 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"
  }
]

POST/api/v1/workflows/workflows/{workflow_id}/field-rules

Create 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
}

PUT/api/v1/workflows/workflows/{workflow_id}/field-rules/reorder

Reorder 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}
]

PATCH/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"
}

DELETE/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 Content

Condition 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.

GET/api/v1/workflows/workflows/{workflow_id}/condition-fields

Workflow 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"}
]

GET/api/v1/workflows/phases/{phase_id}/condition-fields

Phase 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"}
]

GET/api/v1/workflows/fields/{field_id}/condition-fields

Field 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"}
]

GET/api/v1/workflows/items/{item_id}/condition-fields

Item 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.

GET/api/v1/workflows/workflows/{workflow_id}/fields/{field_id}/records/columns

List 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"}
  ]
}

GET/api/v1/workflows/workflows/{workflow_id}/fields/{field_id}/records/search

Search 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": "[email protected]"}}
  ]
}

GET/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.

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

{
  "row_id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff",
  "label": "Acme Inc.",
  "values": {"email": "[email protected]"}
}

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.

GET/api/v1/workflows/workflows/{workflow_id}/routes

List 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
`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": []
  }
]

POST/api/v1/workflows/workflows/{workflow_id}/routes

Create 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
`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
`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
}

PATCH/api/v1/workflows/routes/{route_id}

Update Route

Update a route's assignment-carry behaviour, required fields, or annotation.

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
`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
`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
}

DELETE/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 Content

Items

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.

GET/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	Creator principal
`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	Whether the current phase has a routing group bound
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition
`visible_after`	datetime \| null	Item hidden until this timestamp
`visible_field_ids`	array<string> \| null	Field IDs the caller may see

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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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"]
}

PATCH/api/v1/workflows/items/{item_id}

Update Item

Update an item's title, description, field values, and timeout settings.

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
`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	Visibility delay on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay on transition

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	Creator principal
`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	Whether the current phase has a routing group bound
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition
`visible_after`	datetime \| null	Item hidden until this timestamp
`visible_field_ids`	array<string> \| null	Field IDs the caller may see

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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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"]
}

DELETE/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

POST/api/v1/workflows/items/{item_id}/claim

Claim 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	Creator principal
`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	Whether the current phase has a routing group bound
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition
`visible_after`	datetime \| null	Item hidden until this timestamp
`visible_field_ids`	array<string> \| null	Field IDs the caller may see

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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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"]
}

POST/api/v1/workflows/items/{item_id}/release

Release Item

Release the calling principal's claim on the item, returning it to the routing group.

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	Creator principal
`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	Whether the current phase has a routing group bound
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition
`visible_after`	datetime \| null	Item hidden until this timestamp
`visible_field_ids`	array<string> \| null	Field IDs the caller may see

curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/release" \
  -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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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"]
}

POST/api/v1/workflows/items/{item_id}/assign

Assign Item

Assign the item to a specific principal eligible for the current phase.

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

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	Creator principal
`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	Whether the current phase has a routing group bound
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition
`visible_after`	datetime \| null	Item hidden until this timestamp
`visible_field_ids`	array<string> \| null	Field IDs the caller may see

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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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"]
}

POST/api/v1/workflows/items/{item_id}/assign-group

Assign Item Group

Assign the item to a routing group, distributing it to that group's members.

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	Creator principal
`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	Whether the current phase has a routing group bound
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition
`visible_after`	datetime \| null	Item hidden until this timestamp
`visible_field_ids`	array<string> \| null	Field IDs the caller may see

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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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"]
}

POST/api/v1/workflows/items/{item_id}/route

Route Item

Move the item to a target phase following the workflow's transition graph.

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

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	Creator principal
`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	Whether the current phase has a routing group bound
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition
`visible_after`	datetime \| null	Item hidden until this timestamp
`visible_field_ids`	array<string> \| null	Field IDs the caller may see

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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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"]
}

POST/api/v1/workflows/items/{item_id}/route-to-global-target

Route Item To Global Target

Move the item to the workflow's configured global-timeout target phase, bypassing the transition graph. The body is intentionally empty; the destination is read from the workflow settings. If the target is cleared or the item is already there, returns the item unchanged.

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	Creator principal
`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	Whether the current phase has a routing group bound
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition
`visible_after`	datetime \| null	Item hidden until this timestamp
`visible_field_ids`	array<string> \| null	Field IDs the caller may see

curl -X POST "https://platform.ergondata.ai/api/v1/workflows/items/c3d4e5f6-a7b8-9012-cdef-123456789012/route-to-global-target" \
  -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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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"]
}

GET/api/v1/workflows/items/{item_id}/claimability

Get 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"
}

GET/api/v1/workflows/items/{item_id}/assignable-principals

List 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
  }
]

GET/api/v1/workflows/items/{item_id}/form-context

Get 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": {}
}

GET/api/v1/workflows/items/{item_id}/messaging-options

Get 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": "[email protected]",
      "display_name": "Acme Support",
      "direction": "outbound",
      "status": "active"
    }
  ],
  "allowed_address_ids": ["11112222-3333-4444-5555-666677778888"],
  "allowed_channel_types": ["email"]
}

GET/api/v1/workflows/items/{item_id}/events

List Events

Return the item's activity/event history, newest first, with pagination.

Bearer token required.

Path Parameters

Name	Type	Description
`item_id`*	string (UUID)	Item ID

Query Parameters

Name	Type	Description
`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
}

GET/api/v1/workflows/items/granted

List 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"
  }
]

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.

GET/api/v1/workflows/items/{item_id}/children

List 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"
  }
]

DELETE/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

GET/api/v1/workflows/items/{item_id}/child-capabilities

Get 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.

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
}

GET/api/v1/workflows/items/{item_id}/child-targets

List 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": []
            }
          ]
        }
      ]
    }
  ]
}

POST/api/v1/workflows/items/bulk-create

Bulk 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
}

POST/api/v1/workflows/items/bulk-delete

Bulk 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
}

POST/api/v1/workflows/items/bulk-route

Bulk 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.

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
`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" \
  -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"],
  "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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
      "created_at": "2026-06-01T12:00:00Z",
      "updated_at": "2026-06-02T09:30:00Z"
    }
  ]
}

POST/api/v1/workflows/workflows/{workflow_id}/items

Create 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_id -> value
`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	Creator principal ID
`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: `[]`

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": {"d4e5f6a7-b8c9-0123-def0-234567890123": 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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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", "value": 1042}],
  "card_fields": []
}

GET/api/v1/workflows/workflows/{workflow_id}/items

List 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	Free-text search
`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 returns all, capped at 10000; max 5000)Default: `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
}

POST/api/v1/workflows/workflows/{workflow_id}/items/query

Query 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)
`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-5000)Default: `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
}

POST/api/v1/workflows/workflows/{workflow_id}/items/bulk-create

Bulk 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
}

POST/api/v1/workflows/workflows/{workflow_id}/items/bulk-delete

Bulk 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
}

POST/api/v1/workflows/workflows/{workflow_id}/items/bulk-route

Bulk Route Items

Path-scoped bulk route: move up to 1000 items in the workflow named in the URL to a target phase.

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
`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-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"],
  "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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
      "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.

GET/api/v1/workflows/items/{item_id}/comments

List Comments

Return the full comment thread for an item, oldest first.

Bearer token required.

Path Parameters

Name	Type	Description
`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/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"
  }
]

POST/api/v1/workflows/items/{item_id}/comments

Create Comment

Add a new comment to an item, optionally with file attachments.

Bearer token required.

Path Parameters

Name	Type	Description
`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/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"
}

PATCH/api/v1/workflows/comments/{comment_id}

Update Comment

Edit the content or attachments of an existing comment.

Bearer token required.

Path Parameters

Name	Type	Description
`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/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"
}

DELETE/api/v1/workflows/comments/{comment_id}

Delete Comment

Permanently remove a comment from its item thread.

Bearer token required.

Path Parameters

Name	Type	Description
`comment_id`*	string (UUID)	Comment ID

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)

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. 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.

POST/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments/upload-url

Request 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.

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
`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
}

POST/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments/confirm

Confirm 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.

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
`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
  }
]

GET/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments/download-url

Request Download URL

Return a short-lived presigned GET URL to download a stored attachment by its object_key.

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

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
}

GET/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments/results

Attachment 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"
  }
}

GET/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments/status

Attachment 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

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
  }
]

DELETE/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/attachments

Remove Attachment

Remove a single attachment from a field, identified by field_id and object_key. Returns the remaining attachments on the field.

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
`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

[]

POST/api/v1/workflows/workflows/{workflow_id}/items/{item_id}/comment-attachments/upload-url

Request 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.

GET/api/v1/workflows/workflows/{workflow_id}/assignment-groups

List 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"]
  }
]

POST/api/v1/workflows/workflows/{workflow_id}/assignment-groups

Create 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": []
}

PATCH/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"]
}

DELETE/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

GET/api/v1/workflows/assignment-groups/{group_id}/members

List 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"
  }
]

POST/api/v1/workflows/assignment-groups/{group_id}/members

Add 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"
}

DELETE/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

GET/api/v1/workflows/assignment-groups/{group_id}/channels

List 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"
  }
]

PUT/api/v1/workflows/assignment-groups/{group_id}/channels

Set 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"
  }
]

GET/api/v1/workflows/assignment-groups/{group_id}/phases

List 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}
  }
]

PUT/api/v1/workflows/assignment-groups/{group_id}/phases

Set 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": {}
  }
]

PUT/api/v1/workflows/phases/{phase_id}/assignment-groups

Set 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"
  }
]

GET/api/v1/workflows/phases/{phase_id}/assignment-groups/{group_id}/config

Get 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, ...)
`assignment_active`*	boolean	Whether automatic assignment is active
`assignment_config`	object	Strategy-specific configuration blob

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}
}

PATCH/api/v1/workflows/phases/{phase_id}/assignment-groups/{group_id}/config

Update Phase Group Routing

Update the routing strategy, active flag, or config blob 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, ...)
`assignment_active`	boolean \| null	Whether automatic assignment is active
`assignment_config`	object \| null	Strategy-specific configuration blob

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, ...)
`assignment_active`*	boolean	Whether automatic assignment is active
`assignment_config`	object	Strategy-specific configuration blob

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": {}
}

DELETE/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

PUT/api/v1/workflows/phases/{phase_id}/assignment-groups/{group_id}/capacities

Set 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
  }
]

GET/api/v1/workflows/workflows/{workflow_id}/assignment-capacities

List 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.

GET/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"]}
}

PATCH/api/v1/workflows/workflow-views/{view_id}

Update View

Update a view's name, type, position, or config (layouts, fields, phases, filters).

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"]}
}

DELETE/api/v1/workflows/workflow-views/{view_id}

Delete View

Delete a saved view. Items are unaffected; only the projection is removed.

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

PUT/api/v1/workflows/workflow-views/{view_id}/favorite

Set 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"]}
}

GET/api/v1/workflows/workflows/{workflow_id}/views

List 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"
  }
]

POST/api/v1/workflows/workflows/{workflow_id}/views

Create 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"]}
}

PATCH/api/v1/workflows/workflows/{workflow_id}/views/order

Reorder 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}
]

GET/api/v1/workflows/workflows/{workflow_id}/views/all/items

List 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
}

POST/api/v1/workflows/workflows/{workflow_id}/views/all/items/query

Query All View Items

Filtered, paginated item listing across the workflow's views. Matches 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	Free-text search (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-5000)Default: `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
}

GET/api/v1/workflows/workflow-views/{view_id}/phases

List 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`
`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,
    "item_count": 12,
    "created_at": "2026-06-01T12:00:00Z"
  }
]

GET/api/v1/workflows/workflow-views/{view_id}/routes

List View Routes

List the routes (phase transitions) available within a view's phase scope.

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"
  }
]

GET/api/v1/workflows/workflow-views/{view_id}/claimers

List 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
  }
]

GET/api/v1/workflows/workflow-views/{view_id}/fields

List 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"
  }
]

GET/api/v1/workflows/workflow-views/{view_id}/fields/{field_id}/records/search

Search 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"}
  ]
}

GET/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"}
}

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 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.

GET/api/v1/workflows/workflow-views/{view_id}/items

List View Items

List items visible through a saved view, with search, assignment filter, sorting, and pagination.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string	Saved view ID

Query Parameters

Name	Type	Description
`search`	string \| null	Free-text search (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–5000)Default: `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
}

GET/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	Creator principal
`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	Whether the current phase has an assignment group
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition

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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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
}

POST/api/v1/workflows/workflow-views/{view_id}/items

Create View Item

Create an item through a view. The target phase must be one the view exposes, and field values keyed to fields the caller cannot edit are dropped. After creation the item is re-checked against the view predicate — if it falls outside the view's locked filters the request is rejected (422) and rolled back.

Bearer token required.

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 to link under
`field_values`	object \| null	Field ID → value map (non-editable fields dropped)
`timeout_minutes`	number \| null	Phase timeout in minutes
`global_timeout_minutes`	number \| null	Global timeout in minutes
`visibility_timeout_on_create_minutes`	integer \| null	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on 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
`created_by`*	UUID \| null	Creator principal
`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	Whether the current phase has an assignment group
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition

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": {"44445555-6666-7777-8888-9999aaaabbbb": "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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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
}

POST/api/v1/workflows/workflow-views/{view_id}/items/query

Query View Items

Filtered, paginated item listing through a view. 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	Free-text search (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–5000)Default: `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
}

PATCH/api/v1/workflows/workflow-views/{view_id}/items/{item_id}

Update View Item

Edit an item through a view (same-phase field edits and title). Cross-phase moves go through the route endpoint. Field values are 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 ID → value map (restricted to editable view fields)
`target_phase_id`	UUID \| null	Target phase for field-set context
`timeout_minutes`	number \| null	Phase timeout in minutes
`global_timeout_minutes`	number \| null	Global timeout in minutes
`visibility_timeout_on_create_minutes`	integer \| null	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on 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
`created_by`*	UUID \| null	Creator principal
`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	Whether the current phase has an assignment group
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition

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": {"44445555-6666-7777-8888-9999aaaabbbb": "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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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
}

DELETE/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

GET/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/assignable-principals

List 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": "[email protected]",
    "via_team_id": "77778888-9999-aaaa-bbbb-ccccddddeeee",
    "eligible": true
  }
]

GET/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/form-context

Get 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": {}
}

POST/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/assign

Assign 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	Creator principal
`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	Whether the current phase has an assignment group
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition

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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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
}

POST/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/claim

Claim 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	Creator principal
`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	Whether the current phase has an assignment group
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition

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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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
}

POST/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/release

Release View Item

Release a claim through a saved view (view-scoped self-release).

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	Creator principal
`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	Whether the current phase has an assignment group
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition

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}"

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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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
}

POST/api/v1/workflows/workflow-views/{view_id}/items/{item_id}/route

Route 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 may leave the view's board if the target phase is not part of the view config.

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

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	Creator principal
`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	Whether the current phase has an assignment group
`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	Visibility delay applied on create
`visibility_timeout_on_release_minutes`	integer \| null	Visibility delay applied on release
`visibility_timeout_on_transition_minutes`	integer \| null	Visibility delay applied on transition

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": "77778888-9999-aaaa-bbbb-ccccddddeeee",
  "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
}

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.

GET/api/v1/workflows/workflow-views/{view_id}/access/eligible

List 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
  }
]

GET/api/v1/workflows/workflow-views/{view_id}/access/grants

List 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
}

GET/api/v1/workflows/workflow-views/{view_id}/access/permissions

List 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
  }
]

GET/api/v1/workflows/workflow-views/{view_id}/access/resource-types

List 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
    }
  ]
}

POST/api/v1/workflows/workflow-views/{view_id}/access/grants

Create 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"
}

DELETE/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.

GET/api/v1/workflows/workflows/{workflow_id}/connections

List 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": []
}

POST/api/v1/workflows/workflows/{workflow_id}/connections

Create 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
  }
}

DELETE/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)

GET/api/v1/workflows/workflows/{workflow_id}/access/connections

List 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
  }
]

DELETE/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)

GET/api/v1/workflows/workflows/{workflow_id}/access/connection-requests

List 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:items:view"],
    "decided_at": null,
    "decided_by": null
  }
]

POST/api/v1/workflows/workflows/{workflow_id}/access/connection-requests/{request_id}/approve

Approve 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:items:view"],
  "decided_at": "2026-06-01T12:05:00Z",
  "decided_by": "member:55556666-7777-8888-9999-aaaabbbbcccc"
}

POST/api/v1/workflows/workflows/{workflow_id}/access/connection-requests/{request_id}/reject

Reject 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:items:view"],
  "decided_at": "2026-06-01T12:05:00Z",
  "decided_by": "member:55556666-7777-8888-9999-aaaabbbbcccc"
}

GET/api/v1/workflows/folders/{folder_id}/access/connection-requests

List 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

[]

POST/api/v1/workflows/folders/{folder_id}/access/connection-requests/{request_id}/approve

Approve 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"}

POST/api/v1/workflows/folders/{folder_id}/access/connection-requests/{request_id}/reject

Reject 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}

GET/api/v1/workflows/folders/{folder_id}/access/connections

List 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

[]

DELETE/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)

POST/api/v1/workflows/workflows/{workflow_id}/connection-requests/{request_id}/withdraw

Withdraw 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).

GET/api/v1/workflows/workflows/{workflow_id}/access/eligible

List 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
  }
]

GET/api/v1/workflows/workflows/{workflow_id}/access/grants

List 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
}

GET/api/v1/workflows/workflows/{workflow_id}/access/grants/grouped

List 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
}

GET/api/v1/workflows/workflows/{workflow_id}/access/permissions

List 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:items:manage",
    "friendly_name": "Manage items",
    "description": "Create, edit, and delete items",
    "scope_anchor": "instance",
    "display_order": 10,
    "resource_type_id": "c1c1c1c1-d2d2-e3e3-f4f4-a5a5b6b6c7c7",
    "parent_resource_type_slug": "workflow"
  }
]

GET/api/v1/workflows/workflows/{workflow_id}/access/resource-types

List 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:items:manage",
      "friendly_name": "Manage items",
      "scope_anchor": "instance",
      "display_order": 10
    }
  ]
}

POST/api/v1/workflows/workflows/{workflow_id}/access/grants

Create 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"
}

DELETE/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

GET/api/v1/workflows/folders/{folder_id}/access/eligible

List 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
  }
]

GET/api/v1/workflows/folders/{folder_id}/access/grants

List 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
}

GET/api/v1/workflows/folders/{folder_id}/access/permissions

List 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:manage",
    "friendly_name": "Manage items",
    "description": "Create, edit, and delete items",
    "scope_anchor": "instance",
    "display_order": 10,
    "resource_type_id": "c1c1c1c1-d2d2-e3e3-f4f4-a5a5b6b6c7c7",
    "parent_resource_type_slug": "workflow"
  }
]

GET/api/v1/workflows/folders/{folder_id}/access/resource-types

List 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:items:manage",
      "friendly_name": "Manage items",
      "scope_anchor": "instance",
      "display_order": 10
    }
  ]
}

POST/api/v1/workflows/folders/{folder_id}/access/grants

Create 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"
}

DELETE/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 Content

Cross-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.

GET/api/v1/workflows/workflows/{workflow_id}/grants

List 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"
  }
]

POST/api/v1/workflows/workflows/{workflow_id}/grants

Create 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"
}

DELETE/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 Content

Batch 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.

POST/api/v1/workflows/folders/access/grants/batch

Create 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}
}

POST/api/v1/workflows/workflows/access/grants/batch

Create 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}}

POST/api/v1/workflows/workflow-views/access/grants/batch

Create 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.

GET/api/v1/workflows/workflows/{workflow_id}/activity

List 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	Free-text search across events
`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

curl "https://platform.ergondata.ai/api/v1/workflows/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890/activity?event_type=item.created&page=1&limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "22223333-4444-5555-6666-777788889999",
      "event_type": "item.created",
      "actor_type": "user",
      "actor_label": "Ada Lovelace",
      "data": {"item_id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff"},
      "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"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

GET/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. item.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 snapshot

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": "item.phase_changed",
  "actor_type": "user",
  "actor_label": "Ada Lovelace",
  "data": {"from_phase": "Triage", "to_phase": "In progress"},
  "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"
}

GET/api/v1/workflows/folders/{folder_id}/activity

List 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	Free-text search across events
`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

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": "item.created",
      "actor_type": "user",
      "actor_label": "Ada Lovelace",
      "data": {},
      "created_at": "2026-06-01T12:00:00Z",
      "correlation_id": null,
      "item_id": "88889999-aaaa-bbbb-cccc-ddddeeeeffff",
      "item_title": "Refund request #4821",
      "workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "workflow_name": "Support queue"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

GET/api/v1/workflows/companies/{company_id}/inbox-items

List 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 (mutually exclusive with claimable_for).
`claimable_for`	string \| null	Pass 'me' for claimable items (mutually exclusive with assigned_to=me).
`workflow_ids`	string \| null	Comma-separated workflow UUIDs to narrow the inbox
`phase_ids`	string \| null	Comma-separated phase UUIDs
`search`	string \| null	Filter by title (ilike)
`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 returns all items (capped at 10 000).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
}

GET/api/v1/workflows/companies/{company_id}/inbox-workflows

List 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
  }
]

GET/api/v1/workflows/workflows/granted

List 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"
  }
]

GET/api/v1/workflows/folders/granted

List 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"
  }
]

GET/api/v1/workflows/phases/granted

List 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"
  }
]

GET/api/v1/workflows/fields/granted

List 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"
  }
]

GET/api/v1/workflows/workflows/{workflow_id}/claimers

List 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=..."
  }
]

GET/api/v1/workflows/workflows/{workflow_id}/eligible-principals

List 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
  }
]

GET/api/v1/workflows/workflows/{workflow_id}/phase-groups

List 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"
  }
]