Assignments

Tags: assignments, tasks, workflow

Task and workflow assignments

Resources

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

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
}

AssignmentResponse

Field	Type	Required	Description
concludedAt	DateTime
createdAt	DateTime	✓
currentTask	AssignmentTaskResponse
dataRecords	Array		Default: []
files	Array	✓
id	Integer	✓
isTest	Boolean	✓
memberId	Integer	✓
outcome	String
outcomeReason	String
pages	Array		Default: []
rootTask	AssignmentTaskResponse
status	String		Default: active
taskId	Integer
taskName	String
updatedAt	DateTime	✓
uuid	String	✓
workflowId	WorkflowId	✓
workflowName	String
workflowRevisionId	WorkflowRevisionId
workflowRevisionName	String
workflowRevisionNumber	Integer
workflowRevisionUuid	String
workflowUuid	String

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "taskId": 0  // Integer, optional,
  "taskName": "string"  // String, optional,
  "memberId": 0  // Integer,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "status": "string"  // String, optional, default: active,
  "outcome": "string"  // String, optional,
  "outcomeReason": "string"  // String, optional,
  "concludedAt": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "rootTask": null  // AssignmentTaskResponse, optional,
  "currentTask": null  // AssignmentTaskResponse, optional,
  "isTest": false  // Boolean,
  "dataRecords": []  // Array<DataRecordResponse>, optional, default: [],
  "files": []  // Array<FileResponse>,
  "pages": []  // Array<PageResponse>, optional, default: [],
  "workflowId": null  // WorkflowId,
  "workflowName": "string"  // String, optional,
  "workflowUuid": "string"  // String, optional,
  "workflowRevisionId": null  // WorkflowRevisionId, optional,
  "workflowRevisionUuid": "string"  // String, optional,
  "workflowRevisionNumber": 0  // Integer, optional,
  "workflowRevisionName": "string"  // String, optional
}

AssignmentTaskResponse

Field	Type	Required	Description
autoNext	Boolean	✓
children	Array		Default: []
id	Integer	✓
required	Boolean	✓
taskId	Integer	✓
taskName	String	✓
taskUuid	String	✓
uuid	String	✓
visitedAt	DateTime	✓
workflowId	WorkflowId	✓

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "required": false  // Boolean,
  "autoNext": false  // Boolean,
  "taskId": 0  // Integer,
  "workflowId": null  // WorkflowId,
  "taskName": "string"  // String,
  "taskUuid": "string"  // String,
  "visitedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "children": []  // Array<AssignmentTaskResponse>, optional, default: []
}

DataRecordResponse

Field	Type	Required	Description
accessMode	Integer
createdAt	DateTime	✓
dataTypeId	Integer	✓
externalId	String
fieldValues	Dict[str, Any]	✓
id	Integer	✓
memberId	Integer	✓
memberName	String
retirement	DataRecordRetirementResponse
updatedAt	DateTime	✓

Example:

{
  "id": 0  // Integer,
  "dataTypeId": 0  // Integer,
  "memberId": 0  // Integer,
  "memberName": "string"  // String, optional,
  "fieldValues": {}  // Dict[str, Any],
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "externalId": "string"  // String, optional,
  "accessMode": 0  // Integer, optional,
  "retirement": null  // DataRecordRetirementResponse, optional
}

FileResponse

