Making requests

Base URLs and versioning#

All paths in these docs start with /api/v1. The version is part of the path so that a script written today keeps working; changes that would break a client get a new version.

Collections live under a workspace#

GET /api/v1/workspaces/{workspace}/issues     a collection, inside a workspace
GET /api/v1/issues/{issue}                    one thing, addressed by its own id

The nesting is deliberate. A person sees which workspace they are in; a script cannot. If a token followed whatever workspace its owner last opened in a browser, a click would change what an unchanged cron job does.

Start with GET /api/v1/me. It needs no scope and is the way to find the workspace ids you may use:

{
  "data": {
    "user": { "id": 1, "name": "Sanne", "email": "sanne@example.com" },
    "scopes": ["issues:read", "issues:write"],
    "workspaces": [{ "id": 7, "name": "Studio", "slug": "studio" }]
  }
}

Note A workspace you are not a member of answers 404, not 403. It does not confirm that it exists.

Teams are addressed by id in the path, or by key in a query (?team=ENG), because a team key is only unique inside one workspace.

The envelope#

Responses put the payload under data. A deleted thing answers 204 with no body.

{
  "data": [ { "id": 41, "identifier": "ENG-12", "title": "Printer is on fire" } ],
  "meta": { "page": 1, "per_page": 50, "total": 214, "last_page": 5 }
}

Pagination#

Collections are paged with ?page= (starting at 1) and ?per_page= (default 50, at most 200). meta tells you the total and the last page. Walk the pages until page equals last_page.

curl "https://backlog.polder.work/api/v1/workspaces/7/issues?page=2&per_page=100" \
  -H "Authorization: Bearer $POLDER_TOKEN" -H "Accept: application/json"

Individual endpoints add their own filters (?team=, ?q=, ?assignee_id=); each reference page lists them.

Writing#

Send JSON with Content-Type: application/json. PATCH changes only the fields you send, so you can update a title without touching the rest. Validation problems come back as 422 with the fields that failed; see Rate limits and errors.

Tip The Docs API and the Chat API have their own conventions (Notion-shaped lists with cursors, and per-user endpoints with no workspace in the path). Their overview pages say so.