RoadOps Developer Docs - Set List Items

List set list items

GET/v1/teams/{teamId}/set-list-items

Lists reusable set list library items for a team.

Required scopes: set_list_item: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.

Response 200

`data`	`object[]`
`data[].title`	`string` Reusable set list item title.
`data[].durationSeconds`	`integer` Default duration in seconds for this reusable set list item.
`data[].printTitle`	`string` Optional title to use on printed set list output.
`data[].notes`	`string` Optional notes for the set list item.
`data[].id`	`string:uuid` Set list item identifier.
`data[].orgId`	`string:uuid` Team identifier that owns this reusable set list item.
`data[].isRetired`	`boolean` Whether this reusable item is hidden from active use.
`data[].retiredAt`	`string:date-time` ISO 8601 timestamp when the item was retired.
`data[].retiredBy`	`string` User identifier that retired this item.
`data[].isDeleted`	`boolean` Whether this reusable item has been deleted.
`data[].version`	`integer` Current set list item aggregate version.
`data[].createdAt`	`string:date-time` ISO 8601 timestamp when the item was created.
`data[].createdBy`	`string` User identifier that created this item.
`data[].updatedAt`	`string:date-time` ISO 8601 timestamp when the item was last updated.
`data[].updatedBy`	`string` User identifier that last updated this item.
`data[].cursor`	`integer` Latest event-ledger cursor projected into this set list item record.
`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` Highest record cursor represented by this response.

Create a set list item

POST/v1/teams/{teamId}/set-list-items

Accepts a command to create a reusable set list library item.

Required scopes: set_list_item:write

Parameters

`path.teamId`required	`string:uuid` Team 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)

`title`required	`string` Reusable set list item title.
`durationSeconds`required	`integer` Default duration in seconds for this reusable set list item.
`printTitle`	`string` Optional title to use on printed set list output.
`notes`	`string` Optional notes for the set list item.
`id`	`string:uuid` Optional caller-supplied set list item ID. RoadOps generates one when omitted.

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` Event-ledger 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 set list item

GET/v1/teams/{teamId}/set-list-items/{setListItemId}

Returns one reusable set list library item by ID.

Required scopes: set_list_item:read

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.setListItemId`required	`string:uuid` Set list item identifier.

Response 200

`data`	`object`
`data.title`	`string` Reusable set list item title.
`data.durationSeconds`	`integer` Default duration in seconds for this reusable set list item.
`data.printTitle`	`string` Optional title to use on printed set list output.
`data.notes`	`string` Optional notes for the set list item.
`data.id`	`string:uuid` Set list item identifier.
`data.orgId`	`string:uuid` Team identifier that owns this reusable set list item.
`data.isRetired`	`boolean` Whether this reusable item is hidden from active use.
`data.retiredAt`	`string:date-time` ISO 8601 timestamp when the item was retired.
`data.retiredBy`	`string` User identifier that retired this item.
`data.isDeleted`	`boolean` Whether this reusable item has been deleted.
`data.version`	`integer` Current set list item aggregate version.
`data.createdAt`	`string:date-time` ISO 8601 timestamp when the item was created.
`data.createdBy`	`string` User identifier that created this item.
`data.updatedAt`	`string:date-time` ISO 8601 timestamp when the item was last updated.
`data.updatedBy`	`string` User identifier that last updated this item.
`data.cursor`	`integer` Latest event-ledger cursor projected into this set list item record.
`meta`	`object`
`meta.cursor`	`integer` Highest record cursor represented by this response.

Update a set list item

PATCH/v1/teams/{teamId}/set-list-items/{setListItemId}

Accepts a command to update reusable set list library item fields.

Required scopes: set_list_item:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.setListItemId`required	`string:uuid` Set list item 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` Set list library item fields to update.
`updates.title`	`string` Reusable set list item title.
`updates.durationSeconds`	`integer` Default duration in seconds for this reusable set list item.
`updates.printTitle`	`string` Optional title to use on printed set list output.
`updates.notes`	`string` Optional notes for the set list item.

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` Event-ledger 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 set list item

DELETE/v1/teams/{teamId}/set-list-items/{setListItemId}

Accepts a command to delete a reusable set list library item.

Required scopes: set_list_item:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.setListItemId`required	`string:uuid` Set list item 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` Event-ledger cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative URL to refetch the affected resource.

Retire a set list item

POST/v1/teams/{teamId}/set-list-items/{setListItemId}/retire

Accepts a command to retire a reusable set list library item without deleting it.

Required scopes: set_list_item:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.setListItemId`required	`string:uuid` Set list item 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.
`timestamp`	`string:date-time` Optional ISO 8601 timestamp to use for the lifecycle transition.

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` Event-ledger cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative URL to refetch the affected resource.

Restore a set list item

POST/v1/teams/{teamId}/set-list-items/{setListItemId}/restore

Accepts a command to restore a retired reusable set list library item.

Required scopes: set_list_item:write

Parameters

`path.teamId`required	`string:uuid` Team identifier.
`path.setListItemId`required	`string:uuid` Set list item 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.
`timestamp`	`string:date-time` Optional ISO 8601 timestamp to use for the lifecycle transition.

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` Event-ledger cursor for the accepted update. Refetch until returned records reach this cursor.
`links`	`object`
`links.refetch`	`string` Relative URL to refetch the affected resource.