Assignments
Tags: assignments, tasks, workflow
An Assignment represents a Member's participation in a Workflow during a Chat. It records the current Task and overall status as the Member progresses through the Workflow. Task history records the steps reached; completing or canceling the Assignment ends that participation. These endpoints let authorized clients list, inspect, create, update and cancel 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,
"uuid": "string",
"abilityType": "string",
"config": {},
"enabled": false
}
AssignmentResponse
| Field | Type | Required | Description |
|---|---|---|---|
concludedAt | DateTime | ||
createdAt | DateTime | ✓ | |
currentTask | AssignmentTaskResponse | null | ||
dataRecords | Array<DataRecordResponse> | Default: [] | |
files | Array<FileResponse> | ✓ | |
id | Integer | ✓ | |
isTest | Boolean | ✓ | |
memberId | Integer | ✓ | |
outcome | String | ||
outcomeReason | String | ||
pages | Array<PageResponse> | Default: [] | |
rootTask | AssignmentTaskResponse | null | ||
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,
"uuid": "string",
"memberId": 0,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"status": "active",
"isTest": false,
"dataRecords": [],
"files": [],
"pages": [],
"workflowId": null
}
AssignmentTaskResponse
| Field | Type | Required | Description |
|---|---|---|---|
autoNext | Boolean | ✓ | |
children | Array<AssignmentTaskResponse> | Default: [] | |
id | Integer | ✓ | |
required | Boolean | ✓ | |
taskId | Integer | ✓ | |
taskName | String | ✓ | |
taskUuid | String | ✓ | |
uuid | String | ✓ | |
visitedAt | DateTime | ✓ | |
workflowId | WorkflowId | ✓ |
Example:
{
"id": 0,
"uuid": "string",
"required": false,
"autoNext": false,
"taskId": 0,
"workflowId": null,
"taskName": "string",
"taskUuid": "string",
"visitedAt": "2024-01-01T00:00:00Z",
"children": []
}
CancelAssignmentRequest
| Field | Type | Required | Description |
|---|---|---|---|
reason | String |
Example:
{}
ChatApprovalDecision
| Field | Type | Required | Description |
|---|---|---|---|
answer | Literal['approve', 'approve_always', 'reject', 'edit', 'other'] | ✓ | |
callId | String | ✓ | |
tool | String | ✓ |
Example:
{
"callId": "string",
"tool": "string",
"answer": "approve"
}
CreateAssignmentRequest
| Field | Type | Required | Description |
|---|---|---|---|
dataRecords | Array<DataRecordAssociationRequest> | Default: [] | |
isTest | Boolean | Default: False | |
memberId | Integer | ||
taskId | Integer | ||
workflowId | Integer | ||
workflowRevisionId | Integer |
Example:
{
"isTest": false,
"dataRecords": []
}
DataRecordAssociationRequest
| Field | Type | Required | Description |
|---|---|---|---|
accessMode | Integer | Default: 0 | |
id | Integer | ✓ |
Example:
{
"id": 0,
"accessMode": 0
}
DataRecordResponse
| Field | Type | Required | Description |
|---|---|---|---|
accessMode | Integer | ||
createdAt | DateTime | ✓ | |
createdByMemberId | Integer | ||
dataTypeId | Integer | ✓ | |
externalId | String | ||
fieldValues | Dict[str, Any] | ✓ | |
id | Integer | ✓ | |
memberId | Integer | ✓ | |
memberName | String | ||
retirement | DataRecordRetirementResponse | null | ||
updatedAt | DateTime | ✓ | |
uuid | UUID | ✓ |
Example:
{
"id": 0,
"uuid": "00000000-0000-0000-0000-000000000000",
"dataTypeId": 0,
"memberId": 0,
"fieldValues": {},
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
DataRecordRetirementResponse
| Field | Type | Required | Description |
|---|---|---|---|
reason | Literal['monday_item_archived', 'monday_item_deleted'] | ✓ | |
source | Literal['monday'] | Default: monday | |
status | Literal['retired'] | Default: retired |
Example:
{
"status": "retired",
"reason": "monday_item_archived",
"source": "monday"
}
EscalationSignalsResponse
| Field | Type | Required | Description |
|---|---|---|---|
engine | String | ||
latencyMs | Number | ||
raised | Array | Default: [] | |
scores | dict[str, float] | Default: {} | |
signalSet | String | ✓ | |
status | String | ✓ |
Example:
{
"status": "string",
"signalSet": "string",
"scores": {},
"raised": []
}
FileFolderResponse
| Field | Type | Required | Description |
|---|---|---|---|
access | String | Default: private | |
ancestors | Array<FolderPathSegment> | Default: [] | |
childCount | Integer | Default: 0 | |
createdAt | DateTime | ✓ | |
description | String | ||
fileCount | Integer | Default: 0 | |
id | Integer | ✓ | |
index | Boolean | Default: False | |
indexingCompletedAt | DateTime | ||
indexingStartedAt | DateTime | ||
name | String | ✓ | |
ownerId | Integer | ||
ownerName | String | ||
parentId | Integer | ||
path | String | ||
shareable | Boolean | Default: False | |
updatedAt | DateTime | ✓ | |
uuid | String | ✓ |
Example:
{
"id": 0,
"name": "string",
"uuid": "string",
"childCount": 0,
"fileCount": 0,
"access": "private",
"shareable": false,
"index": false,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"ancestors": []
}
FileLabelResponse
| Field | Type | Required | Description |
|---|---|---|---|
color | String | ✓ | |
description | String | ✓ | |
id | Integer | ✓ | |
name | String | ✓ | |
uuid | String | ✓ |
Example:
{
"id": 0,
"uuid": "string",
"name": "string",
"color": "string",
"description": "string"
}
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 | null | ✓ | |
folderAncestorIds | Array | Default: [] | |
folderId | Integer | ✓ | |
id | Integer | ✓ | |
isS3Stored | Boolean | Default: False | |
labels | Array<FileLabelResponse> | null | ||
lastEditedByMemberId | Integer | ||
mimeType | String | ✓ | |
ownerId | Integer | ||
ownerName | String | ||
permissions | Integer | Default: 0 | |
shareCount | Integer | Default: 0 | |
siteId | Integer | ✓ | |
subjectMemberId | Integer | ||
title | String | ✓ | |
updatedAt | DateTime | ✓ | |
uuid | String | ✓ |
Example:
{
"id": 0,
"uuid": "string",
"title": "string",
"description": "string",
"filename": "string",
"mimeType": "string",
"folderId": 0,
"folderAncestorIds": [],
"siteId": 0,
"externalId": "string",
"access": "private",
"folder": null,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"data": "string",
"cdnUrl": "string",
"fileSize": 0,
"isS3Stored": false,
"permissions": 0,
"shareCount": 0,
"currentVersionNumber": 0
}
FolderPathSegment
| Field | Type | Required | Description |
|---|---|---|---|
id | Integer | ✓ | |
name | String | ✓ |
Example:
{
"id": 0,
"name": "string"
}
MessageFeatureResponse
| Field | Type | Required | Description |
|---|---|---|---|
decision | Literal['greeting', 'answer'] | ✓ | |
engine | String | ✓ | |
latencyMs | Number | ✓ | |
questionSet | String | ✓ | |
status | Literal['decided', 'unavailable'] | ✓ | |
value | Literal[human, voicemail, call_screening, unknown, answerable, not_found] | ✓ |
Example:
{
"decision": "greeting",
"value": null,
"status": "decided",
"engine": "string",
"questionSet": "string",
"latencyMs": 0.0
}
MessageFeatures
| Field | Type | Required | Description |
|---|---|---|---|
greeting | MessageFeatureResponse | null | ||
retrievedAnswer | MessageFeatureResponse | null |
Example:
{}
MessageTokenUsageResponse
| Field | Type | Required | Description |
|---|---|---|---|
cachedTokens | Integer | Default: 0 | |
completionTokens | Integer | ✓ | |
credits | Number | Default: 0.0 | |
model | String | ✓ | |
promptTokens | Integer | ✓ | |
totalTokens | Integer | ✓ |
Example:
{
"model": "string",
"promptTokens": 0,
"completionTokens": 0,
"totalTokens": 0,
"cachedTokens": 0,
"credits": 0.0
}
OpenAIFunctionToolCall
| Field | Type | Required | Description |
|---|---|---|---|
function | Dict[str, Any] | Default: {} | |
id | String | Default: `` | |
type | String | Default: function |
Example:
{
"id": "",
"type": "function",
"function": {}
}
OpenAIMessageResponse
| Field | Type | Required | Description |
|---|---|---|---|
approvalDecision | ChatApprovalDecision | null | ||
audience | String | ||
audioFileUuid | String | ||
audioMetadata | Dict[str, Any] | ||
content | str | List[Dict[str, Any]] | |
created_at | DateTime | ||
email_id | Integer | ||
escalationSignals | EscalationSignalsResponse | null | ||
id | String | ||
inbox_id | Integer | ||
interactionMode | Literal[text, push_to_talk, realtime] | ||
interactionSessionId | String | ||
interactionTurnId | String | ||
isCanned | Boolean | Default: False | |
memberId | Integer | ||
messageFeatures | MessageFeatures | null | ||
origin | String | ||
originalContent | str | List[Dict[str, Any]] | |
parentMessageId | String | ||
role | String | ||
smsDeliveryErrorCode | String | ||
smsDeliveryFailureReason | String | ||
smsDeliveryStatus | String | ||
smsDeliveryUpdatedAt | DateTime | ||
sourceCategories | Array | ||
sttMetadata | SttMetadataResponse | null | ||
suggestions | Array | ||
taskId | Integer | ||
tokenUsage | MessageTokenUsageResponse | null | ||
toolStatus | String | ||
tool_call_id | String | ||
tool_calls | Array<OpenAIFunctionToolCall> | Default: [] | |
truncatedAtMs | Integer | ||
truncationReason | String | ||
userRating | Number | ||
userRatingComment | String | ||
uuid | String |
Example:
{
"tool_calls": [],
"isCanned": false
}
OperatorChildTaskDetail
| Field | Type | Required | Description |
|---|---|---|---|
assignmentTaskId | Integer | ✓ | |
autoNext | Boolean | Default: False | |
celCondition | String | ||
choicePrompt | String | ||
order | Integer | Default: 0 | |
required | Boolean | Default: False | |
taskId | Integer | ✓ | |
taskName | String | ✓ | |
taskType | String | ✓ | |
taskUuid | String | ✓ | |
visitedAt | DateTime |
Example:
{
"assignmentTaskId": 0,
"taskId": 0,
"taskName": "string",
"taskUuid": "string",
"taskType": "string",
"autoNext": false,
"required": false,
"order": 0
}
OperatorTaskDetailResponse
| Field | Type | Required | Description |
|---|---|---|---|
abilities | Array<AbilityResponse> | Default: [] | |
assignmentId | Integer | ✓ | |
assignmentTaskId | Integer | ✓ | |
celGuard | String | ||
childTasks | Array<OperatorChildTaskDetail> | Default: [] | |
configuration | Object | ||
description | String | ||
inheritedAbilities | Array<AbilityResponse> | Default: [] | |
parentAssignmentTaskId | Integer | ||
parentTaskName | String | ||
prompt | String | ||
renderedPrompt | String | ||
taskId | Integer | ✓ | |
taskName | String | ✓ | |
taskType | String | ✓ |
Example:
{
"assignmentId": 0,
"assignmentTaskId": 0,
"taskId": 0,
"taskName": "string",
"taskType": "string",
"abilities": [],
"inheritedAbilities": [],
"childTasks": []
}
PageResponse
| Field | Type | Required | Description |
|---|---|---|---|
contentAMP | String | ✓ | |
contentBlocks | TipTapDocument | null | ✓ | |
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,
"slug": "string",
"title": "string",
"status": "draft",
"contentBlocks": null,
"contentMarkdown": "string",
"contentHtml": "string",
"contentAMP": "string",
"sourceMetadata": {},
"sourceHtml": "string",
"sourceMarkdown": "string",
"sourceUrl": "string",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"crawledAt": "2024-01-01T00:00:00Z",
"siteId": 0,
"isHomePage": false
}
PaginatedResponse[AssignmentResponse]
| Field | Type | Required | Description |
|---|---|---|---|
items | Array<AssignmentResponse> | ✓ | |
page | Integer | ✓ | |
pageSize | Integer | ✓ | |
total | Integer | ✓ | |
totalPages | Integer | ✓ |
Example:
{
"items": [],
"total": 0,
"page": 0,
"pageSize": 0,
"totalPages": 0
}
SttMetadataResponse
| Field | Type | Required | Description |
|---|---|---|---|
eotConfidence | Number | ||
mean | Number | ||
min | Number | ||
model | String | ||
words | Array<SttWordConfidenceResponse> | Default: [] |
Example:
{
"words": []
}
SttWordConfidenceResponse
| Field | Type | Required | Description |
|---|---|---|---|
c | Number | ✓ | |
e | Number | ||
s | Number | ||
w | String | ✓ |
Example:
{
"w": "string",
"c": 0.0
}
TipTapDocument
| Field | Type | Required | Description |
|---|---|---|---|
content | Array<TipTapNode> | null | ||
translations | Dictionary<String, TipTapDocument> | null | ||
type | Literal['doc'] | Default: doc |
Example:
{
"type": "doc"
}
TipTapMark
| Field | Type | Required | Description |
|---|---|---|---|
attrs | Dict[str, Any] | ||
type | String | ✓ |
Example:
{
"type": "string"
}
TipTapNode
| Field | Type | Required | Description |
|---|---|---|---|
attrs | Dict[str, Any] | ||
content | Array<TipTapNode> | null | ||
marks | Array<TipTapMark> | null | ||
text | String | ||
type | String | ✓ |
Example:
{
"type": "string"
}
UpdateAssignmentRequest
| Field | Type | Required | Description |
|---|---|---|---|
dataRecords | Array<DataRecordAssociationRequest> | null |
Example:
{}
Endpoints
GET /api/v2/w/{workspace_uuid}/assignments- ListPOST /api/v2/w/{workspace_uuid}/assignments- CreateGET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}- Get Assignment IdPUT /api/v2/w/{workspace_uuid}/assignments/{assignment_id}- Update Assignment IdPOST /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/cancel- CancelGET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/cel-context- Cel ContextGET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/current-task-detail- Current Task DetailGET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/messages- MessagesGET /api/v2/w/{workspace_uuid}/assignments/{assignment_id}/tasks/{assignment_task_id}- TasksPUT /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: 1pageSize(Integer) — min: 1, max: 100sortBy(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).
Request Body:
isTest: An assertion, not an authority. An assignment is a test assignment when its counterparty member is one — a TEST member, or an anonymous member minted by a test run — and the server derives the flag from that member rather than from the request body. SendingisTest: truefor an ordinary identified member is rejected with 400 and the stable body{"code": "test_provenance_required"}; omitting it (or sendingfalse) does not make a test member's assignment live. To create a test assignment, create or select a test member first.
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)
Response: Object
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