A project-scoped task container. By default a flat list (isMilestone: false); set isMilestone: true for a date-spanning milestone with start/end timestamps and timeline ordering.
List Lists
List lists. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 11 fields. Ordered by order unless you pass sort.
Required scope: lists:read
query Parameters
projectIdRestrict the list to one project. Omit to list lists across every project you can access.
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: order. Listing without projectId orders by -updatedAt instead.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
archived[eq]Filter where archived equals.
isMilestone[eq]Filter where isMilestone equals.
projectId[eq]Filter where projectId equals.
projectId[in]Filter where projectId is one of (comma-separated list).
dependencyId[eq]Filter where dependencyId equals.
dependencyId[in]Filter where dependencyId is one of (comma-separated list).
statusId[eq]Filter where statusId equals.
statusId[in]Filter where statusId is one of (comma-separated list).
ruleId[eq]Filter where ruleId equals.
ruleId[in]Filter where ruleId is one of (comma-separated list).
start[gt]Filter where start is greater than.
start[gte]Filter where start is greater than or equal to.
start[lt]Filter where start is less than.
start[lte]Filter where start is less than or equal to.
end[gt]Filter where end is greater than.
end[gte]Filter where end is greater than or equal to.
end[lt]Filter where end is less than.
end[lte]Filter where end is less than or equal to.
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
updatedAt[gt]Filter where updatedAt is greater than.
updatedAt[gte]Filter where updatedAt is greater than or equal to.
updatedAt[lt]Filter where updatedAt is less than.
updatedAt[lte]Filter where updatedAt is less than or equal to.
List Lists › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Create List
Create a List. Server-assigned fields are ignored if sent.
Required scope: lists:write
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create List › Request Body
nameList name. Trimmed; obvious spam is rejected with 400.
projectIdProject this list belongs to (scope). Immutable after creation.
descriptionList description
startStart date (ISO 8601). Required together with end whenever isMilestone is true — including when flipping it true with a PATCH. end must be at least 2 days after start; use a task with a due date for single-day work. Forced to null when isMilestone is false.
endEnd date (ISO 8601). Required together with start whenever isMilestone is true — including when flipping it true with a PATCH. Must be at least 2 days after start; use a task with a due date for single-day work. Forced to null when isMilestone is false.
orderSort order within the project timeline. Server-defaulted to MAX(order)+100 when omitted on create.
color^#([0-9A-Fa-f]{3}|[0…Hex color, #RGB or #RRGGBB. Stored lowercase and expanded to 6 digits, so #0A9 reads back as #00aa99. Omitted on create → the server assigns a random palette color, so a list always has one.
archivedWhether this list is archived (hidden from the active timeline but preserved). Regular field, NOT a soft-delete.
isMilestonefalse (the default) = a flat list of tasks. true = a date-spanning milestone shown on the roadmap; it requires start and end at least 2 days apart.
dependencyIdId of the list that must finish before this one starts (timeline dependency). The target must belong to the same project, otherwise the request is rejected with 400.
statusIdWhen set, this list also appears as a column on the project board, backed by the given status. Cannot be changed after creation.
assigneesTeam members assigned to this list. Replaces the whole set on update; use POST/DELETE /lists/{id}/assignees for a single add/remove.
hiddenForRoles this list is hidden from. Replaces the whole set on update; use POST /lists/{id}/hidden-for and POST /lists/{id}/hidden-for/remove for a single add/remove. Every id must be a role in the same workspace.
goalsGoals this list contributes toward. Replaces the whole set on update; use POST/DELETE /lists/{id}/goals for a single add/remove.
Set custom-field values on this list. Each entry is { customFieldId, value } and value is always a string — send "" to clear one. Max 50 entries per request. Read them back with ?expand=customFields.
Create List › Responses
Created
idUnique identifier for this resource.
createdAtCreation timestamp.
projectIdProject this list belongs to (scope). Immutable after creation.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
archivedWhether this list is archived (hidden from the active timeline but preserved). Regular field, NOT a soft-delete.
nameList name. Trimmed; obvious spam is rejected with 400. Null only on lists created before this API existed.
descriptionList description
startStart date (ISO 8601). Required together with end whenever isMilestone is true — including when flipping it true with a PATCH. end must be at least 2 days after start; use a task with a due date for single-day work. Forced to null when isMilestone is false.
endEnd date (ISO 8601). Required together with start whenever isMilestone is true — including when flipping it true with a PATCH. Must be at least 2 days after start; use a task with a due date for single-day work. Forced to null when isMilestone is false.
orderSort order within the project timeline. Server-defaulted to MAX(order)+100 when omitted on create.
colorHex color, #RGB or #RRGGBB. Stored lowercase and expanded to 6 digits, so #0A9 reads back as #00aa99. Omitted on create → the server assigns a random palette color, so a list always has one.
isMilestonefalse (the default) = a flat list of tasks. true = a date-spanning milestone shown on the roadmap; it requires start and end at least 2 days apart.
dependencyIdId of the list that must finish before this one starts (timeline dependency). The target must belong to the same project, otherwise the request is rejected with 400.
statusIdWhen set, this list also appears as a column on the project board, backed by the given status. Cannot be changed after creation.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
The related Project, present only when you pass ?expand=project.
The related List, present only when you pass ?expand=dependency.
The related Recurring Rule, present only when you pass ?expand=recurringRule.
The related Status, present only when you pass ?expand=status.
The linked Team Member rows, present only when you pass ?expand=assignees.
The linked Role rows, present only when you pass ?expand=hiddenFor.
The linked Goal rows, present only when you pass ?expand=goals.
The linked attachedCustomField rows, present only when you pass ?expand=customFields.
The linked Task rows, present only when you pass ?expand=tasks.
Get List
Retrieve a single List by id.
Required scope: lists:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the List.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get List › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
projectIdProject this list belongs to (scope). Immutable after creation.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
archivedWhether this list is archived (hidden from the active timeline but preserved). Regular field, NOT a soft-delete.
nameList name. Trimmed; obvious spam is rejected with 400. Null only on lists created before this API existed.
descriptionList description
startStart date (ISO 8601). Required together with end whenever isMilestone is true — including when flipping it true with a PATCH. end must be at least 2 days after start; use a task with a due date for single-day work. Forced to null when isMilestone is false.
endEnd date (ISO 8601). Required together with start whenever isMilestone is true — including when flipping it true with a PATCH. Must be at least 2 days after start; use a task with a due date for single-day work. Forced to null when isMilestone is false.
orderSort order within the project timeline. Server-defaulted to MAX(order)+100 when omitted on create.
colorHex color, #RGB or #RRGGBB. Stored lowercase and expanded to 6 digits, so #0A9 reads back as #00aa99. Omitted on create → the server assigns a random palette color, so a list always has one.
isMilestonefalse (the default) = a flat list of tasks. true = a date-spanning milestone shown on the roadmap; it requires start and end at least 2 days apart.
dependencyIdId of the list that must finish before this one starts (timeline dependency). The target must belong to the same project, otherwise the request is rejected with 400.
statusIdWhen set, this list also appears as a column on the project board, backed by the given status. Cannot be changed after creation.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
The related Project, present only when you pass ?expand=project.
The related List, present only when you pass ?expand=dependency.
The related Recurring Rule, present only when you pass ?expand=recurringRule.
The related Status, present only when you pass ?expand=status.
The linked Team Member rows, present only when you pass ?expand=assignees.
The linked Role rows, present only when you pass ?expand=hiddenFor.
The linked Goal rows, present only when you pass ?expand=goals.
The linked attachedCustomField rows, present only when you pass ?expand=customFields.
The linked Task rows, present only when you pass ?expand=tasks.
Delete List
Permanently delete this List. This cannot be undone.
Required scope: lists:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the List.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete List › Responses
No Content
Update List
Partially update a List. Only the fields you send are changed.
Required scope: lists:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the List.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Update List › Request Body
nameList name. Trimmed; obvious spam is rejected with 400.
descriptionList description
startStart date (ISO 8601). Required together with end whenever isMilestone is true — including when flipping it true with a PATCH. end must be at least 2 days after start; use a task with a due date for single-day work. Forced to null when isMilestone is false.
endEnd date (ISO 8601). Required together with start whenever isMilestone is true — including when flipping it true with a PATCH. Must be at least 2 days after start; use a task with a due date for single-day work. Forced to null when isMilestone is false.
orderSort order within the project timeline. Server-defaulted to MAX(order)+100 when omitted on create.
color^#([0-9A-Fa-f]{3}|[0…Hex color, #RGB or #RRGGBB. Stored lowercase and expanded to 6 digits, so #0A9 reads back as #00aa99. Omitted on create → the server assigns a random palette color, so a list always has one.
archivedWhether this list is archived (hidden from the active timeline but preserved). Regular field, NOT a soft-delete.
isMilestonefalse (the default) = a flat list of tasks. true = a date-spanning milestone shown on the roadmap; it requires start and end at least 2 days apart.
dependencyIdId of the list that must finish before this one starts (timeline dependency). The target must belong to the same project, otherwise the request is rejected with 400.
assigneesTeam members assigned to this list. Replaces the whole set on update; use POST/DELETE /lists/{id}/assignees for a single add/remove.
hiddenForRoles this list is hidden from. Replaces the whole set on update; use POST /lists/{id}/hidden-for and POST /lists/{id}/hidden-for/remove for a single add/remove. Every id must be a role in the same workspace.
goalsGoals this list contributes toward. Replaces the whole set on update; use POST/DELETE /lists/{id}/goals for a single add/remove.
Set custom-field values on this list. Each entry is { customFieldId, value } and value is always a string — send "" to clear one. Max 50 entries per request. Read them back with ?expand=customFields.
expectedUpdatedAtOptional concurrency guard: the updatedAt you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh updatedAt.
Update List › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
projectIdProject this list belongs to (scope). Immutable after creation.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
archivedWhether this list is archived (hidden from the active timeline but preserved). Regular field, NOT a soft-delete.
nameList name. Trimmed; obvious spam is rejected with 400. Null only on lists created before this API existed.
descriptionList description
startStart date (ISO 8601). Required together with end whenever isMilestone is true — including when flipping it true with a PATCH. end must be at least 2 days after start; use a task with a due date for single-day work. Forced to null when isMilestone is false.
endEnd date (ISO 8601). Required together with start whenever isMilestone is true — including when flipping it true with a PATCH. Must be at least 2 days after start; use a task with a due date for single-day work. Forced to null when isMilestone is false.
orderSort order within the project timeline. Server-defaulted to MAX(order)+100 when omitted on create.
colorHex color, #RGB or #RRGGBB. Stored lowercase and expanded to 6 digits, so #0A9 reads back as #00aa99. Omitted on create → the server assigns a random palette color, so a list always has one.
isMilestonefalse (the default) = a flat list of tasks. true = a date-spanning milestone shown on the roadmap; it requires start and end at least 2 days apart.
dependencyIdId of the list that must finish before this one starts (timeline dependency). The target must belong to the same project, otherwise the request is rejected with 400.
statusIdWhen set, this list also appears as a column on the project board, backed by the given status. Cannot be changed after creation.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
The related Project, present only when you pass ?expand=project.
The related List, present only when you pass ?expand=dependency.
The related Recurring Rule, present only when you pass ?expand=recurringRule.
The related Status, present only when you pass ?expand=status.
The linked Team Member rows, present only when you pass ?expand=assignees.
The linked Role rows, present only when you pass ?expand=hiddenFor.
The linked Goal rows, present only when you pass ?expand=goals.
The linked attachedCustomField rows, present only when you pass ?expand=customFields.
The linked Task rows, present only when you pass ?expand=tasks.
Search Lists
Full-text ranked search across lists. Ranked by relevance; pages are capped at 200 results. Filterable by 11 fields.
Required scope: lists:read
query Parameters
qFull-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.
projectIdThe project to search within. Required — lists are project-scoped and search has no workspace-wide mode.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
archived[eq]Filter where archived equals.
isMilestone[eq]Filter where isMilestone equals.
projectId[eq]Filter where projectId equals.
projectId[in]Filter where projectId is one of (comma-separated list).
dependencyId[eq]Filter where dependencyId equals.
dependencyId[in]Filter where dependencyId is one of (comma-separated list).
statusId[eq]Filter where statusId equals.
statusId[in]Filter where statusId is one of (comma-separated list).
ruleId[eq]Filter where ruleId equals.
ruleId[in]Filter where ruleId is one of (comma-separated list).
start[gt]Filter where start is greater than.
start[gte]Filter where start is greater than or equal to.
start[lt]Filter where start is less than.
start[lte]Filter where start is less than or equal to.
end[gt]Filter where end is greater than.
end[gte]Filter where end is greater than or equal to.
end[lt]Filter where end is less than.
end[lte]Filter where end is less than or equal to.
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
updatedAt[gt]Filter where updatedAt is greater than.
updatedAt[gte]Filter where updatedAt is greater than or equal to.
updatedAt[lt]Filter where updatedAt is less than.
updatedAt[lte]Filter where updatedAt is less than or equal to.
Search Lists › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Add assignees to a List
Link the given ids to this List as assignees. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete assignees set afterwards.
Required scopes: lists:write lists:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the List.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Add assignees to a List › Responses
OK
The complete assignees set after the change.
affectedIdsThe ids that were actually linked (ones already linked are omitted).
missingIdsIds you sent that do not exist or are not visible to this token.
Remove assignees from a List
Unlink the given ids from this List's assignees. Removing one that is not linked changes nothing. Returns the complete assignees set afterwards.
Required scopes: lists:write lists:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the List.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Remove assignees from a List › Request Body
idsTeam Members to add or remove, by id.
Remove assignees from a List › Responses
OK
The complete assignees set after the change.
affectedIdsThe ids that were actually unlinked (ones not linked are omitted).
Add hidden for to a List
Link the given ids to this List as hiddenFor. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete hiddenFor set afterwards.
Required scopes: lists:write lists:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the List.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Add hidden for to a List › Responses
OK
The complete hiddenFor set after the change.
affectedIdsThe ids that were actually linked (ones already linked are omitted).
missingIdsIds you sent that do not exist or are not visible to this token.
Remove hidden for from a List
Unlink the given ids from this List's hiddenFor. Removing one that is not linked changes nothing. Returns the complete hiddenFor set afterwards.
Required scopes: lists:write lists:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the List.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Remove hidden for from a List › Responses
OK
The complete hiddenFor set after the change.
affectedIdsThe ids that were actually unlinked (ones not linked are omitted).
Add goals to a List
Link the given ids to this List as goals. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete goals set afterwards.
Required scopes: lists:write lists:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the List.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Add goals to a List › Responses
OK
The complete goals set after the change.
affectedIdsThe ids that were actually linked (ones already linked are omitted).
missingIdsIds you sent that do not exist or are not visible to this token.
Remove goals from a List
Unlink the given ids from this List's goals. Removing one that is not linked changes nothing. Returns the complete goals set afterwards.
Required scopes: lists:write lists:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the List.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Remove goals from a List › Responses
OK
The complete goals set after the change.
affectedIdsThe ids that were actually unlinked (ones not linked are omitted).