Tasks
Ask
List my tasks
GET/v1/teams/{teamId}/tasksLists Tasks assigned to the current user across visible days, including older overdue Tasks. Completion is checked against the current task projection, not stale assignment-index state. A filtered result may be empty with a continuation cursor. Continue with page.nextCursor until it is null, keeping the same filters.
Required scopes: task:read
Parameters
path.teamIdrequired | string:uuidTeam identifier. |
|---|---|
query.limit | integerMaximum number of records to return. Defaults to 50 and is capped at 200. |
query.cursor | stringOpaque cursor returned by page.nextCursor. Reuse the same credential, endpoint, and filters within 24 hours; restart pagination after expiration or credential changes. |
query.includeCompleted | booleanInclude completed tasks. Defaults to false. |
Response 200
data | object[] |
|---|---|
data[].id | string:uuidTask identifier. |
data[].orgId | string:uuidOrganization identifier. |
data[].dayId | string:uuidImmutable associated RoadOps Day identifier. |
data[].title | stringTask title. |
data[].description | stringOptional Task description. |
data[].color | stringOptional Task display color token. |
data[].priority | "highest" | "high" | "medium" | "low" | "lowest"Task priority from highest to lowest. |
data[].sortOrder | integerShared custom order within a Day, ascending. Unordered tasks follow ordered tasks; ties use title then ID. Completed tasks remain last. Requires tasks:manage-all to change. |
data[].categoryId | string:uuidOptional organization Task category identifier. |
data[].statusId | "todo" | "doing" | "waiting" | "done" | string:uuidBuilt-in Task status ID or custom Task status UUID. |
data[].canonicalState | "todo" | "doing" | "waiting" | "done"Normalized Task workflow state used for filtering and completion behavior. |
data[].assigneeIds | string:uuid[]RoadOps user IDs assigned to the Task. |
data[].dueDate | string:dateOptional due date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. Independent of the associated Day. |
data[].reminder | objectOptional reminder resolved in an IANA timezone. |
data[].reminder.date | string:dateLocal reminder date in YYYY-MM-DD format, such as 2026-09-12. |
data[].reminder.time | stringLocal reminder time in 24-hour HH:mm format, such as 09:00. |
data[].reminder.timezone | stringIANA timezone used to resolve the reminder. |
data[].reminder.reminderAt | string:date-timeDerived UTC reminder timestamp. |
data[].createdBy | string:uuidRoadOps user ID that created the Task. |
data[].createdAt | string:date-timeUTC Task creation timestamp. |
data[].updatedAt | string:date-timeUTC timestamp of the latest Task change. |
data[].completedAt | string:date-timeUTC completion timestamp when the Task is done. |
data[].completedBy | string:uuidRoadOps user ID that completed the Task. |
data[].isDeleted | booleanSoft-delete flag. |
data[].version | integerCurrent Task aggregate version. |
data[].cursor | integerLatest cursor projected into this Task. |
page | object |
page.limit | integerMaximum number of records returned in this page. |
page.nextCursor | string | nullOpaque cursor to pass as the next request's cursor query parameter with the same credential, endpoint, and filters within 24 hours, or null when there are no more results. Restart pagination after expiration or credential changes. |
meta | object |
meta.cursor | number | null |
List tasks
GET/v1/teams/{teamId}/days/{dayId}/tasksLists visible Tasks associated with a RoadOps Day. Callers without Task Manage All receive only Tasks assigned to them.
Required scopes: task:read
Parameters
path.teamIdrequired | string:uuidTeam identifier. |
|---|---|
path.dayIdrequired | string:uuidDay identifier. |
query.limit | integerMaximum number of records to return. Defaults to 50 and is capped at 200. |
query.cursor | stringOpaque cursor returned by page.nextCursor. Reuse the same credential, endpoint, and filters within 24 hours; restart pagination after expiration or credential changes. |
Response 200
data | object[] |
|---|---|
data[].id | string:uuidTask identifier. |
data[].orgId | string:uuidOrganization identifier. |
data[].dayId | string:uuidImmutable associated RoadOps Day identifier. |
data[].title | stringTask title. |
data[].description | stringOptional Task description. |
data[].color | stringOptional Task display color token. |
data[].priority | "highest" | "high" | "medium" | "low" | "lowest"Task priority from highest to lowest. |
data[].sortOrder | integerShared custom order within a Day, ascending. Unordered tasks follow ordered tasks; ties use title then ID. Completed tasks remain last. Requires tasks:manage-all to change. |
data[].categoryId | string:uuidOptional organization Task category identifier. |
data[].statusId | "todo" | "doing" | "waiting" | "done" | string:uuidBuilt-in Task status ID or custom Task status UUID. |
data[].canonicalState | "todo" | "doing" | "waiting" | "done"Normalized Task workflow state used for filtering and completion behavior. |
data[].assigneeIds | string:uuid[]RoadOps user IDs assigned to the Task. |
data[].dueDate | string:dateOptional due date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. Independent of the associated Day. |
data[].reminder | objectOptional reminder resolved in an IANA timezone. |
data[].reminder.date | string:dateLocal reminder date in YYYY-MM-DD format, such as 2026-09-12. |
data[].reminder.time | stringLocal reminder time in 24-hour HH:mm format, such as 09:00. |
data[].reminder.timezone | stringIANA timezone used to resolve the reminder. |
data[].reminder.reminderAt | string:date-timeDerived UTC reminder timestamp. |
data[].createdBy | string:uuidRoadOps user ID that created the Task. |
data[].createdAt | string:date-timeUTC Task creation timestamp. |
data[].updatedAt | string:date-timeUTC timestamp of the latest Task change. |
data[].completedAt | string:date-timeUTC completion timestamp when the Task is done. |
data[].completedBy | string:uuidRoadOps user ID that completed the Task. |
data[].isDeleted | booleanSoft-delete flag. |
data[].version | integerCurrent Task aggregate version. |
data[].cursor | integerLatest cursor projected into this Task. |
page | object |
page.limit | integerMaximum number of records returned in this page. |
page.nextCursor | string | nullOpaque cursor to pass as the next request's cursor query parameter with the same credential, endpoint, and filters within 24 hours, or null when there are no more results. Restart pagination after expiration or credential changes. |
meta | object |
meta.cursor | number | null |
Create a task
POST/v1/teams/{teamId}/days/{dayId}/tasksCreates a Task. Callers without Task Manage All may assign only themselves.
Required scopes: task:write
Parameters
path.teamIdrequired | string:uuidTeam identifier. |
|---|---|
path.dayIdrequired | string:uuidDay identifier. |
header.Idempotency-Key | string:uuidOptional caller-generated UUID used to make mutation retries safe. Reuse the same UUID only when retrying the same request. |
Request body (application/json)
id | string:uuidOptional caller-supplied Task ID. |
|---|---|
titlerequired | stringTask title. |
description | stringOptional Task description. |
color | stringOptional Task display color token. |
priorityrequired | "highest" | "high" | "medium" | "low" | "lowest"Task priority from highest to lowest. |
sortOrder | integerShared custom order within a Day, ascending. Unordered tasks follow ordered tasks; ties use title then ID. Completed tasks remain last. Requires tasks:manage-all to change. |
categoryId | string:uuidOptional organization Task category identifier. |
statusIdrequired | "todo" | "doing" | "waiting" | "done" | string:uuidBuilt-in Task status ID or custom Task status UUID. |
assigneeIdsrequired | string:uuid[]RoadOps user IDs assigned to the Task. |
dueDate | string:dateOptional due date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. Independent of the associated Day. |
reminder | objectOptional reminder. When supplied, date, time, and timezone are all required. |
reminder.daterequired | string:dateLocal calendar date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. |
reminder.timerequired | stringLocal time in 24-hour HH:mm format. |
reminder.timezonerequired | stringIANA timezone identifier, such as America/New_York or UTC. |
Response 202
commandId | string:uuidCommand identifier accepted into the RoadOps command ledger. |
|---|---|
resourceId | string:uuidIdentifier of the resource targeted by the command. |
resourceType | stringResource type targeted by the command. |
status | "applied"Command dispatch status. |
aggregateVersion | integerAggregate version produced by the accepted command. |
cursor | integerCursor for the accepted update. Refetch until returned records reach this cursor. |
links | object |
links.refetch | stringRelative URL to refetch the affected resource. |
Retrieve a task
GET/v1/teams/{teamId}/days/{dayId}/tasks/{taskId}Returns one visible Task.
Required scopes: task:read
Parameters
path.teamIdrequired | string:uuidTeam identifier. |
|---|---|
path.dayIdrequired | string:uuidDay identifier. |
path.taskIdrequired | string:uuidTask identifier. |
Response 200
data | object |
|---|---|
data.id | string:uuidTask identifier. |
data.orgId | string:uuidOrganization identifier. |
data.dayId | string:uuidImmutable associated RoadOps Day identifier. |
data.title | stringTask title. |
data.description | stringOptional Task description. |
data.color | stringOptional Task display color token. |
data.priority | "highest" | "high" | "medium" | "low" | "lowest"Task priority from highest to lowest. |
data.sortOrder | integerShared custom order within a Day, ascending. Unordered tasks follow ordered tasks; ties use title then ID. Completed tasks remain last. Requires tasks:manage-all to change. |
data.categoryId | string:uuidOptional organization Task category identifier. |
data.statusId | "todo" | "doing" | "waiting" | "done" | string:uuidBuilt-in Task status ID or custom Task status UUID. |
data.canonicalState | "todo" | "doing" | "waiting" | "done"Normalized Task workflow state used for filtering and completion behavior. |
data.assigneeIds | string:uuid[]RoadOps user IDs assigned to the Task. |
data.dueDate | string:dateOptional due date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. Independent of the associated Day. |
data.reminder | objectOptional reminder resolved in an IANA timezone. |
data.reminder.date | string:dateLocal reminder date in YYYY-MM-DD format, such as 2026-09-12. |
data.reminder.time | stringLocal reminder time in 24-hour HH:mm format, such as 09:00. |
data.reminder.timezone | stringIANA timezone used to resolve the reminder. |
data.reminder.reminderAt | string:date-timeDerived UTC reminder timestamp. |
data.createdBy | string:uuidRoadOps user ID that created the Task. |
data.createdAt | string:date-timeUTC Task creation timestamp. |
data.updatedAt | string:date-timeUTC timestamp of the latest Task change. |
data.completedAt | string:date-timeUTC completion timestamp when the Task is done. |
data.completedBy | string:uuidRoadOps user ID that completed the Task. |
data.isDeleted | booleanSoft-delete flag. |
data.version | integerCurrent Task aggregate version. |
data.cursor | integerLatest cursor projected into this Task. |
meta | object |
meta.cursor | integer |
Update a task
PATCH/v1/teams/{teamId}/days/{dayId}/tasks/{taskId}Updates editable Task fields.
Required scopes: task:write
Parameters
path.teamIdrequired | string:uuidTeam identifier. |
|---|---|
path.dayIdrequired | string:uuidDay identifier. |
path.taskIdrequired | string:uuidTask identifier. |
header.Idempotency-Key | string:uuidOptional caller-generated UUID used to make mutation retries safe. Reuse the same UUID only when retrying the same request. |
Request body (application/json)
expectedVersion | integerOptional aggregate version guard. |
|---|---|
updatesrequired | object |
updates.title | stringTask title. |
updates.description | string | nullUpdated description, or null to clear it. |
updates.color | string | nullUpdated color, or null to clear it. |
updates.priority | "highest" | "high" | "medium" | "low" | "lowest"Task priority from highest to lowest. |
updates.sortOrder | integerShared custom order within a Day, ascending. Unordered tasks follow ordered tasks; ties use title then ID. Completed tasks remain last. Requires tasks:manage-all to change. |
updates.categoryId | string:uuidUpdated category, or null to clear it. |
updates.dueDate | string:dateUpdated due date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. Send null to clear it. |
updates.reminder | object | nullUpdated local reminder fields, or null to clear the reminder. |
updates.reminder.daterequired | string:dateLocal calendar date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. |
updates.reminder.timerequired | stringLocal time in 24-hour HH:mm format. |
updates.reminder.timezonerequired | stringIANA timezone identifier, such as America/New_York or UTC. |
Response 202
commandId | string:uuidCommand identifier accepted into the RoadOps command ledger. |
|---|---|
resourceId | string:uuidIdentifier of the resource targeted by the command. |
resourceType | stringResource type targeted by the command. |
status | "applied"Command dispatch status. |
aggregateVersion | integerAggregate version produced by the accepted command. |
cursor | integerCursor for the accepted update. Refetch until returned records reach this cursor. |
links | object |
links.refetch | stringRelative URL to refetch the affected resource. |
Delete a task
DELETE/v1/teams/{teamId}/days/{dayId}/tasks/{taskId}Deletes a Task.
Required scopes: task:write
Parameters
path.teamIdrequired | string:uuidTeam identifier. |
|---|---|
path.dayIdrequired | string:uuidDay identifier. |
path.taskIdrequired | string:uuidTask identifier. |
header.Idempotency-Key | string:uuidOptional caller-generated UUID used to make mutation retries safe. Reuse the same UUID only when retrying the same request. |
Response 202
commandId | string:uuidCommand identifier accepted into the RoadOps command ledger. |
|---|---|
resourceId | string:uuidIdentifier of the resource targeted by the command. |
resourceType | stringResource type targeted by the command. |
status | "applied"Command dispatch status. |
aggregateVersion | integerAggregate version produced by the accepted command. |
cursor | integerCursor for the accepted update. Refetch until returned records reach this cursor. |
links | object |
links.refetch | stringRelative URL to refetch the affected resource. |
Change task status
POST/v1/teams/{teamId}/days/{dayId}/tasks/{taskId}/statusChanges the core or custom status of a Task.
Required scopes: task:write
Parameters
path.teamIdrequired | string:uuidTeam identifier. |
|---|---|
path.dayIdrequired | string:uuidDay identifier. |
path.taskIdrequired | string:uuidTask identifier. |
header.Idempotency-Key | string:uuidOptional caller-generated UUID used to make mutation retries safe. Reuse the same UUID only when retrying the same request. |
Request body (application/json)
expectedVersion | integer |
|---|---|
statusIdrequired | "todo" | "doing" | "waiting" | "done" | string:uuidBuilt-in Task status ID or custom Task status UUID. |
Response 202
commandId | string:uuidCommand identifier accepted into the RoadOps command ledger. |
|---|---|
resourceId | string:uuidIdentifier of the resource targeted by the command. |
resourceType | stringResource type targeted by the command. |
status | "applied"Command dispatch status. |
aggregateVersion | integerAggregate version produced by the accepted command. |
cursor | integerCursor for the accepted update. Refetch until returned records reach this cursor. |
links | object |
links.refetch | stringRelative URL to refetch the affected resource. |
Replace task assignees
POST/v1/teams/{teamId}/days/{dayId}/tasks/{taskId}/assigneesReplaces Task assignees. Team Task Manage All permission is required.
Required scopes: task:write
Parameters
path.teamIdrequired | string:uuidTeam identifier. |
|---|---|
path.dayIdrequired | string:uuidDay identifier. |
path.taskIdrequired | string:uuidTask identifier. |
header.Idempotency-Key | string:uuidOptional caller-generated UUID used to make mutation retries safe. Reuse the same UUID only when retrying the same request. |
Request body (application/json)
expectedVersion | integer |
|---|---|
assigneeIdsrequired | string:uuid[]RoadOps user IDs assigned to the Task. |
Response 202
commandId | string:uuidCommand identifier accepted into the RoadOps command ledger. |
|---|---|
resourceId | string:uuidIdentifier of the resource targeted by the command. |
resourceType | stringResource type targeted by the command. |
status | "applied"Command dispatch status. |
aggregateVersion | integerAggregate version produced by the accepted command. |
cursor | integerCursor for the accepted update. Refetch until returned records reach this cursor. |
links | object |
links.refetch | stringRelative URL to refetch the affected resource. |
Get task activity
GET/v1/teams/{teamId}/days/{dayId}/tasks/{taskId}/activityReturns paginated EventLedger activity for a visible Task, including notes, subtasks, and attachments.
Required scopes: task:read
Parameters
path.teamIdrequired | string:uuidTeam identifier. |
|---|---|
path.dayIdrequired | string:uuidDay identifier. |
path.taskIdrequired | string:uuidTask identifier. |
query.limit | integerMaximum number of records to return. Defaults to 50 and is capped at 200. |
query.cursor | stringOpaque cursor returned by page.nextCursor. Reuse the same credential, endpoint, and filters within 24 hours; restart pagination after expiration or credential changes. |
Response 200
data | object[] |
|---|---|
data[].type | string |
data[].aggregateVersion | integer |
data[].globalPosition | integer |
data[].timestamp | string:date-time |
data[].createdBy | string |
data[].details | object |
page | object |
page.limit | integerMaximum number of records returned in this page. |
page.nextCursor | string | nullOpaque cursor to pass as the next request's cursor query parameter with the same credential, endpoint, and filters within 24 hours, or null when there are no more results. Restart pagination after expiration or credential changes. |