Workflows

Tags: automation, workflows

A Workflow defines a multi-step process an Agent runs: its Tasks, permitted actions, channels, and escalation rules. These endpoints create and update Workflows, manage revisions and publishing, validate a configuration before launch, and expose per-Workflow activity, diagrams, and statistics.

In the product: Workflows

Resources

Request and response models used by the endpoints on this page.

AbilityConfigIssue

Field	Type	Required	Description
abilityType	String	✓
code	Literal[missing_resource, invalid_state, feature_disabled, missing_connection, external_drift]	✓
eventType	String
message	String	✓
objectType	String
resourceId	int	str
resourceName	String
resourceType	String
severity	Literal[warning, error]	✓
taskId	Integer

Example:

{
  "severity": null  // Literal[warning, error],
  "code": null  // Literal[missing_resource, invalid_state, feature_disabled, missing_connection, external_drift],
  "abilityType": "string"  // String,
  "taskId": 0  // Integer, optional,
  "resourceType": "string"  // String, optional,
  "resourceId": "string"  // int | str, optional,
  "resourceName": "string"  // String, optional,
  "objectType": "string"  // String, optional,
  "eventType": "string"  // String, optional,
  "message": "string"  // String
}

AbilityResponse

Field	Type	Required	Description
abilityType	String	✓
celCondition	String
config	Dict[str, Any]	✓
enabled	Boolean	✓
id	Integer	✓
uuid	String	✓

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "abilityType": "string"  // String,
  "config": {}  // Dict[str, Any],
  "enabled": false  // Boolean,
  "celCondition": "string"  // String, optional
}

ActivateWorkflowRevisionRequest

Field	Type	Required	Description
allowDraft	Boolean		Default: False

Example:

{
  "allowDraft": false  // Boolean, optional, default: False
}

CloneWorkflowRequest

Field	Type	Required	Description
name	String	✓

Example:

{
  "name": "string"  // String
}

EditRevisionAsDraftRequest

Field	Type	Required	Description
discardDraftChanges	Boolean		Default: False

Example:

{
  "discardDraftChanges": false  // Boolean, optional, default: False
}

EventRuleResponse

Field	Type	Required	Description
actionParams	Dict[str, Any]	✓
actionType	<enum EventRuleActionType	✓
active	Boolean	✓
appConnectionId	Integer
calendarEventTypeId	Integer	✓
calendarId	Integer	✓
celBlockedAt	DateTime
conditions	String	✓
createdAt	DateTime	✓
dataTypeId	Integer	✓
dataTypeName	String
delay	Integer	✓
error	String	✓
errorMessage	String	✓
eventType	<enum EventRuleEventType	✓
failedAt	DateTime	✓
id	Integer	✓
journeyId	Integer
journeyStepId	Integer	✓
name	String	✓
objectType	<enum EventRuleObjectType	✓
order	Integer	✓
routineId	Integer	✓
taskId	Integer	✓
taskName	String
taskWorkflowId	Integer
triggerParams	Dict[str, Any]	✓
updatedAt	DateTime	✓
uuid	String	✓
workflowRevisionId	Integer	✓

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "objectType": null  // <enum EventRuleObjectType,
  "name": "string"  // String,
  "eventType": null  // <enum EventRuleEventType,
  "conditions": "string"  // String,
  "actionType": null  // <enum EventRuleActionType,
  "actionParams": {}  // Dict[str, Any],
  "triggerParams": {}  // Dict[str, Any],
  "active": false  // Boolean,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "taskId": 0  // Integer,
  "taskName": "string"  // String, optional,
  "taskWorkflowId": 0  // Integer, optional,
  "dataTypeId": 0  // Integer,
  "dataTypeName": "string"  // String, optional,
  "routineId": 0  // Integer,
  "workflowRevisionId": 0  // Integer,
  "calendarId": 0  // Integer,
  "calendarEventTypeId": 0  // Integer,
  "journeyStepId": 0  // Integer,
  "journeyId": 0  // Integer, optional,
  "appConnectionId": 0  // Integer, optional,
  "error": "string"  // String,
  "errorMessage": "string"  // String,
  "failedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "celBlockedAt": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "delay": 0  // Integer,
  "order": 0  // Integer
}

PublishWorkflowRevisionRequest

Field	Type	Required	Description
publishNotes	String
revisionName	String
setActive	Boolean		Default: True

Example:

{
  "revisionName": "string"  // String, optional,
  "publishNotes": "string"  // String, optional,
  "setActive": false  // Boolean, optional, default: True
}

TaskChatResponse

Field	Type	Required	Description
assignmentId	Integer	✓
chatId	Integer	✓
chatUuid	String	✓
currentTaskName	String	✓
lastMessageAt	String
memberId	Integer	✓
memberName	String	✓
messageCount	Integer		Default: 0
summary	String
title	String
workflowName	String	✓

Example:

{
  "chatId": 0  // Integer,
  "chatUuid": "string"  // String,
  "title": "string"  // String, optional,
  "summary": "string"  // String, optional,
  "assignmentId": 0  // Integer,
  "memberName": "string"  // String,
  "memberId": 0  // Integer,
  "currentTaskName": "string"  // String,
  "workflowName": "string"  // String,
  "lastMessageAt": "string"  // String, optional,
  "messageCount": 0  // Integer, optional, default: 0
}

TaskChatsListResponse

Field	Type	Required	Description
items	Array	✓
limit	Integer	✓
offset	Integer	✓
total	Integer	✓

Example:

{
  "items": []  // Array<TaskChatResponse>,
  "total": 0  // Integer,
  "limit": 0  // Integer,
  "offset": 0  // Integer
}

UpdateWorkflowRevisionMetadataRequest

Field	Type	Required	Description
publishNotes	String
revisionName	String

Example:

{
  "revisionName": "string"  // String, optional,
  "publishNotes": "string"  // String, optional
}

UpdateWorkflowRevisionRequest