Field	Type	Required	Description
access	String		Default: private
accessMode	Integer
cdnUrl	String	✓
choicePrompt	String
createdAt	DateTime	✓
currentVersionNumber	Integer		Default: 0
data	String	✓
description	String	✓
externalId	String	✓
fileSize	Integer	✓
filename	String	✓
folder	FileFolderResponse	✓
folderId	Integer	✓
id	Integer	✓
isS3Stored	Boolean		Default: False
labels	Array
lastEditedByMemberId	Integer
mimeType	String	✓
ownerId	Integer
permissions	Integer		Default: 0
shareCount	Integer		Default: 0
siteId	Integer	✓
title	String	✓
updatedAt	DateTime	✓
uuid	String	✓

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "title": "string"  // String,
  "description": "string"  // String,
  "accessMode": 0  // Integer, optional,
  "choicePrompt": "string"  // String, optional,
  "filename": "string"  // String,
  "mimeType": "string"  // String,
  "folderId": 0  // Integer,
  "siteId": 0  // Integer,
  "externalId": "string"  // String,
  "ownerId": 0  // Integer, optional,
  "access": "string"  // String, optional, default: private,
  "folder": null  // FileFolderResponse,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "data": "string"  // String,
  "cdnUrl": "string"  // String,
  "fileSize": 0  // Integer,
  "isS3Stored": false  // Boolean, optional, default: False,
  "permissions": 0  // Integer, optional, default: 0,
  "labels": []  // Array<FileLabelResponse>, optional,
  "shareCount": 0  // Integer, optional, default: 0,
  "currentVersionNumber": 0  // Integer, optional, default: 0,
  "lastEditedByMemberId": 0  // Integer, optional
}

OpenAIFunctionToolCall

Field	Type	Required	Description
function	Dict[str, Any]		Default: {}
id	String		Default: ``
type	String		Default: function

Example:

{
  "id": "string"  // String, optional, default: ,
  "type": "string"  // String, optional, default: function,
  "function": {}  // Dict[str, Any], optional, default: {}
}

OpenAIMessageResponse

Field	Type	Required	Description
audioFileUuid	String
audioMetadata	Dict[str, Any]
content	Union[str, List[Dict[str, Any]], null]
created_at	DateTime
email_id	Integer
id	String
inbox_id	Integer
memberId	Integer
originalContent	Union[str, List[Dict[str, Any]], null]
role	String
smsDeliveryErrorCode	String
smsDeliveryFailureReason	String
smsDeliveryStatus	String
smsDeliveryUpdatedAt	DateTime
suggestions	Array
taskId	Integer
tokenUsage	MessageTokenUsageResponse
tool_call_id	String
tool_calls	Array		Default: []
truncatedAtMs	Integer
truncationReason	String
userRating	Number
userRatingComment	String

Example:

{
  "id": "string"  // String, optional,
  "role": "string"  // String, optional,
  "content": {}  // Union[str, List[Dict[str, Any]], null], optional,
  "originalContent": {}  // Union[str, List[Dict[str, Any]], null], optional,
  "truncationReason": "string"  // String, optional,
  "truncatedAtMs": 0  // Integer, optional,
  "tool_calls": []  // Array<OpenAIFunctionToolCall>, optional, default: [],
  "tool_call_id": "string"  // String, optional,
  "suggestions": "string"  // Array<String>, optional,
  "created_at": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "email_id": 0  // Integer, optional,
  "inbox_id": 0  // Integer, optional,
  "tokenUsage": null  // MessageTokenUsageResponse, optional,
  "memberId": 0  // Integer, optional,
  "taskId": 0  // Integer, optional,
  "audioFileUuid": "string"  // String, optional,
  "audioMetadata": {}  // Dict[str, Any], optional,
  "smsDeliveryStatus": "string"  // String, optional,
  "smsDeliveryErrorCode": "string"  // String, optional,
  "smsDeliveryUpdatedAt": "2024-01-01T00:00:00Z"  // DateTime, optional,
  "smsDeliveryFailureReason": "string"  // String, optional,
  "userRating": 0.0  // Number, optional,
  "userRatingComment": "string"  // String, optional
}

OperatorChildTaskDetail

Field	Type	Required	Description
assignmentTaskId	Integer	✓
autoNext	Boolean		Default: False
celCondition	String
choicePrompt	String
order	Integer		Default: 0
required	Boolean		Default: False
shortPrompt	String
taskId	Integer	✓
taskName	String	✓
taskType	String	✓
taskUuid	String	✓
visitedAt	DateTime

