API v1 Reference › Tasks

Updates multiple tasks with the selected operation.

POSThttps://api.awork.com/api/v1/tasks/batch/{operation}
POST https://api.awork.com/api/v1/tasks/batch/{operation}

Updates multiple tasks with the selected operation. Supported operations move tasks, change dates, manage tags, change status or type, assign users, copy tasks, and delete tasks.

Authentication

AuthorizationBearer

Send your token in the Authorization: Bearer <token> header. See Authentication for API keys and OAuth.

Path parameters

operationstringRequired

The operation to perform on all tasks.

Request body Required

The model describing the batch task operation.

application/json

taskIdsarray of stringRequired

The list of task ids to perform the batch operation on.

newTaskListIdstring or nullOptional
format: uuid

The id of the new task list. Needed if operation is 'movetotasklist'. Optional if operation is 'movetoproject'.

removeFromCurrentListboolean or nullOptional

Whether to remove the task from all its current task lists. Optional for operation 'movetotasklist'.

newProjectIdstring or nullOptional
format: uuid

The id of the new project to move the tasks to. Needed if operation is 'movetoproject'.

newParentTaskIdstring or nullOptional
format: uuid

The id of the task that will be the new parent of the selected tasks. Needed if operation is 'moveundertask'.

newTaskStatusIdstring or nullOptionalDeprecated
format: uuid

Deprecated for 'movetoproject': use TaskStatusMapping instead. The id of the new task status id to change the tasks to. Needed if operation is 'movetoproject' or 'changetaskstatus'.

taskStatusMappingarray of object or nullOptional

The task status mapping from old task status to new task status. Optional for operation 'movetoproject'.

Show 2 properties
oldStatusIdstringRequired
format: uuid

The old task status id.

newStatusIdstringRequired
format: uuid

The new task status id.

newDueDatestring or nullOptional
format: date-time

The new due date for the tasks. Optional for operation 'setdates'. If not set, due and start date will be removed.

newStartDatestring or nullOptional
format: date-time

The new start date for the tasks. Optional for operation 'setdates'. Only gets used when NewDueDate is set.

removeDueDateboolean or nullOptional

Whether to remove the due date. Required for operation 'setdates'.

removeStartDateboolean or nullOptional

Whether to remove the start date. Required for operation 'setdates'.

tagsarray of object or nullOptional

List of tags to add to the tasks. If task already has tag, tag is skipped.

Show 2 properties
namestringRequired
minLength: 0 maxLength: 255

The name of the tag to delete.

colorstring or nullOptional

The color of the tag. Use one of 'red', 'coral', 'yellow', 'green', 'teal', 'arctic', 'blue', 'azure', 'purple', 'violet'.

deleteTimeTrackingsboolean or nullOptional

Whether to delete the timetrackings of each task when deleting tasks. Optional for operation 'delete'.

newTypeOfWorkIdstring or nullOptional
format: uuid

The new type of work id for the tasks. Required if operation is 'changetypeofwork'.

changeTimeEntriesboolean or nullOptional

Whether to change the type of work of the timeentries for each task aswell. Optional for operation 'changetypeofwork'.

userIdsarray of string or nullOptional

Depending on the batch operation, it can be either the ids of the user to assign ('assignusers', required) or the ids of the user to remove ('unassignusers', optional, if not provided unassigns all users).

removeOldAssignmentsboolean or nullOptional

Whether to replace or add user assignments to a task that has users already assigned. Optional for operation 'assignusers'.

isPrioboolean or nullOptional

Whether to set the tasks to be prio or not. Required for operation 'setprio'.

daysOffsetnumber or nullOptional
format: double

In case of an adjust date operation, define the number (positive or negative) of days that will be added/subtracted to the task dates. It can be a decimal number (fraction of day)

adjustSuccessorsboolean or nullOptional

If set to true, it will adjust the dates of successor tasks as well.

adjustSubtasksboolean or nullOptional

If set to true, it will adjust the dates of subtasks of selected tasks. If set to false, it will only adjust the dates of the selected tasks.

plannerDataobjectOptional

Data specific to planner batch operations for handling drag and drop in the planner UI.

Show 7 properties
referenceTaskIdstringRequired
format: uuid

The reference task that was dragged (determines delta calculation).

targetStartDatestring or nullOptional
format: date-time

Target start date for the reference task (used to calculate start date delta). Null if no start date change.

targetEndDatestring or nullOptional
format: date-time

Target end date for the reference task (used to calculate end date delta). Null if no end date change. Allows extending or shortening task duration.

timezonestring or nullOptional

The IANA timezone used for calendar-day moves. Uses the account timezone when omitted. Target dates remain UTC instants.

targetLaneOrderinteger or nullOptional
format: int32

Target lane order for vertical moves in planner. Null if no lane change.

setDatesbooleanOptional

Whether to set absolute dates for the task (not delta-based). When true, only a single task can be modified. Only applies when TargetStartDate or TargetEndDate is provided.

moveTypestringOptional

Allowed: "DateOnly" "LaneOnly" "DateAndLane" "AssigneeChange" "AssigneeAndLane" "AssigneeAndDate"

Defines the type of move operation in the planner.

Responses

207 Multi-Status

application/json

okobjectOptional

The entity IDs with the same batch operation outcome.

Show 1 properties
idsarray of string or nullOptional

The affected entity IDs.

notFoundobjectOptional

The entity IDs with the same batch operation outcome.

Show 1 properties
idsarray of string or nullOptional

The affected entity IDs.

unauthorizedobjectOptional

The entity IDs with the same batch operation outcome.

Show 1 properties
idsarray of string or nullOptional

The affected entity IDs.

badRequestobjectOptional

The entity IDs with the same batch operation outcome.

Show 1 properties
idsarray of string or nullOptional

The affected entity IDs.

400 Bad Request

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

401 Unauthorized

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

Search documentation