Field	Type	Required	Description
abilities	Array
assistantIdentity	String
assistantName	String
chatModelConfig	Object
chatModelId	String
copyFromAgentId	Integer
copyFromWorkflowRevisionId	Integer
copySourceDigest	String
dataTypeSlug	String
defaultInboxId	Integer
defaultPhoneNumberId	Integer
description	String
eventRules	Array
memberRoleAccess	Array
name	String
ownerId	Integer
posX	Number
posY	Number
prompt	String
realtimeModelConfig	Object
realtimeModelId	String
routingMode	WorkflowRoutingMode
startTaskId	Integer

Example:

{
  "name": "string"  // String, optional,
  "description": "string"  // String, optional,
  "prompt": "string"  // String, optional,
  "ownerId": 0  // Integer, optional,
  "startTaskId": 0  // Integer, optional,
  "copyFromAgentId": 0  // Integer, optional,
  "copyFromWorkflowRevisionId": 0  // Integer, optional,
  "copySourceDigest": "string"  // String, optional,
  "assistantName": "string"  // String, optional,
  "assistantIdentity": "string"  // String, optional,
  "chatModelId": "string"  // String, optional,
  "chatModelConfig": {}  // Object, optional,
  "realtimeModelId": "string"  // String, optional,
  "realtimeModelConfig": {}  // Object, optional,
  "defaultPhoneNumberId": 0  // Integer, optional,
  "defaultInboxId": 0  // Integer, optional,
  "routingMode": null  // WorkflowRoutingMode, optional,
  "dataTypeSlug": "string"  // String, optional,
  "posX": 0.0  // Number, optional,
  "posY": 0.0  // Number, optional,
  "abilities": []  // Array<AbilityData>, optional,
  "eventRules": []  // Array<EventRuleData>, optional,
  "memberRoleAccess": []  // Array<WorkflowMemberRoleAccessRequest>, optional
}

WorkflowAccessValidationResponse

Field	Type	Required	Description
warnings	Array	✓

Example:

{
  "warnings": []  // Array<WorkflowAccessWarning>
}

WorkflowAccessWarning

Field	Type	Required	Description
abilityType	String	✓
neededAccess	String	✓
neededAccessMask	Integer	✓
resourceId	Integer	✓
resourceName	String	✓
resourceType	Literal[form, file, folder, calendar]	✓
roleId	Integer	✓
roleName	String	✓
taskId	Integer	✓
taskName	String	✓

Example:

{
  "roleId": 0  // Integer,
  "roleName": "string"  // String,
  "taskId": 0  // Integer,
  "taskName": "string"  // String,
  "abilityType": "string"  // String,
  "resourceType": null  // Literal[form, file, folder, calendar],
  "resourceId": 0  // Integer,
  "resourceName": "string"  // String,
  "neededAccess": "string"  // String,
  "neededAccessMask": 0  // Integer
}

WorkflowConfigValidationResponse

Field	Type	Required	Description
issues	Array	✓

Example:

{
  "issues": []  // Array<AbilityConfigIssue>
}

WorkflowContributorResponse

Field	Type	Required	Description
channels	Array	✓
createdAt	DateTime	✓
hint	String
id	Integer	✓
memberId	Integer	✓
title	String	✓
updatedAt	DateTime	✓
workflowRevisionId	Integer	✓

Example:

{
  "id": 0  // Integer,
  "workflowRevisionId": 0  // Integer,
  "memberId": 0  // Integer,
  "title": "string"  // String,
  "channels": "string"  // Array<String>,
  "hint": "string"  // String, optional,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime
}

WorkflowDetailResponse

Field	Type	Required	Description
activeRevision	WorkflowRevisionSummaryResponse
draftRevision	WorkflowRevisionResponse	✓
workflow	WorkflowResponse	✓

Example:

{
  "workflow": null  // WorkflowResponse,
  "draftRevision": null  // WorkflowRevisionResponse,
  "activeRevision": null  // WorkflowRevisionSummaryResponse, optional
}

WorkflowMemberRoleAccessResponse

Field	Type	Required	Description
accessMode	Integer	✓
memberRoleId	Integer	✓
memberRoleName	String	✓

Example:

{
  "memberRoleId": 0  // Integer,
  "memberRoleName": "string"  // String,
  "accessMode": 0  // Integer
}

WorkflowRevisionDiffFieldChange

Field	Type	Required	Description
base	Any
field	String	✓
other	Any

Example:

{
  "field": "string"  // String,
  "base": null  // Any, optional,
  "other": null  // Any, optional
}

WorkflowRevisionDiffResponse

Field	Type	Required	Description
abilities	WorkflowRevisionDiffAbilities	✓
base	WorkflowRevisionDiffSide	✓
edges	WorkflowRevisionDiffEdges	✓
eventRules	WorkflowRevisionDiffEventRules	✓
other	WorkflowRevisionDiffSide	✓
revisionFields	Array
tasks	WorkflowRevisionDiffTasks	✓

Example:

{
  "base": null  // WorkflowRevisionDiffSide,
  "other": null  // WorkflowRevisionDiffSide,
  "revisionFields": []  // Array<WorkflowRevisionDiffFieldChange>, optional, default: PydanticUndefined,
  "tasks": null  // WorkflowRevisionDiffTasks,
  "edges": null  // WorkflowRevisionDiffEdges,
  "abilities": null  // WorkflowRevisionDiffAbilities,
  "eventRules": null  // WorkflowRevisionDiffEventRules
}

WorkflowRevisionListResponse

Field	Type	Required	Description
revisions	Array	✓
workflow	WorkflowResponse	✓

Example:

{
  "workflow": null  // WorkflowResponse,
  "revisions": []  // Array<WorkflowRevisionSummaryResponse>
}

WorkflowRevisionResponse

