Tasks

Find sprint work, edit tasks and attach pull requests with workspace-scoped API access. Request tasks:read for reads and tasks:write for mutations.

8 endpoints

GET

Find pending tasks

GET /external/v1/tasks

Find tasks owned by one team, including tasks inherited from its Initiatives. status defaults to pending, which means every status except done. sprintId=current selects the explicitly active sprint; when none is active the result is empty. Omitting sprintId includes backlog and other sprints. Results sort by executionPosition and then UUID. List responses are arrays with X-Total-Count, X-Limit, X-Offset and X-Has-More headers. Continue until X-Has-More is false; concurrent edits can shift offset pages.

Requirements

API scopes required:

tasks:read

Request

Parameters

Name	Type	Description
teamId *	uuid	Required query parameter. Resolve it with GET /external/v1/teams (initiatives:read).
limit	integer	Page size, 1–100. Default 20.
offset	integer	Matching rows to skip. Default 0.
sprintId	uuid \| current	Filter to a sprint, or use current.
status	enum	pending (default), all, or triage, ready, in_progress, in_review, blocked, done.
ownerUserId	uuid	Filter by owner.
projectId	uuid	Filter by Initiative.
sourceIdeaId	uuid	Filter by linked Idea.
q	string	Literal search in task title and description; up to 200 characters.

Responses

200

Success

The requested data is returned.

400

Invalid request

Invalid ID, unsupported field, empty patch, or invalid value.

403

Missing scope

The key does not grant the required resource scope.

404

Not found

The addressed record or assignment is outside this workspace or team.

Example Response

200 OK

json

[
  {
    "id": "22222222-2222-4222-8222-222222222222",
    "summary": "Fix duplicate exports",
    "executionStatus": "in_review",
    "sourceIdeaId": null,
    "sourceEvidenceId": "33333333-3333-4333-8333-333333333333",
    "sprintId": null,
    "ownerUserId": null
  }
]

GET

Get task context

GET /external/v1/tasks/:id

Read task instructions, dependencies, owner, sprint, sourceIdeaId and sourceEvidenceId. readOnly identifies completed-sprint tasks; sourceManaged identifies provider-owned tasks. Follow sourceIdeaId with the Ideas API, sourceEvidenceId with the Signal evidence API, and list PR attachments separately. The response includes safe provider metadata and linked user-story context.

Requirements

API scopes required:

tasks:read

Request

Parameters

Name	Type	Description
id *	uuid	Record UUID in the path.
teamId *	uuid	Required query parameter. Resolve it with GET /external/v1/teams (initiatives:read).

Responses

200

Success

The requested data is returned.

400

Invalid request

Invalid ID, unsupported field, empty patch, or invalid value.

403

Missing scope

The key does not grant the required resource scope.

404

Not found

The addressed record or assignment is outside this workspace or team.

Example Response

200 OK

json

{
  "id": "22222222-2222-4222-8222-222222222222",
  "summary": "Fix duplicate exports",
  "executionStatus": "in_review",
  "sourceIdeaId": null,
  "sourceEvidenceId": "33333333-3333-4333-8333-333333333333",
  "sprintId": null,
  "ownerUserId": null,
  "description": "Make retries reuse the export.",
  "dependencies": [],
  "readOnly": false,
  "sourceManaged": false
}

POST

Create a task

POST /external/v1/tasks

Create a native team task. Omitted values use ready status, medium priority and the planned lane. sourceIdeaId can link product context without requiring an Initiative. Reuse clientRequestId after a timeout; use a new UUID for a different task.

Requirements

API scopes required:

tasks:write

Request

Parameters

Name	Type	Description
teamId *	uuid	Required query parameter. Resolve it with GET /external/v1/teams (initiatives:read).

Request body (application/json)

summarystring

Required

Task title, 3–500 characters after trimming.

descriptionstring

Task instructions, up to 12,000 characters.

rolestring

Delivery role, up to 120 characters.

kindenum

task, bug, request, or design.

executionStatusenum

triage, ready, in_progress, in_review, blocked, done.

executionPriorityenum

urgent, high, medium, or low.

executionLaneenum

planned or fast.

projectIduuid | null

Initiative in this team; null makes the task standalone.

sprintIduuid | null

Non-completed sprint in this team; null removes sprint assignment.

ownerUserIduuid | null

Workspace user who belongs to this team; null clears ownership.

sourceIdeaIduuid

Optional source Idea in this workspace.

triageNotestring | null

Up to 4,000 characters; null clears the note.

clientRequestIduuid

Required

Required stable UUID for this creation attempt. Reuse on retries to avoid duplicate tasks.

Responses

201

Success

