PolderAPI

Backlog API

Favorites

Read what you have starred and star or unstar issues, projects and teams.

Base URLhttps://backlog.polder.work

Starring is a note to yourself: a private bookmark that changes nothing about the issue, project or team. Favorites belong to the token's owner, so two tokens of different people see different lists.

Changing the set takes its own scope, favorites:write, rather than issues:write: pinning an issue should not require the power to delete issues. Reading the list takes issues:read, because what comes back is issues. See Scopes.

List favorites

GET/api/v1/workspaces/{workspace}/favoritesscope issues:read

Everything you starred in this workspace, all three kinds in one answer. It is not paged: a favorites list is a small hand-made set, and each kind is capped at 200.

curl https://backlog.polder.work/api/v1/workspaces/7/favorites \
  -H "Authorization: Bearer $POLDER_TOKEN"

{
  "data": {
    "issues": [ { "id": 412, "identifier": "ENG-12", "title": "Printer is on fire", "is_favorite": true, "…": "…" } ],
    "projects": [ { "id": 3, "name": "Launch", "slug": "launch", "…": "…" } ],
    "teams": [ { "id": 5, "key": "ENG", "name": "Engineering", "…": "…" } ]
  }
}

The objects are the same as in Issues, the projects list and the teams list. Issues carry is_favorite: true, newest change first; projects are sorted by name, teams by name.

Starring is not a way around visibility. A star on an issue of a private team stays in the database after you leave the team, but it no longer comes back from this endpoint. Archived issues are left out too.

Star and unstar

All six routes below take favorites:write, answer 204 with no body and are idempotent: starring what is starred, or unstarring what is not, is simply the state you asked for. You need the right to view the thing, not to edit it. Without it the answer is 403 (an unknown id is 404).

Star an issue

POST/api/v1/issues/{issue}/favoritescope favorites:write

{issue} is the numeric issue id.

curl -X POST https://backlog.polder.work/api/v1/issues/412/favorite \
  -H "Authorization: Bearer $POLDER_TOKEN"

Unstar an issue

DELETE/api/v1/issues/{issue}/favoritescope favorites:write

Star a project

POST/api/v1/projects/{project}/favoritescope favorites:write

You must be a member of the project's workspace (403 otherwise).

Unstar a project

DELETE/api/v1/projects/{project}/favoritescope favorites:write

Star a team

POST/api/v1/teams/{team}/favoritescope favorites:write

Important {team} is the numeric team id here, not the team key. Elsewhere in this API ?team=ENG filters by key, but a key is only unique within a workspace and these routes do not name one.

Unstar a team

DELETE/api/v1/teams/{team}/favoritescope favorites:write

Where else you see it

Issue payloads carry is_favorite wherever the query asked for it: the issue list, a saved view's issues, GET /favorites and a single issue. It is absent, not false, where nobody asked.