Field	Type	Required	Description
abilities	Array
archivedTaskCount	Integer		Default: 0
assistantConfigDigest	String	✓
assistantIdentity	String
assistantName	String
chatModelConfig	Object
chatModelId	String	✓
contributors	Array
createdAt	DateTime	✓
dataTypeSlug	String
eventRules	Array
id	Integer	✓
memberRoleAccess	Array
permissions	Integer		Default: 0
posX	Number
posY	Number
prompt	String
publishNotes	String
publishedAt	DateTime
publishedByAccountUuid	String
realtimeModelConfig	Object
realtimeModelId	String
revisionName	String
revisionNumber	Integer
routingMode	String		Default: open_world
startTaskId	Integer
taskCount	Integer		Default: 0
updatedAt	DateTime	✓
uuid	String	✓
workflowId	Integer	✓
workflowName	String
workflowUuid	String	✓

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "workflowId": 0  // Integer,
  "workflowUuid": "string"  // String,
  "workflowName": "string"  // String, optional,
  "revisionNumber": 0  // Integer, optional,
  "revisionName": "string"  // String, optional,
  "publishNotes": "string"  // String, optional,
  "publishedAt": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "publishedByAccountUuid": "string"  // String, optional,
  "prompt": "string"  // String, optional,
  "assistantName": "string"  // String, optional,
  "assistantIdentity": "string"  // String, optional,
  "assistantConfigDigest": "string"  // String,
  "startTaskId": 0  // Integer, optional,
  "chatModelId": "string"  // String,
  "chatModelConfig": {}  // Object, optional,
  "realtimeModelId": "string"  // String, optional,
  "realtimeModelConfig": {}  // Object, optional,
  "routingMode": "string"  // String, optional, default: open_world,
  "dataTypeSlug": "string"  // String, optional,
  "posX": 0.0  // Number, optional,
  "posY": 0.0  // Number, optional,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "taskCount": 0  // Integer, optional, default: 0,
  "archivedTaskCount": 0  // Integer, optional, default: 0,
  "permissions": 0  // Integer, optional, default: 0,
  "memberRoleAccess": []  // Array<WorkflowMemberRoleAccessResponse>, optional, default: PydanticUndefined,
  "abilities": []  // Array<AbilityResponse>, optional, default: PydanticUndefined,
  "eventRules": []  // Array<EventRuleResponse>, optional, default: PydanticUndefined,
  "contributors": []  // Array<WorkflowContributorResponse>, optional, default: PydanticUndefined
}

WorkflowRevisionSummaryResponse

Field	Type	Required	Description
createdAt	DateTime	✓
createdFromWorkflowRevisionId	Integer
id	Integer	✓
publishNotes	String
publishedAt	DateTime
publishedByAccountUuid	String
revisionName	String
revisionNumber	Integer
updatedAt	DateTime	✓
uuid	String	✓
workflowId	Integer	✓

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "workflowId": 0  // Integer,
  "revisionNumber": 0  // Integer, optional,
  "revisionName": "string"  // String, optional,
  "publishNotes": "string"  // String, optional,
  "createdFromWorkflowRevisionId": 0  // Integer, optional,
  "publishedAt": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "publishedByAccountUuid": "string"  // String, optional,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime
}

WorkflowRouteDryRunResponse

Field	Type	Required	Description
assignmentId	Integer	✓
candidateChildTaskIds	Array
chatId	Integer	✓
edgeCount	Integer	✓
errorType	String
issues	Array
sourceAssignmentTaskId	Integer
sourceTaskId	Integer
status	String	✓
winningChildTaskId	Integer

Example:

{
  "assignmentId": 0  // Integer,
  "chatId": 0  // Integer,
  "sourceTaskId": 0  // Integer, optional,
  "sourceAssignmentTaskId": 0  // Integer, optional,
  "status": "string"  // String,
  "edgeCount": 0  // Integer,
  "candidateChildTaskIds": 0  // Array<Integer>, optional, default: PydanticUndefined,
  "winningChildTaskId": 0  // Integer, optional,
  "errorType": "string"  // String, optional,
  "issues": []  // Array<AbilityConfigIssue>, optional, default: PydanticUndefined
}

WorkflowTemplateResponse

Field	Type	Required	Description
available	Boolean	✓
defaultWorkflowName	String	✓
exampleConversation	String	✓
icon	String	✓
longDescription	String	✓
name	String	✓
requiredFeatures	Array	✓
shortDescription	String	✓
tags	Array
uuid	String	✓

Example:

{
  "uuid": "string"  // String,
  "name": "string"  // String,
  "icon": "string"  // String,
  "shortDescription": "string"  // String,
  "longDescription": "string"  // String,
  "defaultWorkflowName": "string"  // String,
  "exampleConversation": "string"  // String,
  "requiredFeatures": "string"  // Array<String>,
  "tags": "string"  // Array<String>, optional, default: PydanticUndefined,
  "available": false  // Boolean
}

Endpoints

Create & manage

• POST /api/v2/w/{workspace_uuid}/workflows - Create
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id} - Get Workflow Id
• PUT /api/v2/w/{workspace_uuid}/workflows/{workflow_id} - Update Workflow Id

List, revisions & publishing

• GET /api/v2/w/{workspace_uuid}/workflows - List
• GET /api/v2/w/{workspace_uuid}/workflows/templates - Templates
• POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/publish - Publish
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions - Revisions
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions/{revision_id} - Revisions
• PATCH /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions/{revision_id} - Update Revisions
• POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions/{revision_id}/activate - Activate
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions/{revision_id}/diff - Diff
• POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions/{revision_id}/edit - Edit

Archive & delete

• DELETE /api/v2/w/{workspace_uuid}/workflows/{workflow_id} - Delete Workflow Id
• POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/archive - Archive
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/deletion-preview - Deletion Preview
• POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/unarchive - Unarchive

Validation

• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/route-dry-run - Route Dry Run
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/validate-access - Validate Access
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/validate-config - Validate Config

Templates

• POST /api/v2/w/{workspace_uuid}/workflows/templates/{template_uuid}/create-workflow - Create Workflow

Contributors

• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/contributors - Contributors
• POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/contributors - Contributors
• DELETE /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/contributors/{contributor_id} - Delete Contributors
• PATCH /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/contributors/{contributor_id} - Update Contributors

Activity, diagrams & thumbnails

• GET /api/v2/w/{workspace_uuid}/workflows/activity/batch - Batch
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/activity - Activity
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/diagram - Diagram
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/thumbnail - Thumbnail

Statistics & cloning

• POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/clone - Clone
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/task-assignment-stats - Task Assignment Stats
• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/tasks/{task_id}/chats - Chats

