Skip to main content

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​

FieldTypeRequiredDescription
abilityTypeString✓
celConditionString
configDict[str, Any]✓
enabledBoolean✓
idInteger✓
uuidString✓

Example:

{
"id": 0,
"uuid": "string",
"abilityType": "string",
"config": {},
"enabled": false
}

AssignmentResponse​

FieldTypeRequiredDescription
concludedAtDateTime
createdAtDateTime✓
currentTaskAssignmentTaskResponse | null
dataRecordsArray<DataRecordResponse>Default: []
filesArray<FileResponse>✓
idInteger✓
isTestBoolean✓
memberIdInteger✓
outcomeString
outcomeReasonString
pagesArray<PageResponse>Default: []
rootTaskAssignmentTaskResponse | null
statusStringDefault: active
taskIdInteger
taskNameString
updatedAtDateTime✓
uuidString✓
workflowIdWorkflowId✓
workflowNameString
workflowRevisionIdWorkflowRevisionId
workflowRevisionNameString
workflowRevisionNumberInteger
workflowRevisionUuidString
workflowUuidString

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​

FieldTypeRequiredDescription
autoNextBoolean✓
childrenArray<AssignmentTaskResponse>Default: []
idInteger✓
requiredBoolean✓
taskIdInteger✓
taskNameString✓
taskUuidString✓
uuidString✓
visitedAtDateTime✓
workflowIdWorkflowId✓

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​

FieldTypeRequiredDescription
reasonString

Example:

{}

ChatApprovalDecision​

FieldTypeRequiredDescription
answerLiteral['approve', 'approve_always', 'reject', 'edit', 'other']✓
callIdString✓
toolString✓

Example:

{
"callId": "string",
"tool": "string",
"answer": "approve"
}

CreateAssignmentRequest​

FieldTypeRequiredDescription
dataRecordsArray<DataRecordAssociationRequest>Default: []
isTestBooleanDefault: False
memberIdInteger
taskIdInteger
workflowIdInteger
workflowRevisionIdInteger

Example:

{
"isTest": false,
"dataRecords": []
}

DataRecordAssociationRequest​

FieldTypeRequiredDescription
accessModeIntegerDefault: 0
idInteger✓

Example:

{
"id": 0,
"accessMode": 0
}

DataRecordResponse​

FieldTypeRequiredDescription
accessModeInteger
createdAtDateTime✓
createdByMemberIdInteger
dataTypeIdInteger✓
externalIdString
fieldValuesDict[str, Any]✓
idInteger✓
memberIdInteger✓
memberNameString
retirementDataRecordRetirementResponse | null
updatedAtDateTime✓
uuidUUID✓

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​

FieldTypeRequiredDescription
reasonLiteral['monday_item_archived', 'monday_item_deleted']✓
sourceLiteral['monday']Default: monday
statusLiteral['retired']Default: retired

Example:

{
"status": "retired",
"reason": "monday_item_archived",
"source": "monday"
}

EscalationSignalsResponse​

FieldTypeRequiredDescription
engineString
latencyMsNumber
raisedArrayDefault: []
scoresdict[str, float]Default: {}
signalSetString✓
statusString✓

Example:

{
"status": "string",
"signalSet": "string",
"scores": {},
"raised": []
}

FileFolderResponse​

FieldTypeRequiredDescription
accessStringDefault: private
ancestorsArray<FolderPathSegment>Default: []
childCountIntegerDefault: 0
createdAtDateTime✓
descriptionString
fileCountIntegerDefault: 0
idInteger✓
indexBooleanDefault: False
indexingCompletedAtDateTime
indexingStartedAtDateTime
nameString✓
ownerIdInteger
ownerNameString
parentIdInteger
pathString
shareableBooleanDefault: False
updatedAtDateTime✓
uuidString✓

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​

FieldTypeRequiredDescription
colorString✓
descriptionString✓
idInteger✓
nameString✓
uuidString✓

Example:

{
"id": 0,
"uuid": "string",
"name": "string",
"color": "string",
"description": "string"
}

FileResponse​

FieldTypeRequiredDescription
accessStringDefault: private
accessModeInteger
cdnUrlString✓
choicePromptString
createdAtDateTime✓
currentVersionNumberIntegerDefault: 0
dataString✓
descriptionString✓
externalIdString✓
fileSizeInteger✓
filenameString✓
folderFileFolderResponse | null✓
folderAncestorIdsArrayDefault: []
folderIdInteger✓
idInteger✓
isS3StoredBooleanDefault: False
labelsArray<FileLabelResponse> | null
lastEditedByMemberIdInteger
mimeTypeString✓
ownerIdInteger
ownerNameString
permissionsIntegerDefault: 0
shareCountIntegerDefault: 0
siteIdInteger✓
subjectMemberIdInteger
titleString✓
updatedAtDateTime✓
uuidString✓

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​

FieldTypeRequiredDescription
idInteger✓
nameString✓

Example:

{
"id": 0,
"name": "string"
}

MessageFeatureResponse​

FieldTypeRequiredDescription
decisionLiteral['greeting', 'answer']✓
engineString✓
latencyMsNumber✓
questionSetString✓
statusLiteral['decided', 'unavailable']✓
valueLiteral[human, voicemail, call_screening, unknown, answerable, not_found]✓

Example:

{
"decision": "greeting",
"value": null,
"status": "decided",
"engine": "string",
"questionSet": "string",
"latencyMs": 0.0
}

MessageFeatures​

