RoadOps Developer Docs

List my tasks

GET/v1/teams/{teamId}/tasks

Lists 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.teamId`required	`string:uuid` Team identifier.
`query.limit`	`integer` Maximum number of records to return. Defaults to 50 and is capped at 200.
`query.cursor`	`string` Cursor returned by page.nextCursor from the previous list response.
`query.includeCompleted`	`boolean` Include completed tasks. Defaults to false.

Response 200

`data`	`object[]`
`data[].id`	`string:uuid` Task identifier.
`data[].orgId`	`string:uuid` Organization identifier.
`data[].dayId`	`string:uuid` Immutable associated RoadOps Day identifier.
`data[].title`	`string` Task title.
`data[].description`	`string` Optional Task description.
`data[].color`	`string` Optional Task display color token.
`data[].priority`	`"highest" \| "high" \| "medium" \| "low" \| "lowest"` Task priority from highest to lowest.
`data[].sortOrder`	`integer` Shared 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:uuid` Optional organization Task category identifier.
`data[].statusId`	`"todo" \| "doing" \| "waiting" \| "done" \| string:uuid` Built-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:date` Optional due date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. Independent of the associated Day.
`data[].reminder`	`object` Optional reminder resolved in an IANA timezone.
`data[].reminder.date`	`string:date` Local reminder date in YYYY-MM-DD format, such as 2026-09-12.
`data[].reminder.time`	`string` Local reminder time in 24-hour HH:mm format, such as 09:00.
`data[].reminder.timezone`	`string` IANA timezone used to resolve the reminder.
`data[].reminder.reminderAt`	`string:date-time` Derived UTC reminder timestamp.
`data[].createdBy`	`string:uuid` RoadOps user ID that created the Task.
`data[].createdAt`	`string:date-time` UTC Task creation timestamp.
`data[].updatedAt`	`string:date-time` UTC timestamp of the latest Task change.
`data[].completedAt`	`string:date-time` UTC completion timestamp when the Task is done.
`data[].completedBy`	`string:uuid` RoadOps user ID that completed the Task.
`data[].isDeleted`	`boolean` Soft-delete flag.
`data[].version`	`integer` Current Task aggregate version.
`data[].cursor`	`integer` Latest cursor projected into this Task.
`page`	`object`
`page.limit`	`integer` Maximum number of records returned in this page.
`page.nextCursor`	`string \| null` Cursor to pass as the next request's cursor query parameter, or null when there are no more results.
`meta`	`object`
`meta.cursor`	`number \| null`

Response: List my Tasks

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000221",
      "title": "Confirm venue load-in details",
      "description": "Check dock access and shore power.",
      "statusId": "todo",
      "assigneeIds": [
        "00000000-0000-4000-8000-000000000702"
      ],
      "dueDate": "2026-09-12",
      "orgId": "00000000-0000-4000-8000-000000000100",
      "dayId": "00000000-0000-4000-8000-000000000201",
      "canonicalState": "todo",
      "createdBy": "00000000-0000-4000-8000-000000000702",
      "createdAt": "2026-09-10T14:00:00.000Z",
      "updatedAt": "2026-09-10T14:00:00.000Z",
      "isDeleted": false,
      "version": 1,
      "cursor": 87235
    }
  ],
  "page": {
    "limit": 50,
    "nextCursor": null
  },
  "meta": {
    "cursor": 87234
  }
}

List tasks

GET/v1/teams/{teamId}/days/{dayId}/tasks

Lists visible Tasks associated with a RoadOps Day. Callers without Task Manage All receive only Tasks assigned to them.

Required scopes: task:read

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.dayId`required	`string:uuid` Day identifier.
`query.limit`	`integer` Maximum number of records to return. Defaults to 50 and is capped at 200.
`query.cursor`	`string` Cursor returned by page.nextCursor from the previous list response.

Response 200

`data`	`object[]`
`data[].id`	`string:uuid` Task identifier.
`data[].orgId`	`string:uuid` Organization identifier.
`data[].dayId`	`string:uuid` Immutable associated RoadOps Day identifier.
`data[].title`	`string` Task title.
`data[].description`	`string` Optional Task description.
`data[].color`	`string` Optional Task display color token.
`data[].priority`	`"highest" \| "high" \| "medium" \| "low" \| "lowest"` Task priority from highest to lowest.
`data[].sortOrder`	`integer` Shared 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:uuid` Optional organization Task category identifier.
`data[].statusId`	`"todo" \| "doing" \| "waiting" \| "done" \| string:uuid` Built-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:date` Optional due date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. Independent of the associated Day.
`data[].reminder`	`object` Optional reminder resolved in an IANA timezone.
`data[].reminder.date`	`string:date` Local reminder date in YYYY-MM-DD format, such as 2026-09-12.
`data[].reminder.time`	`string` Local reminder time in 24-hour HH:mm format, such as 09:00.
`data[].reminder.timezone`	`string` IANA timezone used to resolve the reminder.
`data[].reminder.reminderAt`	`string:date-time` Derived UTC reminder timestamp.
`data[].createdBy`	`string:uuid` RoadOps user ID that created the Task.
`data[].createdAt`	`string:date-time` UTC Task creation timestamp.
`data[].updatedAt`	`string:date-time` UTC timestamp of the latest Task change.
`data[].completedAt`	`string:date-time` UTC completion timestamp when the Task is done.
`data[].completedBy`	`string:uuid` RoadOps user ID that completed the Task.
`data[].isDeleted`	`boolean` Soft-delete flag.
`data[].version`	`integer` Current Task aggregate version.
`data[].cursor`	`integer` Latest cursor projected into this Task.
`page`	`object`
`page.limit`	`integer` Maximum number of records returned in this page.
`page.nextCursor`	`string \| null` Cursor to pass as the next request's cursor query parameter, or null when there are no more results.
`meta`	`object`
`meta.cursor`	`number \| null`