Feedback

• GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/feedback - Feedback

Create & manage

Create a Workflow, fetch one by id, and update its definition.

Create

POST /api/v2/w/{workspace_uuid}/workflows

Description:

Create a new custom workflow.

Creates a new workflow with specified configuration and settings. Workflows organize tasks and define business processes within your workspace. Use this endpoint to build custom workflows tailored to your specific needs, as opposed to using pre-configured templates.

Request Body: Contains workflow creation parameters:

• name: Workflow display name (required, string)
• description: Workflow purpose description (optional, string)
• prompt: Workflow-level instruction prompt (optional, string)
• ownerId: Owner member ID (optional, integer)
• copyFromAgentId: One-time Agent source for assistant settings (optional, integer)
• copyFromWorkflowRevisionId: One-time Workflow revision source for assistant settings (optional, integer)
• copySourceDigest: Source digest for optimistic concurrency (optional, string)
• assistantName: Versioned assistant display name (optional, string)
• assistantIdentity: Versioned assistant identity/instructions (optional, string)
• chatModelId / chatModelConfig: Versioned chat model settings (optional)
• realtimeModelId / realtimeModelConfig: Versioned voice model settings (optional)
• defaultPhoneNumberId: Default phone number ID (optional, integer, nullable)
• defaultInboxId: Default inbox ID (optional, integer, nullable)
• createMode: task to create an initial task, or taskless for a simple workflow
• defaultTaskName: Initial task name when createMode is task (optional, string)
• defaultTaskDescription: Initial task description when createMode is task (optional, string)
• defaultTaskPrompt: Initial task prompt when createMode is task (optional, string)
• abilities: Workflow-level abilities (optional, array)
• eventRules: Workflow-level event rules (optional, array)

Response: Returns a WorkflowDetailResponse composition (workflow root + draftRevision + activeRevision) for the newly created workflow. workflow.id is the stable root id callers redirect to.

Permissions: Requires workflows:write. Copying from an Agent also requires agents:read; copying from a Workflow revision requires read access to that source Workflow. Workflow permissions are automatically granted to the owner upon creation.

Error Responses:

• 400 Bad Request: Invalid request data or validation failure
• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: Member lacks workspace access
• 404 Not Found: Copy-source Workflow revision is missing or unreadable
• 409 Conflict: copySourceDigest no longer matches the selected source

Related Endpoints:

• GET /workflows - List all workflows
• POST /workflows/templates/{template_uuid}/create-workflow - Create from template
• PUT /workflows/{workflow_id} - Update a workflow
• POST /workflows/{workflow_id}/clone - Clone an existing workflow

Authentication: Public endpoint (no authentication required)

---

Get Workflow Id

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}

Description:

Retrieve a specific workflow by its identifier.

Fetches the workflow root plus its draft and active revisions as a composition. This endpoint accepts multiple identifier formats for flexibility: numeric ID or UUID. Use this when you need to view or edit a specific workflow's complete configuration.

Path Parameters:

• workflow_id: Workflow identifier (can be integer ID or UUID string)

Response: Returns a WorkflowDetailResponse object containing:

• workflow: WorkflowResponse root (id, uuid, name, description, ownerId, archived, defaults, activeRevisionId, draftRevisionId, draftModifiedAt, timestamps)
• draftRevision: WorkflowRevisionResponse — the editable draft graph (prompt, models, routing, tasks/abilities/eventRules, permissions)
• activeRevision: WorkflowRevisionSummaryResponse for the live revision (nullable)

Permissions: Requires valid workspace membership and "use" permission on the workflow. Members without appropriate permissions will receive a 403 error even if the workflow exists.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks "use" permission on this workflow
• 404 Not Found: Workflow with specified identifier does not exist

Related Endpoints:

• GET /workflows - List all workflows
• PUT /workflows/{workflow_id} - Update a workflow
• DELETE /workflows/{workflow_id} - Delete a workflow

Authentication: Requires workspace member

Parameters:

• workflow_id (String)

Response: See WorkflowDetailResponse

---

Update Workflow Id

PUT /api/v2/w/{workspace_uuid}/workflows/{workflow_id}

Description:

Update the workflow's draft revision.

Mutates the workflow's draft in place — never the active revision — so live traffic does not see in-progress edits. Marks the workflow as dirty (hasUnpublishedChanges = true) so the editor can show a "you have unsaved changes" indicator and the publish button.

Modifies workflow settings including name, description, associated assistant, and default task. Use this endpoint to refine workflows as your business processes evolve or to update configuration after initial creation.

Path Parameters:

• workflow_id: Unique identifier of the workflow to update (integer)

Request Body: Contains workflow update parameters (all optional):

• name: Updated workflow display name (string)
• description: Updated workflow description (string)
• prompt: Updated workflow-level instruction prompt (string, nullable)
• ownerId: Updated owner member ID (integer)
• copyFromAgentId: One-time Agent source for assistant settings (integer)
• copyFromWorkflowRevisionId: One-time Workflow revision source for assistant settings (integer)
• copySourceDigest: Source digest for optimistic concurrency (string)
• assistantName: Versioned assistant display name (string, nullable)
• assistantIdentity: Versioned assistant identity/instructions (string, nullable)
• chatModelId / chatModelConfig: Versioned chat model settings (nullable)
• realtimeModelId / realtimeModelConfig: Versioned voice model settings (nullable)
• startTaskId: Updated start task ID (integer, nullable)
• defaultPhoneNumberId: Updated default phone number ID (integer, nullable)
• defaultInboxId: Updated default inbox ID (integer, nullable)
• posX: Workflow diagram X position (number, nullable)
• posY: Workflow diagram Y position (number, nullable)
• abilities: Replacement workflow-level abilities (array)
• eventRules: Replacement workflow-level event rules (array)
• memberRoleAccess: Replacement role access policy (array; requires admin permission)

Response: Returns a WorkflowDetailResponse composition (workflow root + draftRevision + activeRevision). The edits land on draftRevision; workflow.draftModifiedAt reflects the dirty state.