Example:

{
  "assignmentTaskId": 0  // Integer,
  "taskId": 0  // Integer,
  "taskName": "string"  // String,
  "taskUuid": "string"  // String,
  "taskType": "string"  // String,
  "shortPrompt": "string"  // String, optional,
  "choicePrompt": "string"  // String, optional,
  "celCondition": "string"  // String, optional,
  "autoNext": false  // Boolean, optional, default: False,
  "required": false  // Boolean, optional, default: False,
  "order": 0  // Integer, optional, default: 0,
  "visitedAt": "2024-01-01T00:00:00Z"  // DateTime, optional
}

OperatorTaskDetailResponse

Field	Type	Required	Description
abilities	Array		Default: []
assignmentId	Integer	✓
assignmentTaskId	Integer	✓
celGuard	String
childTasks	Array		Default: []
configuration	Object
description	String
inheritedAbilities	Array		Default: []
parentAssignmentTaskId	Integer
parentShortPrompt	String
parentTaskName	String
prompt	String
renderedPrompt	String
shortPrompt	String
taskId	Integer	✓
taskName	String	✓
taskType	String	✓

Example:

{
  "assignmentId": 0  // Integer,
  "assignmentTaskId": 0  // Integer,
  "taskId": 0  // Integer,
  "taskName": "string"  // String,
  "taskType": "string"  // String,
  "prompt": "string"  // String, optional,
  "renderedPrompt": "string"  // String, optional,
  "shortPrompt": "string"  // String, optional,
  "description": "string"  // String, optional,
  "configuration": {}  // Object, optional,
  "celGuard": "string"  // String, optional,
  "abilities": []  // Array<AbilityResponse>, optional, default: [],
  "inheritedAbilities": []  // Array<AbilityResponse>, optional, default: [],
  "childTasks": []  // Array<OperatorChildTaskDetail>, optional, default: [],
  "parentAssignmentTaskId": 0  // Integer, optional,
  "parentTaskName": "string"  // String, optional,
  "parentShortPrompt": "string"  // String, optional
}

PageResponse

Field	Type	Required	Description
contentAMP	String	✓
contentBlocks	TipTapDocument	✓
contentHtml	String	✓
contentMarkdown	String	✓
crawledAt	DateTime	✓
createdAt	DateTime	✓
id	Integer	✓
isHomePage	Boolean		Default: False
siteId	Integer	✓
slug	String	✓
sourceHtml	String	✓
sourceMarkdown	String	✓
sourceMetadata	dict[str, Any]	✓
sourceUrl	String	✓
status	String		Default: draft
title	String	✓
updatedAt	DateTime	✓
url	String

Example:

{
  "id": 0  // Integer,
  "slug": "string"  // String,
  "title": "string"  // String,
  "status": "string"  // String, optional, default: draft,
  "url": "string"  // String, optional,
  "contentBlocks": null  // TipTapDocument,
  "contentMarkdown": "string"  // String,
  "contentHtml": "string"  // String,
  "contentAMP": "string"  // String,
  "sourceMetadata": {}  // dict[str, Any],
  "sourceHtml": "string"  // String,
  "sourceMarkdown": "string"  // String,
  "sourceUrl": "string"  // String,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "crawledAt": "2024-01-01T00:00:00Z"  // DateTime,
  "siteId": 0  // Integer,
  "isHomePage": false  // Boolean, optional, default: False
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/assignments - List
• POST /api/v2/w/{workspace_uuid}/assignments - Create
• GET /api/v2/w/{workspace_uuid}/assignments/{assignment_id} - Get Assignment Id
• PUT /api/v2/w/{workspace_uuid}/assignments/{assignment_id} - Update Assignment Id
• POST /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/cancel - Cancel
• GET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/cel-context - Cel Context
• GET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/current-task-detail - Current Task Detail
• GET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/messages - Messages
• GET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/tasks/{assignment_task_id} - Tasks
• PUT /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/tasks/{assignment_task_id}/select - Update Select

List

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

Description:

List assignments with pagination.

Self-access: Users can always list their own assignments (mine=True forced). Admin access: ASSIGNMENTS_READ scope required to list all assignments or to filter by a memberId other than the caller's own.

Authentication: Requires workspace member

Parameters:

• page (Integer) — min: 1
• pageSize (Integer) — min: 1, max: 100
• sortBy (AssignmentSortField)
• sortOrder (SortOrder)
• mine (Boolean)
• taskId (Integer)
• memberId (Integer)
• status (String)

Response: See PaginatedResponse[AssignmentResponse]

---

Create

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

Description:

Create a new assignment.

Requires workflow USE permission (checked by CreateAssignmentRequest).

Authentication: Requires workspace member

Parameters:

• request_body (CreateAssignmentRequest)

Response: See AssignmentResponse

---

Get Assignment Id

GET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}