FieldTypeRequiredDescription
greetingMessageFeatureResponse | null
retrievedAnswerMessageFeatureResponse | null

Example:

{}

MessageTokenUsageResponse​

FieldTypeRequiredDescription
cachedTokensIntegerDefault: 0
completionTokensInteger✓
creditsNumberDefault: 0.0
modelString✓
promptTokensInteger✓
totalTokensInteger✓

Example:

{
"model": "string",
"promptTokens": 0,
"completionTokens": 0,
"totalTokens": 0,
"cachedTokens": 0,
"credits": 0.0
}

OpenAIFunctionToolCall​

FieldTypeRequiredDescription
functionDict[str, Any]Default: {}
idStringDefault: ``
typeStringDefault: function

Example:

{
"id": "",
"type": "function",
"function": {}
}

OpenAIMessageResponse​

FieldTypeRequiredDescription
approvalDecisionChatApprovalDecision | null
audienceString
audioFileUuidString
audioMetadataDict[str, Any]
contentstrList[Dict[str, Any]]
created_atDateTime
email_idInteger
escalationSignalsEscalationSignalsResponse | null
idString
inbox_idInteger
interactionModeLiteral[text, push_to_talk, realtime]
interactionSessionIdString
interactionTurnIdString
isCannedBooleanDefault: False
memberIdInteger
messageFeaturesMessageFeatures | null
originString
originalContentstrList[Dict[str, Any]]
parentMessageIdString
roleString
smsDeliveryErrorCodeString
smsDeliveryFailureReasonString
smsDeliveryStatusString
smsDeliveryUpdatedAtDateTime
sourceCategoriesArray
sttMetadataSttMetadataResponse | null
suggestionsArray
taskIdInteger
tokenUsageMessageTokenUsageResponse | null
toolStatusString
tool_call_idString
tool_callsArray<OpenAIFunctionToolCall>Default: []
truncatedAtMsInteger
truncationReasonString
userRatingNumber
userRatingCommentString
uuidString

Example:

{
"tool_calls": [],
"isCanned": false
}

OperatorChildTaskDetail​

FieldTypeRequiredDescription
assignmentTaskIdInteger✓
autoNextBooleanDefault: False
celConditionString
choicePromptString
orderIntegerDefault: 0
requiredBooleanDefault: False
taskIdInteger✓
taskNameString✓
taskTypeString✓
taskUuidString✓
visitedAtDateTime

Example:

{
"assignmentTaskId": 0,
"taskId": 0,
"taskName": "string",
"taskUuid": "string",
"taskType": "string",
"autoNext": false,
"required": false,
"order": 0
}

OperatorTaskDetailResponse​

FieldTypeRequiredDescription
abilitiesArray<AbilityResponse>Default: []
assignmentIdInteger✓
assignmentTaskIdInteger✓
celGuardString
childTasksArray<OperatorChildTaskDetail>Default: []
configurationObject
descriptionString
inheritedAbilitiesArray<AbilityResponse>Default: []
parentAssignmentTaskIdInteger
parentTaskNameString
promptString
renderedPromptString
taskIdInteger✓
taskNameString✓
taskTypeString✓

Example:

{
"assignmentId": 0,
"assignmentTaskId": 0,
"taskId": 0,
"taskName": "string",
"taskType": "string",
"abilities": [],
"inheritedAbilities": [],
"childTasks": []
}

PageResponse​

FieldTypeRequiredDescription
contentAMPString✓
contentBlocksTipTapDocument | null✓
contentHtmlString✓
contentMarkdownString✓
crawledAtDateTime✓
createdAtDateTime✓
idInteger✓
isHomePageBooleanDefault: False
siteIdInteger✓
slugString✓
sourceHtmlString✓
sourceMarkdownString✓
sourceMetadatadict[str, Any]✓
sourceUrlString✓
statusStringDefault: draft
titleString✓
updatedAtDateTime✓
urlString

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

FieldTypeRequiredDescription
itemsArray<AssignmentResponse>✓
pageInteger✓
pageSizeInteger✓
totalInteger✓
totalPagesInteger✓

Example:

{
"items": [],
"total": 0,
"page": 0,
"pageSize": 0,
"totalPages": 0
}

SttMetadataResponse​

FieldTypeRequiredDescription
eotConfidenceNumber
meanNumber
minNumber
modelString
wordsArray<SttWordConfidenceResponse>Default: []

Example:

{
"words": []
}

SttWordConfidenceResponse​

FieldTypeRequiredDescription
cNumber✓
eNumber
sNumber
wString✓

Example:

{
"w": "string",
"c": 0.0
}

TipTapDocument​

FieldTypeRequiredDescription
contentArray<TipTapNode> | null
translationsDictionary<String, TipTapDocument> | null
typeLiteral['doc']Default: doc

Example:

{
"type": "doc"
}

TipTapMark​

FieldTypeRequiredDescription
attrsDict[str, Any]
typeString✓

Example:

{
"type": "string"
}

TipTapNode​

FieldTypeRequiredDescription
attrsDict[str, Any]
contentArray<TipTapNode> | null
marksArray<TipTapMark> | null
textString
typeString✓

Example:

{
"type": "string"
}

UpdateAssignmentRequest​

FieldTypeRequiredDescription
dataRecordsArray<DataRecordAssociationRequest> | null

Example:

{}

Endpoints​

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

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. Sending isTest: true for an ordinary identified member is rejected with 400 and the stable body {"code": "test_provenance_required"}; omitting it (or sending false) 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