Permissions: Requires valid workspace membership and "edit" permission on the workflow. Copying from an Agent also requires agents:read; copying from a Workflow revision requires read access to that source Workflow.

Error Responses:

• 400 Bad Request: Invalid request data or validation failure
• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks "edit" permission on this workflow
• 404 Not Found: Workflow with specified ID does not exist
• 409 Conflict: copySourceDigest no longer matches the selected source

Related Endpoints:

• GET /workflows/{workflow_id} - Get workflow details
• DELETE /workflows/{workflow_id} - Delete a workflow
• POST /workflows/{workflow_id}/clone - Clone a workflow

Authorization: Requires workflows:write scope

Parameters:

• workflow_id (String)
• data - See UpdateWorkflowRevisionRequest

Response: See WorkflowDetailResponse

---

List, revisions & publishing

List Workflows, work with revisions and diffs, and publish a revision.

List

GET /api/v2/w/{workspace_uuid}/workflows

Description:

List all workflows accessible to the current member.

Returns a paginated collection of workflows filtered by the member's permissions and archived status. Each item is a composition of the stable workflow root and its active revision summary, plus list enrichments (task counts and the member's permission mask) computed against the active graph.

Query Parameters:

• page: Page number (integer, default: 1)
• pageSize: Items per page (integer, default: 100, max: 500)
• archived: Filter by archived status (boolean, default: false)
• search: Filter by workflow name or description (string, optional)

Response: Returns a PaginatedResponse of WorkflowListItemResponse objects. Each item contains:

• workflow: WorkflowResponse root (id, uuid, name, description, ownerId, archived, defaults, activeRevisionId, draftRevisionId, draftModifiedAt, timestamps)
• activeRevision: WorkflowRevisionSummaryResponse for the live revision (nullable)
• taskCount / archivedTaskCount: task counts on the active graph (integer)
• permissions: the caller's permission mask (integer)

Permissions: Requires workflows:read. Listed workflows are visibility-filtered with WorkflowAction.READ; the per-row permissions field reports whether the caller can also use or edit each workflow.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: Member lacks workspace access

Related Endpoints:

• POST /workflows - Create a new workflow
• GET /workflows/{workflow_id} - Get a specific workflow
• GET /workflows/templates - List available workflow templates

Authentication: Public endpoint (no authentication required)

---

Templates

GET /api/v2/w/{workspace_uuid}/workflows/templates

Description:

List all available workflow templates with feature availability status.

Returns all registered workflow templates including pre-built configurations for common use cases like appointment booking, lead qualification, and customer support. Each template includes availability status based on the workspace's enabled features.

Query Parameters: None

Response: Returns an array of WorkflowTemplateResponse objects, each containing:

• uuid: Unique template identifier (UUID string)
• name: Template display name (string)
• shortDescription: Brief template description (string)
• longDescription: Detailed template explanation (string)
• category: Template category (string)
• requiredFeatures: Array of required feature flags (string array)
• isAvailable: Whether template can be used in this workspace (boolean)
• iconName: Icon identifier for UI display (string, nullable)

Permissions: Requires valid workspace membership. All members can view templates, but availability depends on workspace feature flags and subscription level.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: Member lacks workspace access

Related Endpoints:

• POST /workflows/templates/{template_uuid}/create-workflow - Create workflow from template
• GET /workflows - List all workflows
• POST /workflows - Create a custom workflow

Authorization: Requires workflows:read scope

Response: List of WorkflowTemplateResponse

---

Publish

POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/publish

Description:

Freeze the workflow's draft as a published revision and clone a fresh draft.

By default the just-published revision becomes the active revision — new chats, assignments, phone calls, and routine dispatches resolve to it immediately. Pass setActive=False to publish without flipping live traffic (advanced flow; the UI does not surface this).

Authorization: Requires workflows:write scope

Parameters:

• workflow_id (String)
• data - See PublishWorkflowRevisionRequest

Response: See WorkflowRevisionSummaryResponse

---

Revisions

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions

Authentication: Requires workspace member

Parameters:

• workflow_id (String)

Response: See WorkflowRevisionListResponse

---

Revisions

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions/{revision_id}

Authentication: Requires workspace member

Parameters:

• workflow_id (String)
• revision_id (String)

Response: See WorkflowRevisionResponse

---

Update Revisions

PATCH /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions/{revision_id}

Description:

Update a revision's curation metadata (label + publish notes).

Applies to BOTH the draft and any published revision — labels and notes are curation, not graph state, so this never bumps the workflow's dirty flag (draft_modified_at). Only fields explicitly present in the request body are applied; an explicit null clears the field.

Request Body:

• revisionName: Short human-readable label for the revision (string, nullable)
• publishNotes: Longer free-text summary for the revision (string, nullable)

Permissions: Requires workflows:write and workflow edit authority on the revision.

Authorization: Requires workflows:write scope

Parameters:

• workflow_id (String)
• revision_id (String)
• data - See UpdateWorkflowRevisionMetadataRequest

Response: See WorkflowRevisionSummaryResponse

---

Activate

POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions/{revision_id}/activate

Description:

Point the workflow's active pointer at the chosen revision.

Pointer flip only — no clone, no freeze, no new revision row. The target may be any of the workflow's published revisions. Activating the draft (legacy / "make my edits live") requires allowDraft=true in the request body and a confirmed warning in the UI.

Authorization: Requires workflows:write scope

Parameters:

• workflow_id (String)
• revision_id (String)
• data - See ActivateWorkflowRevisionRequest

Response: See WorkflowRevisionSummaryResponse

---

Diff

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions/{revision_id}/diff

Description:

Compare two revisions of the same workflow.

Produces a structured diff of revision-level fields, tasks (matched by stable lineageUuid so a rename reads as a changed name field, not remove+add), task edges, abilities, and event rules. against defaults to the workflow's draft. Requires READ authority on both revisions.

Authentication: Requires workspace member

Parameters:

• workflow_id (String)
• revision_id (String)
• against (String)

Response: See WorkflowRevisionDiffResponse

---

Edit

POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/revisions/{revision_id}/edit

Description:

Branch a published revision into the workflow's draft.

