Task Assignments

Returns a paginated list of the acting user's own task assignments. This is the recipient's view — only assignments where the actor is the recipient are returned. Assignments for tasks the actor authored and distributed to others are not included; use GET /api/tasks/v4/tasks with distribution_kind=DISTRIBUTED for those.

The distribution_kind filter is required and must specify at least one of RECEIVED or PERSONAL.

Query Params

distribution_kind string[]

filters task assignments based on their association with the actor. Multiple values can be used.

RECEIVED: Tasks received by the actor, excluding personal tasks.
PERSONAL: Personal tasks of the actor.

progress_status string[]

Filter for the assignment progress status. Possible values are:

NEW: The recipient has never seen the task before.
OPEN: The recipient has seen but not finished the task.
FINISHED: The recipient has finished the task.

sort string[]

Sort options for the actor's own task assignments. Each option has ascending (_ASC) and descending (_DESC) variants:

CREATED_AT: Sort by when the assignment was created.
UPDATED_AT: Sort by when the assignment was last updated (e.g., when progress status changed).

body_format string[]

restricts the returned formatted content to the specified formats

PLAIN: the plain content is returned.
DELTA: the content is returned in delta format
HTML: the content is returned in html format

page_cursor string

A cursor pointing to the first item to be contained in the response array. Refer to our general "pagination" concept for more information.

page_limit integer

The maximum number of items to be contained in the response array. Refer to our general "pagination" concept for more information.

Response Body

200 OK

Error Codes

DISTRIBUTION_KIND_UNDEFINED
FEATURE_DISABLED

Delete existing task assignmentexperimental

Requires authentication via bearer.

Removes a single assignment from a task. Only the task author can delete assignments.

Constraint: A distributed task must always have at least one recipient. Attempting to remove the last remaining assignment returns TASK_ASSIGNMENTS_LOWER_LIMIT_VIOLATION. The operation cannot be undone.

Path Params

assignment_id stringrequired

The primary identifier of the assignment to access.

Response Body

204 No Content

Error Codes

TASK_NOT_FOUND
FEATURE_DISABLED
TASK_ASSIGNMENT_NOT_FOUND
TASK_ASSIGNMENTS_LOWER_LIMIT_VIOLATION

Mark task assignment as finishedexperimental

Requires authentication via bearer.

Marks the actor's own task assignment as finished. Only the assignment owner (the recipient) can finish their own assignment.

Status Transition: NEW or OPEN → FINISHED. If the assignment is already FINISHED, the operation succeeds without making any changes (idempotent).

Path Params

assignment_id stringrequired

The primary identifier of the assignment to mark as finished.

Response Body

200 OK

Error Codes

FEATURE_DISABLED
TASK_ASSIGNMENT_CHANGE_CONFLICT
TASK_ASSIGNMENT_NOT_FOUND
TASK_NOT_FOUND

Mark task assignment as openexperimental

Requires authentication via bearer.

Re-opens the actor's own task assignment, reverting a previously finished assignment back to open. Only the assignment owner (the recipient) can re-open their own assignment.

Status Transition: FINISHED → OPEN. If the assignment is already OPEN or NEW, the operation succeeds without making any changes (idempotent).

Path Params

assignment_id stringrequired

The primary identifier of the assignment to mark as open.

Response Body

200 OK

Error Codes

FEATURE_DISABLED
TASK_ASSIGNMENT_CHANGE_CONFLICT
TASK_ASSIGNMENT_NOT_FOUND
TASK_NOT_FOUND

Get task assignments for taskexperimental

Requires authentication via bearer.

Retrieves a paginated list of individual assignments for a specific task. Accessible only to the task author. Use the embed=USER option to include recipient user details in the response.

Path Params

task_id stringrequired

The primary identifier of the task to access.

Query Params

embed string[]

Options for embedding additional data into task assignment responses:

USER: Includes the recipient's user profile in the recipient field of each assignment.

page_cursor string

A cursor pointing to the first item to be contained in the response array. Refer to our general "pagination" concept for more information.

page_limit integer

The maximum number of items to be contained in the response array. Refer to our general "pagination" concept for more information.

sort string[]

Sort options for a task's assignments. Each option has ascending (_ASC) and descending (_DESC) variants:

LASTNAME: Sort by the recipient's last name alphabetically.

progress_status string[]

Filter for the assignment progress status. Possible values are:

NEW: The recipient has never seen the task before.
OPEN: The recipient has seen but not finished the task.
FINISHED: The recipient has finished the task.

body_format string[]

restricts the returned formatted content to the specified formats

PLAIN: the plain content is returned.
DELTA: the content is returned in delta format
HTML: the content is returned in html format

Response Body

200 OK

Error Codes

FEATURE_DISABLED
TASK_NOT_FOUND
VALIDATION_ERROR

Create new task assignmentexperimental

Requires authentication via bearer.

Adds a single recipient (user or channel) to an existing task. Only the task author can add assignments.

Idempotent Behavior:

If the specified recipient is already assigned to the task, no new assignment is created and 200 OK is returned.
If the recipient is new, the assignment is created and 201 Created is returned.

Both responses include the updated TaskAssignmentsSummary for the task.

Path Params

task_id stringrequired

The primary identifier of the task to access.

Request Body

recipient objectrequired

Response Body

200 OK

201 Created

Error Codes

FEATURE_DISABLED
NOT_ADMIN_OF_CHANNEL
TASK_NOT_FOUND
UNKNOWN_CHANNEL_ID
UNKNOWN_USER_ID
VALIDATION_ERROR

Create multiple task assignmentsexperimental

Requires authentication via bearer.

Adds multiple user recipients to an existing task in a single request. Only the task author can add assignments.

Constraints:

Only USER type recipients are supported (channels cannot be added via batch).
Maximum 100 user IDs per request.
Already-assigned users are silently skipped; only truly new assignments are created.

Returns 200 OK if no new assignments were created, 201 Created if at least one was added. Both responses include the updated TaskAssignmentsSummary for the task.

Path Params

task_id stringrequired

The primary identifier of the task to access.

Request Body

user_ids object[]

Response Body

200 OK

201 Created

Error Codes

FEATURE_DISABLED
NOT_ADMIN_OF_CHANNEL
TASK_NOT_FOUND
UNKNOWN_USER_ID
UNKNOWN_CHANNEL_ID

Delete multiple task assignmentsexperimental

Requires authentication via bearer.

Removes multiple assignments from a task in a single request. Only the task author can delete assignments.

Constraint: A distributed task must always retain at least one recipient. If the deletion would leave the task with no recipients, TASK_ASSIGNMENTS_LOWER_LIMIT_VIOLATION is returned and no assignments are deleted. The operation cannot be undone.

Path Params

task_id stringrequired

The primary identifier of the task to access.

Request Body

assignment_ids object[]

Response Body

200 OK

Error Codes

TASK_NOT_FOUND
FEATURE_DISABLED
TASK_ASSIGNMENT_NOT_FOUND
TASK_ASSIGNMENTS_LOWER_LIMIT_VIOLATION
UNKNOWN_TASK_ASSIGNMENT_ID
VALIDATION_ERROR