The saved record is returned.

400

Invalid request

Invalid ID, unsupported field, empty patch, or invalid value.

403

Missing scope

The key does not grant the required resource scope.

404

Not found

The addressed record or assignment is outside this workspace or team.

409

Conflict

The observed status changed, the sprint is completed, or a source-managed field must be edited in Linear.

Example Request

POST

/external/v1/tasks

json

{
  "summary": "Fix duplicate exports",
  "clientRequestId": "22222222-2222-4222-8222-222222222222",
  "sourceIdeaId": "33333333-3333-4333-8333-333333333333"
}

Example Response

201 Created

json

{
  "id": "22222222-2222-4222-8222-222222222222",
  "summary": "Fix duplicate exports",
  "executionStatus": "in_review",
  "sourceIdeaId": null,
  "sourceEvidenceId": "33333333-3333-4333-8333-333333333333",
  "sprintId": null,
  "ownerUserId": null
}

PATCH

Update a task

PATCH /external/v1/tasks/:id

Send at least one supported field. Omitted fields remain unchanged; nullable fields can be cleared. Arrays replace the full saved relation. Completed-sprint tasks are read-only. Linear-owned source fields (title, instructions, effort, kind, status, priority, lane, sprint, owner and dependencies) must be edited in Linear. Updating a task never changes an Idea status or evidence resolution.

Requirements

API scopes required:

tasks:write

Request

Parameters

Name	Type	Description
id *	uuid	Record UUID in the path.
teamId *	uuid	Required query parameter. Resolve it with GET /external/v1/teams (initiatives:read).

Request body (application/json)

summarystring

Task title, 3–500 characters after trimming.

descriptionstring

Task instructions, up to 12,000 characters.

rolestring

Delivery role, up to 120 characters.

kindenum

task, bug, request, or design.

executionStatusenum

triage, ready, in_progress, in_review, blocked, done.

executionPriorityenum

urgent, high, medium, or low.

executionLaneenum

planned or fast.

projectIduuid | null

Initiative in this team; null makes the task standalone.

sprintIduuid | null

Non-completed sprint in this team; null removes sprint assignment.

ownerUserIduuid | null

Workspace user who belongs to this team; null clears ownership.

sourceIdeaIduuid | null

Source Idea in this workspace; null clears the link.

triageNotestring | null

Up to 4,000 characters; null clears the note.

storyPointsinteger | null

Effort from 0 to 1,000; null clears the estimate.

dependenciesuuid[]

Complete dependency task list, up to 100 unique IDs accessible in this team.

userStoryIdsuuid[]

Complete user-story list, up to 100 unique IDs in this team.

expectedCurrentStatusenum

Optional observed task status; a mismatch returns 409. triage, ready, in_progress, in_review, blocked, done.

Responses

200

Success

The saved record is returned.

400

Invalid request

Invalid ID, unsupported field, empty patch, or invalid value.

403

Missing scope

The key does not grant the required resource scope.

404

Not found

The addressed record or assignment is outside this workspace or team.

409

Conflict

The observed status changed, the sprint is completed, or a source-managed field must be edited in Linear.

Example Request

PATCH

/external/v1/tasks/:id

json

{
  "description": "Reuse the existing export on retry.",
  "expectedCurrentStatus": "ready"
}

Example Response

200 OK

json

{
  "id": "22222222-2222-4222-8222-222222222222",
  "summary": "Fix duplicate exports",
  "executionStatus": "in_review",
  "sourceIdeaId": null,
  "sourceEvidenceId": "33333333-3333-4333-8333-333333333333",
  "sprintId": null,
  "ownerUserId": null
}

PATCH

Change task status

PATCH /external/v1/tasks/:id/status

Set one task status. expectedCurrentStatus rejects a stale update. A done task does not automatically ship its Idea or resolve supporting evidence.

Requirements

API scopes required:

tasks:write

Request

Parameters

Name	Type	Description
id *	uuid	Record UUID in the path.
teamId *	uuid	Required query parameter. Resolve it with GET /external/v1/teams (initiatives:read).

Request body (application/json)

statusenum

Required

triage, ready, in_progress, in_review, blocked, done.

expectedCurrentStatusenum

Previously observed status; mismatch returns 409.

Responses

200

Success

The saved record is returned.

400

Invalid request

Invalid ID, unsupported field, empty patch, or invalid value.

403

Missing scope

The key does not grant the required resource scope.

404

Not found

The addressed record or assignment is outside this workspace or team.

409

Conflict

The observed status changed, the sprint is completed, or a source-managed field must be edited in Linear.

Example Request

PATCH

/external/v1/tasks/:id/status

json