Response: List tasks

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000221",
      "title": "Confirm venue load-in details",
      "description": "Check dock access and shore power.",
      "statusId": "todo",
      "assigneeIds": [
        "00000000-0000-4000-8000-000000000702"
      ],
      "dueDate": "2026-09-12",
      "orgId": "00000000-0000-4000-8000-000000000100",
      "dayId": "00000000-0000-4000-8000-000000000201",
      "canonicalState": "todo",
      "createdBy": "00000000-0000-4000-8000-000000000702",
      "createdAt": "2026-09-10T14:00:00.000Z",
      "updatedAt": "2026-09-10T14:00:00.000Z",
      "isDeleted": false,
      "version": 1,
      "cursor": 87235
    }
  ],
  "page": {
    "limit": 50,
    "nextCursor": null
  },
  "meta": {
    "cursor": 87234
  }
}

Create a task

POST/v1/teams/{teamId}/days/{dayId}/tasks

Creates a Task. Callers without Task Manage All may assign only themselves.

Required scopes: task:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.dayId`required	`string:uuid` Day identifier.
`header.Idempotency-Key`	`string:uuid` Optional 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:uuid` Optional caller-supplied Task ID.
`title`required	`string` Task title.
`description`	`string` Optional Task description.
`color`	`string` Optional Task display color token.
`priority`required	`"highest" \| "high" \| "medium" \| "low" \| "lowest"` Task priority from highest to lowest.
`sortOrder`	`integer` Shared 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:uuid` Optional organization Task category identifier.
`statusId`required	`"todo" \| "doing" \| "waiting" \| "done" \| string:uuid` Built-in Task status ID or custom Task status UUID.
`assigneeIds`required	`string:uuid[]` RoadOps user IDs assigned to the Task.
`dueDate`	`string:date` Optional due date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. Independent of the associated Day.
`reminder`	`object` Optional reminder. When supplied, date, time, and timezone are all required.
`reminder.date`required	`string:date` Local calendar date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone.
`reminder.time`required	`string` Local time in 24-hour HH:mm format.
`reminder.timezone`required	`string` IANA timezone identifier, such as America/New_York or UTC.

Response 202

`commandId`	`string:uuid` Command identifier accepted into the RoadOps command ledger.
`resourceId`	`string:uuid` Identifier of the resource targeted by the command.
`resourceType`	`string` Resource type targeted by the command.
`status`	`"applied"` Command dispatch status.
`aggregateVersion`	`integer` Aggregate version produced by the accepted command.
`cursor`	`integer` Cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative 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.teamId`required	`string:uuid` Team identifier.
`path.dayId`required	`string:uuid` Day identifier.
`path.taskId`required	`string:uuid` Task identifier.

Response 200