The workflow's draft becomes a fresh clone of the named published revision. Fails with 400 when the target is already the draft or is not published, and with 409 when the current draft has unpublished changes (unless discardDraftChanges is set) or is live for existing assignments.

Request Body:

• discardDraftChanges: Replace the current draft even if it has unpublished changes (boolean, default: false)

Permissions: Requires workflows:write and workflow edit authority on the revision.

Authorization: Requires workflows:write scope

Parameters:

• workflow_id (String)
• revision_id (String)
• data - See EditRevisionAsDraftRequest

Response: See WorkflowRevisionSummaryResponse

---

Archive & delete

Archive, unarchive, preview a deletion's impact, and delete a Workflow.

Delete Workflow Id

DELETE /api/v2/w/{workspace_uuid}/workflows/{workflow_id}

Description:

Delete a workflow permanently.

Removes a workflow from the workspace. By default, workflows with tasks cannot be deleted. Set cascade=true to delete the workflow and all its associated tasks. Deletion requires workspace admin scope and workflow delete/admin authority.

Path Parameters:

• workflow_id: Unique identifier of the workflow to delete (integer)

Query Parameters:

• cascade: If true, deletes workflow and all associated tasks (boolean, default: false)

Response: Returns a success status object:

• status: "success" string confirming deletion
• deletedTaskCount: Number of tasks deleted (only when cascade=true)

Permissions: Requires workflows:admin and workflow delete/admin authority.

Error Responses:

• 400 Bad Request: Workflow has existing tasks and cascade=false
• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks delete authority
• 404 Not Found: Workflow with specified ID does not exist

Related Endpoints:

• GET /workflows/{workflow_id}/deletion-preview - Preview what will be deleted
• GET /workflows/{workflow_id} - Get workflow details before deletion
• PUT /workflows/{workflow_id} - Update workflow instead of deleting
• POST /workflows/{workflow_id}/clone - Clone workflow before deletion

Authorization: Requires workflows:admin scope

Parameters:

• workflow_id (String)
• cascade (Boolean)

---

Archive

POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/archive

Description:

Archive a workflow.

Archives a workflow, hiding it from the default workflow list. Archived workflows cannot be used to create new assignments, but existing assignments remain accessible. Members with workflow edit authority can archive workflows.

Path Parameters:

• workflow_id: Unique identifier of the workflow to archive (integer)

Response: Returns a success status object:

• status: "success" string confirming archival

Permissions: Requires workflows:write and workflow edit authority.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks workflow edit authority
• 404 Not Found: Workflow with specified ID does not exist

Related Endpoints:

• POST /workflows/{workflow_id}/unarchive - Unarchive a workflow
• DELETE /workflows/{workflow_id} - Delete a workflow permanently

Authorization: Requires workflows:write scope

Parameters:

• workflow_id (String)
• _body (Object)

---

Deletion Preview

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/deletion-preview

Description:

Preview what will be deleted/archived when deleting a workflow.

Returns information about all tasks that will be deleted along with the workflow, and whether there are any assignments associated with this workflow.

Path Parameters:

• workflow_id: Unique identifier of the workflow (integer)

Response: Returns an object containing:

• taskCount: Number of tasks that will be deleted (integer)
• tasks: Array of task objects with id, name, and description
• hasAssignments: Whether this workflow has any assignments (boolean)

Permissions: Requires valid workspace membership and "edit" permission on the workflow.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks "edit" permission
• 404 Not Found: Workflow with specified ID does not exist

Authentication: Requires workspace member

Parameters:

• workflow_id (String)

---

Unarchive

POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/unarchive

Description:

Unarchive a workflow.

Restores an archived workflow, making it visible in the default workflow list and available for creating new assignments. Members with workflow edit authority can unarchive workflows.

Path Parameters:

• workflow_id: Unique identifier of the workflow to unarchive (integer)

Response: Returns a success status object:

• status: "success" string confirming unarchival

Permissions: Requires workflows:write and workflow edit authority.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks workflow edit authority
• 404 Not Found: Workflow with specified ID does not exist

Related Endpoints:

• POST /workflows/{workflow_id}/archive - Archive a workflow
• GET /workflows?archived=true - List archived workflows

Authorization: Requires workflows:write scope

Parameters:

• workflow_id (String)
• _body (Object)

---

Validation

Validate a Workflow's configuration, access, and routing before it goes live.

Route Dry Run

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/route-dry-run

Description:

Trace automatic routing for a Chat without performing the transition.

Path Parameters:

• workflow_id: Workflow whose dry-run we want to inspect.

Query Parameters:

• chat_id: Chat under an Assignment belonging to workflow_id.
• current_task_id (optional): Override for ctx.task.id.
• current_assignment_task_id (optional): Override for ctx.assignment_task.id.

Response: :class:WorkflowRouteDryRunResponse — IDs, status labels, candidate child Task IDs, the winning child Task ID when applicable, and errorType (class name only) when the evaluator raised. CEL text, evaluation inputs, Form values, Member values, Chat content, and raw exception strings are never returned.

Authentication: Requires workspace member

Parameters:

• workflow_id (Integer)
• chat_id (Integer)
• current_task_id (Integer)
• current_assignment_task_id (Integer)

Response: See WorkflowRouteDryRunResponse

---

Validate Access

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/validate-access

Description:

Validate that roles with workflow access also have access to dependency resources.

Checks all abilities on the workflow and its tasks, then verifies that each role with workflow USE access also has access to the forms, files, folders, and calendars referenced by those abilities. Each ability type defines its own validation logic via the AbilityRegistry.

Path Parameters:

• workflow_id: Unique identifier of the workflow (integer)

Response: Returns a WorkflowAccessValidationResponse containing:

• warnings: Array of WorkflowAccessWarning objects describing missing access

Permissions: Requires valid workspace membership and "edit" permission on the workflow.

Authentication: Requires workspace member

Parameters:

• workflow_id (String)

Response: See WorkflowAccessValidationResponse

---

Validate Config

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/validate-config

Description:

Validate that this workflow's abilities reference live workspace resources.