{
  "status": "in_review",
  "expectedCurrentStatus": "in_progress"
}

Example Response

200 OK

json

{
  "id": "22222222-2222-4222-8222-222222222222",
  "summary": "Fix duplicate exports",
  "executionStatus": "in_review",
  "sourceIdeaId": null,
  "sourceEvidenceId": "33333333-3333-4333-8333-333333333333",
  "sprintId": null,
  "ownerUserId": null
}

GET

List task PR attachments

GET /external/v1/tasks/:id/pull-requests

Read task attachments and stored GitHub status from the same workspace when available. Missing synced fields are null. No provider request is made; mergedAt is not proof of production shipment. List responses are arrays with X-Total-Count, X-Limit, X-Offset and X-Has-More headers. Continue until X-Has-More is false; concurrent edits can shift offset pages.

Requirements

API scopes required:

tasks:read

Request

Parameters

Name	Type	Description
id *	uuid	Record UUID in the path.
teamId *	uuid	Required query parameter. Resolve it with GET /external/v1/teams (initiatives:read).
limit	integer	Page size, 1–100. Default 20.
offset	integer	Matching rows to skip. Default 0.

Responses

200

Success

The requested data is returned.

400

Invalid request

Invalid ID, unsupported field, empty patch, or invalid value.

403

Missing scope

The key does not grant the required resource scope.

404

Not found

The addressed record or assignment is outside this workspace or team.

Example Response

200 OK

json

[
  {
    "id": "33333333-3333-4333-8333-333333333333",
    "url": "https://github.com/example/app/pull/42",
    "repositoryFullName": "example/app",
    "number": 42,
    "pullRequestId": null,
    "title": null,
    "state": null,
    "checksState": null,
    "mergedAt": null,
    "lastSyncedAt": null
  }
]

POST

Attach a PR to a task

POST /external/v1/tasks/:id/pull-requests

Attach an HTTPS github.com pull request URL, including before the integration has synced it. The URL is recorded without fetching or verifying it. Repository and PR number determine identity; retrying returns the existing attachment. This does not create an Idea/Initiative delivery link, publish a PR, or change any status. Use the existing Zentrik trailer contract separately for product delivery links.

Requirements

API scopes required:

tasks:write

Request

Parameters

Name	Type	Description
id *	uuid	Record UUID in the path.
teamId *	uuid	Required query parameter. Resolve it with GET /external/v1/teams (initiatives:read).

Request body (application/json)

urlurl

Required

https://github.com/owner/repository/pull/number. Query and fragment are removed; repository case is normalized. GitHub Enterprise hosts are not supported.

Responses

201

Success

The saved record is returned.

400

Invalid request

Invalid ID, unsupported field, empty patch, or invalid value.

403

Missing scope

The key does not grant the required resource scope.

404

Not found

The addressed record or assignment is outside this workspace or team.

409

Conflict

The observed status changed, the sprint is completed, or a source-managed field must be edited in Linear.

Example Request

POST

/external/v1/tasks/:id/pull-requests

json

{
  "url": "https://github.com/example/app/pull/42"
}

Example Response

201 Created

json

{
  "id": "33333333-3333-4333-8333-333333333333",
  "workspaceId": "33333333-3333-4333-8333-333333333333",
  "taskId": "22222222-2222-4222-8222-222222222222",
  "repositoryFullName": "example/app",
  "number": 42,
  "url": "https://github.com/example/app/pull/42",
  "createdAt": "2026-09-10T10:00:00Z",
  "updatedAt": "2026-09-10T10:00:00Z"
}

DELETE

Detach a task PR

DELETE /external/v1/tasks/:id/pull-requests/:linkId

Remove only this task attachment. Repeated removal returns changed:false. The PR and Idea/Initiative delivery links remain available. Completed-sprint tasks are read-only.

Requirements

API scopes required:

tasks:write

Request

Parameters

Name	Type	Description
id *	uuid	Record UUID in the path.
teamId *	uuid	Required query parameter. Resolve it with GET /external/v1/teams (initiatives:read).
linkId *	uuid	Attachment ID returned by attach/list, not the GitHub PR ID.

Responses

200

Success

The saved record is returned.

400

Invalid request

Invalid ID, unsupported field, empty patch, or invalid value.

403

Missing scope

The key does not grant the required resource scope.

404

Not found

The addressed record or assignment is outside this workspace or team.

409

Conflict

The observed status changed, the sprint is completed, or a source-managed field must be edited in Linear.

Example Response

200 OK

json

{
  "id": "22222222-2222-4222-8222-222222222222",
  "linkId": "33333333-3333-4333-8333-333333333333",
  "changed": true
}