Issues

Issues are the core of the Backlog API. Reading needs issues:read, everything that changes something needs issues:write. Every request also runs the same policies as the web app: a private team you are not in is invisible (404 in lists, 403 on a direct id), and writing needs permission to contribute to the issue's team.

Writes go through the same actions as the web app, so numbers are claimed atomically, descriptions and comments are sanitised, notifications and webhooks fire, and boards update live.

The issue object#

{
  "id": 981,
  "identifier": "ENG-12",
  "number": 12,
  "team_id": 3,
  "title": "Login times out",
  "description": "<p>…</p>",
  "state": { "id": 21, "team_id": 3, "name": "In Progress", "type": "started", "color": "#f59e0b", "progress": 0.5, "position": 2 },
  "priority": 2,
  "priority_name": "High",
  "estimate": 3,
  "budget_minutes": null,
  "assignees": [{ "id": 1, "name": "Sanne", "email": "sanne@example.com", "isBot": false }],
  "reviewers": [],
  "creator": { "id": 2, "name": "Daan", "email": "daan@example.com", "isBot": false },
  "project_id": null,
  "milestone_id": null,
  "cycle_id": null,
  "parent_id": null,
  "labels": [{ "id": 12, "name": "bug", "color": "#ef4444", "team_id": null, "group_id": null, "is_group": false }],
  "customers": [],
  "due_at": "2026-09-01",
  "scheduled_days": ["2026-08-28"],
  "scheduled_times": {},
  "scheduled_for": "2026-08-28",
  "started_at": "2026-08-20T09:00:00+00:00",
  "completed_at": null,
  "canceled_at": null,
  "state_changed_at": "2026-08-20T09:00:00+00:00",
  "archived_at": null,
  "sla": { "targets": null, "due_at": null, "at_risk_at": null, "breached_at": null },
  "is_favorite": false,
  "triage_status": null,
  "created_at": "2026-08-19T14:00:00+00:00",
  "updated_at": "2026-08-20T09:00:00+00:00"
}

customers is only included by the single-issue, create and update responses; identifier, state and the other relation fields are only present where the relation was loaded, which is always the case for the endpoints below.

Note: identifier is for reading and for the ?identifier= filter. The routes /api/v1/issues/{issue} take the numeric id. To go from ENG-12 to an id, call the list with ?identifier=ENG-12.

List issues#

The issues in the workspace you may see, archived ones excluded. Every filter is optional and only narrows the set.

A filter value of the wrong type (for example state_type=done) is a 422.

Without q the list is ordered by updated_at (oldest first), then id, which makes updated_since polling stable: ask for what moved since your last run and page through that window without rows shifting.

Warning: URL-encode updated_since. An ISO 8601 stamp ends in +00:00, and a bare + in a query string decodes to a space, so the value arrives as 2026-08-18T12:00:00 00:00.

Searching#

q is the same search the command palette uses: titles, descriptions and comments, ranked, with an exact identifier (ENG-12) first.

• It is prefix-based. Every typed word is matched as a prefix, and nothing is stemmed: authent finds Authentication rewrite, running does not find run.
• It composes with the other filters: ?q=login&team=ENG searches inside that team.
• It claims the ordering. With q, results come back by relevance, not by updated_at.
• A term with nothing searchable in it (?q=...) matches nothing.

curl "https://backlog.polder.work/api/v1/workspaces/7/issues?team=ENG&state_type=started&per_page=20" \
  -H "Authorization: Bearer $POLDER_TOKEN"

{
  "data": [ { "id": 981, "identifier": "ENG-12", "title": "Login times out", … } ],
  "meta": { "page": 1, "per_page": 20, "total": 1, "last_page": 1 }
}

The list items omit customers. Each one carries is_favorite.

Create an issue#

Creates an issue and answers 201 with the issue object. The team is named in the body, by key, because it is a choice the caller makes per request. Creating needs permission to contribute to that team (403).