Calls collect_config_issues on every ability (enabled or not) and aggregates non-blocking diagnostics (for example, files or folders that were deleted after the ability was saved). Runtime resolution stays resilient regardless — this route exists to surface drift to operators before they re-enable something or save an unrelated change that would drag broken config along with it.

Path Parameters:

• workflow_id: Unique identifier of the workflow (integer)

Response: Returns a WorkflowConfigValidationResponse containing:

• issues: Array of AbilityConfigIssue entries describing config drift

Permissions: Requires valid workspace membership and "edit" permission on the workflow.

Authentication: Requires workspace member

Parameters:

• workflow_id (String)

Response: See WorkflowConfigValidationResponse

---

Templates

Create a Workflow from a template.

Create Workflow

POST /api/v2/w/{workspace_uuid}/workflows/templates/{template_uuid}/create-workflow

Description:

Create a new workflow from a pre-configured template.

Instantiates a workflow based on a registered template, including all associated tasks, assistants, and configurations. Templates provide quick-start solutions for common workflows like appointment scheduling, lead qualification, or customer support. The endpoint validates feature requirements and creates all necessary resources in a single operation.

Path Parameters:

• template_uuid: Unique identifier of the workflow template (UUID string)

Request Body: Contains workflow creation parameters:

• name: Display name for the new workflow (required, string)

Response: Returns a WorkflowDetailResponse composition (workflow root + draftRevision + activeRevision) for the newly created workflow. workflow.id is the stable root id callers redirect to; the draft graph carries the template's tasks and default settings.

Permissions: Requires valid workspace membership. Template availability depends on workspace feature flags and subscription level. Some templates may require specific enabled features to be instantiated.

Error Responses:

• 400 Bad Request: Required feature not enabled for template
• 401 Unauthorized: Authentication required or invalid session
• 404 Not Found: Template UUID does not exist
• 500 Internal Server Error: Failed to create workflow or missing dependencies
• 501 Not Implemented: Template creation not yet implemented for this template type

Related Endpoints:

• GET /workflows/templates - List available workflow templates
• GET /workflows - List all workflows
• GET /workflows/{workflow_id} - Get created workflow details

Authorization: Requires workflows:write scope

Parameters:

• template_uuid (String)
• data - See CreateWorkflowFromTemplateRequest

Response: See WorkflowDetailResponse

---

Contributors

Manage the Members who contribute to a Workflow.

Contributors

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/contributors

Description:

List contributors on the workflow's draft revision.

Matches create/update/delete: the editor binds to the draft, so list must surface draft contributors (not the active/published snapshot).

Authentication: Requires workspace member

Parameters:

• workflow_id (String)

Response: List of WorkflowContributorResponse

---

Contributors

POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/contributors

Description:

Add a contributor to the workflow's draft revision.

The contributor row attaches to the draft. It survives Publish via the standard revision-clone (every published revision carries the contributor list it had at publish time).

Authorization: Requires workflows:write scope

Parameters:

• workflow_id (String)
• request - See CreateWorkflowContributorRequest

Response: See WorkflowContributorResponse

---

Delete Contributors

DELETE /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/contributors/{contributor_id}

Description:

Remove a contributor from the workflow's draft revision.

Authorization: Requires workflows:admin scope

Parameters:

• workflow_id (String)
• contributor_id (Integer)

---

Update Contributors

PATCH /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/contributors/{contributor_id}

Description:

Update a contributor on the workflow's draft revision.

Authorization: Requires workflows:write scope

Parameters:

• workflow_id (String)
• contributor_id (Integer)
• request - See UpdateWorkflowContributorRequest

Response: See WorkflowContributorResponse

---

Activity, diagrams & thumbnails

Per-Workflow activity feeds, rendered diagrams, and thumbnails.

Batch

GET /api/v2/w/{workspace_uuid}/workflows/activity/batch

Description:

Get activity statistics for multiple workflows in a single request.

Query Parameters:

• workflow_ids: Comma-separated list of workflow IDs (e.g., "1,2,3")
• days: Number of days of sparkline data to return (1-90, default 7)

Response: Returns a dict mapping workflow ID (as string key) to activity object:

• chatCount: Total number of chats (integer)
• sparklineData: Array of integers representing daily chat counts (oldest to newest)

Authorization: Requires workflows:read scope

Parameters:

• workflow_ids (String)
• days (Integer) — default: 7, min: 1, max: 90

---

Activity

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/activity

Description:

Get activity statistics for a workflow.

Returns sparkline data showing chat activity over the specified number of days.

Path Parameters:

• workflow_id: Unique identifier of the workflow (integer)

Query Parameters:

• days: Number of days of sparkline data to return (1-90, default 7)

Response: Returns an object containing:

• chatCount: Total number of chats (integer)
• sparklineData: Array of integers representing daily chat counts (oldest to newest)

Permissions: Requires workflows:read and workflow read visibility.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks workflow read visibility
• 404 Not Found: Workflow with specified ID does not exist
• 422 Unprocessable Entity: Invalid days parameter (must be 1-90)

Related Endpoints:

• GET /workflows/{workflow_id} - Get workflow details
• GET /workflows - List all workflows

Authorization: Requires workflows:read scope

Parameters:

• workflow_id (String)
• days (Integer) — default: 7, min: 1, max: 90

---

Diagram

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/diagram

Description:

Get a Mermaid diagram representation of a workflow.

Returns a Mermaid flowchart definition that can be rendered client-side. The diagram shows the workflow structure with tasks as nodes and their connections as edges.

By default only active tasks are rendered, matching the active task list. Archived tasks (and edges touching them) are excluded so they don't appear as live-but-orphaned nodes. Pass include_archived=true to render archived tasks as well — they get a distinct dashed-grey style and an "(archived)" label so they are never mistaken for active tasks.

Path Parameters:

• workflow_id: Unique identifier of the workflow (integer)

Query Parameters:

• include_archived: Render archived tasks (distinctly styled) in addition to active ones (optional, default: false)

Response: Returns an object containing:

• mermaid: Mermaid diagram definition (string)
• taskCount: Total number of tasks in the workflow, active + archived (integer)
• archivedTaskCount: How many of those tasks are archived (integer)
• includeArchived: Whether archived tasks were rendered (boolean)

Permissions: Requires valid workspace membership and "use" permission on the workflow.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks "use" permission
• 404 Not Found: Workflow with specified ID does not exist

Authentication: Requires workspace member

Parameters:

• workflow_id (String)
• include_archived (Boolean)

---

Thumbnail

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/thumbnail

Description:

Get an SVG thumbnail representation of a workflow.

Returns a compact SVG diagram showing the workflow structure with tasks as nodes and their connections as edges, styled to match the React Flow workflow diagram.

Path Parameters:

• workflow_id: Unique identifier of the workflow (integer)

Response: Returns SVG content with Content-Type: image/svg+xml

Permissions: Requires valid workspace membership and "use" permission on the workflow.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks "use" permission
• 404 Not Found: Workflow with specified ID does not exist

Authentication: Requires workspace member

Parameters:

• workflow_id (String)

---

Statistics & cloning

Task-assignment statistics, per-task chats, and Workflow cloning.

Clone

POST /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/clone

Description:

Clone a workflow with all tasks and associations.

Creates a complete copy of an existing workflow including all associated tasks, task configurations, and relationships. Use this endpoint to duplicate successful workflows for reuse, create variations, or establish templates from existing work. The cloned workflow becomes owned by the requesting member.

Path Parameters:

• workflow_id: Unique identifier of the workflow to clone (integer)

Request Body: Contains cloning parameters:

• name: Display name for the cloned workflow (required, string)

Response: Returns a WorkflowDetailResponse composition (workflow root + draftRevision + activeRevision) for the newly cloned workflow. workflow.id is the new stable root id callers redirect to; the draft graph carries the cloned tasks/abilities and the caller's permissions.

Permissions: Requires valid workspace membership with "use" permission on the source workflow and permission to create workflows in the workspace. The cloned workflow is owned by the member who performs the cloning operation.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks "use" permission on source workflow or cannot create workflows
• 404 Not Found: Workflow with specified ID does not exist
• 409 Conflict: A workflow with the specified name already exists
• 500 Internal Server Error: Failed to reload cloned workflow data

Related Endpoints:

• GET /workflows/{workflow_id} - View workflow before cloning
• POST /workflows - Create new workflow from scratch
• POST /workflows/templates/{template_uuid}/create-workflow - Create from template

Authorization: Requires workflows:write scope

Parameters:

• workflow_id (String)
• data - See CloneWorkflowRequest

Response: See WorkflowDetailResponse

---

Task Assignment Stats

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/task-assignment-stats

Description:

Get current assignment count for each task in a workflow.

Returns aggregated data showing how many assignments are currently on each task. Useful for workflow visualization and identifying bottlenecks.

Path Parameters:

• workflow_id: Unique identifier of the workflow (integer)

Query Parameters:

• from_date: Filter assignments created on or after this date (ISO 8601 format, e.g., 2024-01-15)
• to_date: Filter assignments created on or before this date (ISO 8601 format, e.g., 2024-01-20)

Response: Returns a dictionary mapping task IDs to assignment counts:

{
123: {"count": 5},
456: {"count": 3}
}

Permissions: Requires valid workspace membership and "use" permission on the workflow.

Error Responses:

• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks "use" permission on this workflow
• 404 Not Found: Workflow with specified ID does not exist

Authentication: Requires workspace member

Parameters:

• workflow_id (String)
• from_date (String)
• to_date (String)
• workflow_revision_id (Integer)

---

Chats

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/tasks/{task_id}/chats

Description:

Get list of chats on a specific task in a workflow.

Returns a paginated list of chats that are currently assigned to a specific task. Useful for viewing all chats at a particular workflow task.

Path Parameters:

• workflow_id: Unique identifier of the workflow (integer)
• task_id: Unique identifier of the task (integer)

Query Parameters:

• from_date: Filter assignments created on or after this date (ISO 8601 format)
• to_date: Filter assignments created on or before this date (ISO 8601 format)
• limit: Maximum number of results to return (integer, default: 100, max: 500)
• offset: Number of results to skip for pagination (integer, default: 0)

Response: Returns a TaskChatsListResponse containing:

• items: Array of task chat objects with:
• chatId: Chat identifier
• chatUuid: Chat UUID
• title: Chat title
• summary: Chat summary
• assignmentId: Current assignment ID
• memberName: Name of assigned member
• memberId: ID of assigned member
• currentTaskName: Name of current task
• workflowName: Name of workflow
• lastMessageAt: Timestamp of last message
• messageCount: Number of messages in the chat
• total: Total count of matching chats
• limit: Limit used for pagination
• offset: Offset used for pagination

Permissions: Requires valid workspace membership and "use" permission on the workflow.

Error Responses:

• 400 Bad Request: Invalid date format or parameters
• 401 Unauthorized: Authentication required or invalid session
• 403 Forbidden: User lacks "use" permission on this workflow
• 404 Not Found: Workflow or task not found

Authentication: Requires workspace member

Parameters:

• workflow_id (String)
• task_id (Integer)
• from_date (String)
• to_date (String)
• limit (Integer)
• offset (Integer)

Response: See TaskChatsListResponse

---

Feedback

Feedback recorded against a Workflow's conversations.

Feedback

GET /api/v2/w/{workspace_uuid}/workflows/{workflow_id}/feedback

Description:

List chat feedback for a workflow (thumbs + future explicit/extracted rows).

Joins chat_feedback → chats → assignments so only chats that belong to this workflow are returned. Each item includes:

• source — capture path (rating / explicit_user / extracted / supervisor)
• authorKind — who left it (end_user / staff / supervisor / system / …)

Permissions: workflows:read + workflow read visibility.

PHI: body may contain free-text referencing patient context.

Authorization: Requires workflows:read scope

Parameters:

• workflow_id (Integer)
• page (Integer) — min: 1
• page_size (Integer) — min: 1, max: 100
• source (String)
• rating (String)
• author_kind (String)
• include_test (Boolean)

Response: See WorkflowFeedbackListResponse

---