A team objective with tracked progress. progressCompleted, progressTotal and (for targetType: dynamic) targetValue are computed from the goal task set — send them and they are overwritten. A create needs at least name and endAt. A goal completes itself: completedAt is stamped when its tracked progress reaches its target and cleared when it falls back below. members, tasks and lists are honoured on create and ignored on update.
List Goals
List goals. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 6 fields. Ordered by createdAt unless you pass sort.
Required scope: goals:read
query Parameters
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: createdAt.
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.
accessType[eq]Filter where accessType equals.
accessType[in]Filter where accessType is one of (comma-separated list).
goalGroupId[eq]Filter where goalGroupId equals.
goalGroupId[in]Filter where goalGroupId is one of (comma-separated list).
ownerId[eq]Filter where ownerId equals.
ownerId[in]Filter where ownerId is one of (comma-separated list).
endAt[eq]Filter where endAt equals.
endAt[gt]Filter where endAt is greater than.
endAt[gte]Filter where endAt is greater than or equal to.
endAt[lt]Filter where endAt is less than.
endAt[lte]Filter where endAt 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.
List Goals › 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 Goal
Create a Goal. Server-assigned fields are ignored if sent. Requires a human-backed identity — a user session or a personal access token. Application and agent tokens receive 403 here; they can read goals but not change them.
Required scope: goals: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 Goal › Request Body
nameGoal name
endAtTarget completion date (ISO 8601). Required on create; a goal always has a date it is aiming at.
descriptionOptional longer description
accessTypeWho can see this goal: public (the whole team), limited (the team members listed in members), private (the owner only).
goalGroupIdGoal group this goal is filed under (nullable — ON DELETE SET NULL). Writable: an id files the goal under that group; explicit null unlinks; omitted leaves it unchanged.
membersTeam members this goal is shared with (this is who accessType: limited means). Set when the goal is created; ignored on update. Read them back with ?expand=members.
goalSourceTypeWhat feeds the goal's task set: customField, manual, label, assigneeLabel, assignee.
goalSourceValueThe id goalSourceType points at: for label a label id; for customField a custom-field id; for assignee and assigneeLabel a team-member id. Not used when goalSourceType is manual (send the task ids in tasks instead).
goalSourceOptionNarrows goalSourceValue when goalSourceType is custom_field: the id of the dropdown option to match. Ignored for every other source type.
tasksTasks linked to this goal, for goals whose goalSourceType is manual. Set when the goal is created; ignored on update. Read them back with ?expand=tasks.
listsLists whose tasks feed this goal. Set when the goal is created; ignored on update. Read them back with ?expand=lists.
trackMetricTypeHow progress is measured: taskCount, trackedTime, customFieldValue, storyPoints.
trackMetricValueThe id trackMetricType points at — for custom_field_value, the custom-field id whose values are summed. Not used by the other metric types.
targetTypeTarget mode: dynamic (the target tracks the live total of the goal task set) or static (a fixed targetValue).
targetValueThe fixed numeric target. Used only when targetType is static; when targetType is dynamic it is recomputed by the server from the goal task set and anything you send is overwritten.
ownerIdThe team member who owns this goal — for a private goal, the only member who can see it. Defaults to the caller on create; send another team member id to hand it over.
Create Goal › Responses
Created
idUnique identifier for this resource.
createdAtCreation timestamp.
nameGoal name
accessTypeWho can see this goal: public (the whole team), limited (the team members listed in members), private (the owner only).
goalSourceTypeWhat feeds the goal's task set: customField, manual, label, assigneeLabel, assignee.
trackMetricTypeHow progress is measured: taskCount, trackedTime, customFieldValue, storyPoints.
targetTypeTarget mode: dynamic (the target tracks the live total of the goal task set) or static (a fixed targetValue).
targetValueThe fixed numeric target. Used only when targetType is static; when targetType is dynamic it is recomputed by the server from the goal task set and anything you send is overwritten.
progressTotalPersisted denominator of the progress rollup (float).
progressCompletedPersisted numerator of the progress rollup (float).
endAtTarget completion date (ISO 8601). Required on create; a goal always has a date it is aiming at.
teamIdThe workspace (team) this goal belongs to.
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.
descriptionOptional longer description
goalSourceValueThe id goalSourceType points at: for label a label id; for customField a custom-field id; for assignee and assigneeLabel a team-member id. Not used when goalSourceType is manual (send the task ids in tasks instead).
goalSourceOptionNarrows goalSourceValue when goalSourceType is custom_field: the id of the dropdown option to match. Ignored for every other source type.
trackMetricValueThe id trackMetricType points at — for custom_field_value, the custom-field id whose values are summed. Not used by the other metric types.
completedAtWhen this goal was completed, or null while it is open. Entirely server-derived: it is stamped the moment progressCompleted reaches progressTotal and cleared again if progress falls back below. There is no manual complete or reopen — finish the tracked work, or lower a static targetValue.
ownerIdThe team member who owns this goal — for a private goal, the only member who can see it. Defaults to the caller on create; send another team member id to hand it over.
goalGroupIdGoal group this goal is filed under (nullable — ON DELETE SET NULL). Writable: an id files the goal under that group; explicit null unlinks; omitted leaves it unchanged.
The related Team Member, present only when you pass ?expand=owner.
The related Goal Group, present only when you pass ?expand=goalGroup.
The linked Team Member rows, present only when you pass ?expand=members.
The linked Task rows, present only when you pass ?expand=tasks.
The linked List rows, present only when you pass ?expand=lists.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Get Goal
Retrieve a single Goal by id.
Required scope: goals:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Goal.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Goal › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
nameGoal name
accessTypeWho can see this goal: public (the whole team), limited (the team members listed in members), private (the owner only).
goalSourceTypeWhat feeds the goal's task set: customField, manual, label, assigneeLabel, assignee.
trackMetricTypeHow progress is measured: taskCount, trackedTime, customFieldValue, storyPoints.
targetTypeTarget mode: dynamic (the target tracks the live total of the goal task set) or static (a fixed targetValue).
targetValueThe fixed numeric target. Used only when targetType is static; when targetType is dynamic it is recomputed by the server from the goal task set and anything you send is overwritten.
progressTotalPersisted denominator of the progress rollup (float).
progressCompletedPersisted numerator of the progress rollup (float).
endAtTarget completion date (ISO 8601). Required on create; a goal always has a date it is aiming at.
teamIdThe workspace (team) this goal belongs to.
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.
descriptionOptional longer description
goalSourceValueThe id goalSourceType points at: for label a label id; for customField a custom-field id; for assignee and assigneeLabel a team-member id. Not used when goalSourceType is manual (send the task ids in tasks instead).
goalSourceOptionNarrows goalSourceValue when goalSourceType is custom_field: the id of the dropdown option to match. Ignored for every other source type.
trackMetricValueThe id trackMetricType points at — for custom_field_value, the custom-field id whose values are summed. Not used by the other metric types.
completedAtWhen this goal was completed, or null while it is open. Entirely server-derived: it is stamped the moment progressCompleted reaches progressTotal and cleared again if progress falls back below. There is no manual complete or reopen — finish the tracked work, or lower a static targetValue.
ownerIdThe team member who owns this goal — for a private goal, the only member who can see it. Defaults to the caller on create; send another team member id to hand it over.
goalGroupIdGoal group this goal is filed under (nullable — ON DELETE SET NULL). Writable: an id files the goal under that group; explicit null unlinks; omitted leaves it unchanged.
The related Team Member, present only when you pass ?expand=owner.
The related Goal Group, present only when you pass ?expand=goalGroup.
The linked Team Member rows, present only when you pass ?expand=members.
The linked Task rows, present only when you pass ?expand=tasks.
The linked List rows, present only when you pass ?expand=lists.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Delete Goal
Permanently delete this Goal. This cannot be undone. Requires a human-backed identity — a user session or a personal access token. Application and agent tokens receive 403 here; they can read goals but not change them.
Required scope: goals:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Goal.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Goal › Responses
No Content
Update Goal
Partially update a Goal. Only the fields you send are changed. Requires a human-backed identity — a user session or a personal access token. Application and agent tokens receive 403 here; they can read goals but not change them.
Required scope: goals:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Goal.
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 Goal › Request Body
nameGoal name
descriptionOptional longer description
accessTypeWho can see this goal: public (the whole team), limited (the team members listed in members), private (the owner only).
endAtTarget completion date (ISO 8601). Required on create; a goal always has a date it is aiming at.
goalGroupIdGoal group this goal is filed under (nullable — ON DELETE SET NULL). Writable: an id files the goal under that group; explicit null unlinks; omitted leaves it unchanged.
goalSourceTypeWhat feeds the goal's task set: customField, manual, label, assigneeLabel, assignee.
goalSourceValueThe id goalSourceType points at: for label a label id; for customField a custom-field id; for assignee and assigneeLabel a team-member id. Not used when goalSourceType is manual (send the task ids in tasks instead).
goalSourceOptionNarrows goalSourceValue when goalSourceType is custom_field: the id of the dropdown option to match. Ignored for every other source type.
trackMetricTypeHow progress is measured: taskCount, trackedTime, customFieldValue, storyPoints.
trackMetricValueThe id trackMetricType points at — for custom_field_value, the custom-field id whose values are summed. Not used by the other metric types.
targetTypeTarget mode: dynamic (the target tracks the live total of the goal task set) or static (a fixed targetValue).
targetValueThe fixed numeric target. Used only when targetType is static; when targetType is dynamic it is recomputed by the server from the goal task set and anything you send is overwritten.
ownerIdThe team member who owns this goal — for a private goal, the only member who can see it. Defaults to the caller on create; send another team member id to hand it over.
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 Goal › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
nameGoal name
accessTypeWho can see this goal: public (the whole team), limited (the team members listed in members), private (the owner only).
goalSourceTypeWhat feeds the goal's task set: customField, manual, label, assigneeLabel, assignee.
trackMetricTypeHow progress is measured: taskCount, trackedTime, customFieldValue, storyPoints.
targetTypeTarget mode: dynamic (the target tracks the live total of the goal task set) or static (a fixed targetValue).
targetValueThe fixed numeric target. Used only when targetType is static; when targetType is dynamic it is recomputed by the server from the goal task set and anything you send is overwritten.
progressTotalPersisted denominator of the progress rollup (float).
progressCompletedPersisted numerator of the progress rollup (float).
endAtTarget completion date (ISO 8601). Required on create; a goal always has a date it is aiming at.
teamIdThe workspace (team) this goal belongs to.
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.
descriptionOptional longer description
goalSourceValueThe id goalSourceType points at: for label a label id; for customField a custom-field id; for assignee and assigneeLabel a team-member id. Not used when goalSourceType is manual (send the task ids in tasks instead).
goalSourceOptionNarrows goalSourceValue when goalSourceType is custom_field: the id of the dropdown option to match. Ignored for every other source type.
trackMetricValueThe id trackMetricType points at — for custom_field_value, the custom-field id whose values are summed. Not used by the other metric types.
completedAtWhen this goal was completed, or null while it is open. Entirely server-derived: it is stamped the moment progressCompleted reaches progressTotal and cleared again if progress falls back below. There is no manual complete or reopen — finish the tracked work, or lower a static targetValue.
ownerIdThe team member who owns this goal — for a private goal, the only member who can see it. Defaults to the caller on create; send another team member id to hand it over.
goalGroupIdGoal group this goal is filed under (nullable — ON DELETE SET NULL). Writable: an id files the goal under that group; explicit null unlinks; omitted leaves it unchanged.
The related Team Member, present only when you pass ?expand=owner.
The related Goal Group, present only when you pass ?expand=goalGroup.
The linked Team Member rows, present only when you pass ?expand=members.
The linked Task rows, present only when you pass ?expand=tasks.
The linked List rows, present only when you pass ?expand=lists.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Search Goals
Full-text ranked search across goals. Ranked by relevance; pages are capped at 200 results. Filterable by 6 fields.
Required scope: goals:read
query Parameters
qFull-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.
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.
accessType[eq]Filter where accessType equals.
accessType[in]Filter where accessType is one of (comma-separated list).
goalGroupId[eq]Filter where goalGroupId equals.
goalGroupId[in]Filter where goalGroupId is one of (comma-separated list).
ownerId[eq]Filter where ownerId equals.
ownerId[in]Filter where ownerId is one of (comma-separated list).
endAt[eq]Filter where endAt equals.
endAt[gt]Filter where endAt is greater than.
endAt[gte]Filter where endAt is greater than or equal to.
endAt[lt]Filter where endAt is less than.
endAt[lte]Filter where endAt 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.
Search Goals › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.