`data`	`object`
`data.id`	`string:uuid` Task identifier.
`data.orgId`	`string:uuid` Organization identifier.
`data.dayId`	`string:uuid` Immutable associated RoadOps Day identifier.
`data.title`	`string` Task title.
`data.description`	`string` Optional Task description.
`data.color`	`string` Optional Task display color token.
`data.priority`	`"highest" \| "high" \| "medium" \| "low" \| "lowest"` Task priority from highest to lowest.
`data.sortOrder`	`integer` Shared 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:uuid` Optional organization Task category identifier.
`data.statusId`	`"todo" \| "doing" \| "waiting" \| "done" \| string:uuid` Built-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:date` Optional due date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. Independent of the associated Day.
`data.reminder`	`object` Optional reminder resolved in an IANA timezone.
`data.reminder.date`	`string:date` Local reminder date in YYYY-MM-DD format, such as 2026-09-12.
`data.reminder.time`	`string` Local reminder time in 24-hour HH:mm format, such as 09:00.
`data.reminder.timezone`	`string` IANA timezone used to resolve the reminder.
`data.reminder.reminderAt`	`string:date-time` Derived UTC reminder timestamp.
`data.createdBy`	`string:uuid` RoadOps user ID that created the Task.
`data.createdAt`	`string:date-time` UTC Task creation timestamp.
`data.updatedAt`	`string:date-time` UTC timestamp of the latest Task change.
`data.completedAt`	`string:date-time` UTC completion timestamp when the Task is done.
`data.completedBy`	`string:uuid` RoadOps user ID that completed the Task.
`data.isDeleted`	`boolean` Soft-delete flag.
`data.version`	`integer` Current Task aggregate version.
`data.cursor`	`integer` Latest 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.teamId`required	`string:uuid` Team identifier.
`path.dayId`required	`string:uuid` Day identifier.
`path.taskId`required	`string:uuid` Task identifier.
`header.Idempotency-Key`	`string:uuid` Optional 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` Optional aggregate version guard.
`updates`required	`object`
`updates.title`	`string` Task title.
`updates.description`	`string \| null` Updated description, or null to clear it.
`updates.color`	`string \| null` Updated color, or null to clear it.
`updates.priority`	`"highest" \| "high" \| "medium" \| "low" \| "lowest"` Task priority from highest to lowest.
`updates.sortOrder`	`integer` Shared 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:uuid` Updated category, or null to clear it.
`updates.dueDate`	`string:date` Updated due date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone. Send null to clear it.
`updates.reminder`	`object \| null` Updated local reminder fields, or null to clear the reminder.
`updates.reminder.date`required	`string:date` Local calendar date in YYYY-MM-DD format, such as 2026-09-12; no time or timezone.
`updates.reminder.time`required	`string` Local time in 24-hour HH:mm format.
`updates.reminder.timezone`required	`string` IANA timezone identifier, such as America/New_York or UTC.

Response 202

`commandId`	`string:uuid` Command identifier accepted into the RoadOps command ledger.
`resourceId`	`string:uuid` Identifier of the resource targeted by the command.
`resourceType`	`string` Resource type targeted by the command.
`status`	`"applied"` Command dispatch status.
`aggregateVersion`	`integer` Aggregate version produced by the accepted command.
`cursor`	`integer` Cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative 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.teamId`required	`string:uuid` Team identifier.
`path.dayId`required	`string:uuid` Day identifier.
`path.taskId`required	`string:uuid` Task identifier.
`header.Idempotency-Key`	`string:uuid` Optional caller-generated UUID used to make mutation retries safe. Reuse the same UUID only when retrying the same request.

Response 202

`commandId`	`string:uuid` Command identifier accepted into the RoadOps command ledger.
`resourceId`	`string:uuid` Identifier of the resource targeted by the command.
`resourceType`	`string` Resource type targeted by the command.
`status`	`"applied"` Command dispatch status.
`aggregateVersion`	`integer` Aggregate version produced by the accepted command.
`cursor`	`integer` Cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative URL to refetch the affected resource.

Change task status

POST/v1/teams/{teamId}/days/{dayId}/tasks/{taskId}/status

Changes the core or custom status of a Task.

Required scopes: task:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.dayId`required	`string:uuid` Day identifier.
`path.taskId`required	`string:uuid` Task identifier.
`header.Idempotency-Key`	`string:uuid` Optional 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`
`statusId`required	`"todo" \| "doing" \| "waiting" \| "done" \| string:uuid` Built-in Task status ID or custom Task status UUID.

Response 202

`commandId`	`string:uuid` Command identifier accepted into the RoadOps command ledger.
`resourceId`	`string:uuid` Identifier of the resource targeted by the command.
`resourceType`	`string` Resource type targeted by the command.
`status`	`"applied"` Command dispatch status.
`aggregateVersion`	`integer` Aggregate version produced by the accepted command.
`cursor`	`integer` Cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative URL to refetch the affected resource.

Replace task assignees

POST/v1/teams/{teamId}/days/{dayId}/tasks/{taskId}/assignees

Replaces Task assignees. Team Task Manage All permission is required.

Required scopes: task:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.dayId`required	`string:uuid` Day identifier.
`path.taskId`required	`string:uuid` Task identifier.
`header.Idempotency-Key`	`string:uuid` Optional 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`
`assigneeIds`required	`string:uuid[]` RoadOps user IDs assigned to the Task.

Response 202

`commandId`	`string:uuid` Command identifier accepted into the RoadOps command ledger.
`resourceId`	`string:uuid` Identifier of the resource targeted by the command.
`resourceType`	`string` Resource type targeted by the command.
`status`	`"applied"` Command dispatch status.
`aggregateVersion`	`integer` Aggregate version produced by the accepted command.
`cursor`	`integer` Cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative URL to refetch the affected resource.

Get task activity

GET/v1/teams/{teamId}/days/{dayId}/tasks/{taskId}/activity

Returns paginated EventLedger activity for a visible Task, including notes, subtasks, and attachments.

Required scopes: task:read

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.dayId`required	`string:uuid` Day identifier.
`path.taskId`required	`string:uuid` Task identifier.
`query.limit`	`integer` Maximum number of records to return. Defaults to 50 and is capped at 200.
`query.cursor`	`string` Cursor returned by page.nextCursor from the previous list response.

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`	`integer` Maximum number of records returned in this page.
`page.nextCursor`	`string \| null` Cursor to pass as the next request's cursor query parameter, or null when there are no more results.