Description:

Get a specific assignment by ID.

Self-access: Users can view their own assignments. Admin access: ASSIGNMENTS_READ scope required to view other members' assignments.

Authentication: Requires workspace member

Parameters:

• assignment_id (Integer)

Response: See AssignmentResponse

---

Update Assignment Id

PUT /api/v2/w/{workspace_uuid}/assignments/{assignment_id}

Description:

Update an existing assignment.

Self-access: Users can update their own assignments. Admin access: ASSIGNMENTS_WRITE scope required to update other members' assignments.

Authentication: Requires workspace member

Parameters:

• assignment_id (Integer)
• request_body (UpdateAssignmentRequest)

Response: See AssignmentResponse

---

Cancel

POST /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/cancel

Description:

Cancel an active assignment.

Admin access: ASSIGNMENTS_WRITE scope required to cancel other members' assignments. Self-access: Users can cancel their own assignments.

Authentication: Requires workspace member

Parameters:

• assignment_id (Integer)
• request_body (CancelAssignmentRequest)

Response: See AssignmentResponse

---

Cel Context

GET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/cel-context

Description:

Get CEL evaluation context for the current assignment.

Returns a read-only snapshot of the variables used when evaluating task conditions for this Assignment, so the UI can show routing hints. Task switches are still enforced server-side.

Self-access: Users can read context for their own assignments. Admin access: ASSIGNMENTS_READ scope required for other members' assignments.

The response omits member.form_data and member.data (empty maps) so this preview does not expose PHI; the runtime evaluator still has access when conditions reference those fields.

Authentication: Requires workspace member

Parameters:

• assignment_id (Integer)

---

Current Task Detail

GET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/current-task-detail

Description:

Get rich detail of the current task for operator assignment view.

Authentication: Requires workspace member

Parameters:

• assignment_id (Integer)

Response: See OperatorTaskDetailResponse

---

Messages

GET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/messages

Description:

Get all messages for a specific assignment.

Self-access: Users can view messages for their own assignments. Admin access: ASSIGNMENTS_READ scope required to view other members' messages.

Authentication: Requires workspace member

Parameters:

• assignment_id (Integer)

Response: List of OpenAIMessageResponse

---

Tasks

GET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/tasks/{assignment_task_id}

Description:

Get a specific assignment task by ID.

Self-access: Users can view tasks for their own assignments. Admin access: ASSIGNMENTS_READ scope required to view other members' tasks.

Authentication: Requires workspace member

Parameters:

• assignment_id (Integer)
• assignment_task_id (Integer)

Response: See AssignmentTaskResponse

---

Update Select

PUT /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/tasks/{assignment_task_id}/select

Description:

Switch the current task for an assignment.

Self-access: Users can switch tasks for their own assignments. Admin access: ASSIGNMENTS_WRITE scope required to switch other members' tasks.

Authentication: Requires workspace member

Parameters:

• assignment_id (Integer)
• assignment_task_id (Integer)

Response: See AssignmentTaskResponse

---