Side effects: the next number in the team is claimed, the creator is you, the assignees and reviewers are notified, mentions in the description notify the people mentioned, and the team's automations and workflows run. If the team has a default reviewer and you do not send reviewer_ids, that reviewer is added.

Body

Ids that do not exist, or belong to another team, are a 422. Ids of a project, label, assignee or reviewer that exist but do not belong in this team or workspace are silently left out rather than refused. scheduled_days and scheduled_for are not accepted on create; set them with a PATCH.

curl https://backlog.polder.work/api/v1/workspaces/7/issues \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"team": "ENG", "title": "Login times out", "priority": 2, "assignee_ids": [1]}'

{ "data": { "id": 981, "identifier": "ENG-12", "title": "Login times out", … } }

The MCP equivalent is polder_create_issue.

Read an issue#

One issue by numeric id, including customers and is_favorite. 403 if you may not see its team.

curl https://backlog.polder.work/api/v1/issues/981 \
  -H "Authorization: Bearer $POLDER_TOKEN"

Change an issue#

Changes only the fields you send. Omitted fields are left alone, which is what stops two integrations from overwriting each other. Send null to clear a nullable field. Answers 200 with the new issue.

To move an issue, send a workflow_state_id from the issue's team. Timestamps such as started_at and completed_at follow the state's type.

Body (all optional)

position is not accepted on update.

curl -X PATCH https://backlog.polder.work/api/v1/issues/981 \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workflow_state_id": 22, "assignee_ids": [1, 4]}'

Failing validation is a 422 with the field names under errors.

Archive an issue#

The reversible way to get rid of an issue. No body. Answers 200 with the issue, with archived_at set. Archived issues no longer appear in the list. It needs the same permission as a PATCH. A PATCH cannot archive: use this.

Delete an issue#

Permanently deletes the issue and answers 204. Open boards drop the row live. Prefer archiving.

List comments#

The comments on an issue, oldest first, paged.

{
  "data": [
    {
      "id": 77, "issue_id": 981, "parent_id": null, "body": "<p>On it.</p>",
      "author": { "id": 1, "name": "Sanne", "email": "sanne@example.com", "isBot": false },
      "edited_at": null,
      "created_at": "2026-08-20T09:05:00+00:00"
    }
  ],
  "meta": { … }
}

Comments are flat in this API: a reply carries the parent_id of the thread's first comment.

Post a comment#

Posts a comment as the token's owner and answers 201 with it. Needs permission to contribute to the issue's team. Side effects: the issue's subscribers are notified, people mentioned are notified, and on an issue that came in by email a public comment may be sent back to the sender.

Body

curl https://backlog.polder.work/api/v1/issues/981/comments \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "<p>Fixed in the next release.</p>"}'

Comments posted through the API are internal, never public.

Delete a comment#

Deletes a comment and answers 204. Only its author may do this (403 for anyone else), as in the web app. There is no endpoint to edit a comment.

List relations#

How the issue hangs together with other issues, from this issue's point of view. Not paged, and the envelope has no meta.

{
  "data": [
    { "type": "blocks", "issue_id": 982, "identifier": "ENG-13", "title": "Ship the release" },
    { "type": "blocked_by", "issue_id": 970, "identifier": "ENG-4", "title": "Rotate the keys" }
  ]
}

The list includes relations you have no right to see the other side of: the identifier and title come back for every related issue.

Add a relation#

Links two issues and answers 204. Needs permission to change {issue} and to see the other issue.

Body

blocked_by and duplicate_of are folded into blocks and duplicate with the two sides swapped, so either direction produces the same graph. Adding a relation that already exists is a no-op. A new relation is recorded in the activity of both issues.

curl https://backlog.polder.work/api/v1/issues/981/relations \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "blocked_by", "issue_id": 970}'

Remove a relation#

Removes a relation and answers 204. It takes the same body as adding one, in the body of the DELETE, not in the URL: type and issue_id. Removing a relation that is not there is not an error.

curl -X DELETE https://backlog.polder.work/api/v1/issues/981/relations \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "blocked_by", "issue_id": 970}'