Work item votes overview

A vote is one user's upvote or downvote on a work item. Teams use votes to show how much they want something done, for example on feature requests or bugs in triage.

Each user has at most one vote on a work item. You never address a vote by its own id. Casting and retracting act on the caller's vote on the work item in the path:

• Casting sets your vote. If you have already voted, it changes the existing vote instead of adding a second one.
• Retracting removes your vote. It returns 204 whether or not you had voted.

Both are safe to repeat. Sending the same cast twice leaves one vote with the same value.

Learn more about voting on work items

The vote object

Attributes

• id string (uuid)

  Unique identifier for the vote. It stays the same when the voter changes their vote.

• work_item_id string (uuid)

  The work item the vote is on.

• project_id string (uuid)

  The project the work item belongs to.

• actor_id string (uuid)

  The user who voted.

• vote integer

  1 for an upvote, -1 for a downvote.

• created_at string (date-time)

  When the vote was created.

• updated_at string (date-time)

  When the vote was last cast or changed.

Response200

{
  "id": "d6a2f8c1-3e7b-4a95-8c04-9f1e5b2d7a63",
  "work_item_id": "8c3d1f72-4a9e-4b65-9d20-6e1f3b7a5c48",
  "project_id": "4af68566-94a4-4eb3-94aa-50dc9427067b",
  "actor_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "vote": 1,
  "created_at": "2026-01-14T09:22:41.478363Z",
  "updated_at": "2026-01-14T09:22:41.478363Z"
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/votes/	List work item votes
POST	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/votes/	Cast a vote on a work item
DELETE	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/votes/	Retract your vote on a work item

Access

Operation	Who can call it	Scope
List	Anyone who can see the work item.	projects.work_items:read
Cast and retract	Anyone with the workitem:react permission on the work item.	projects.work_items:write

A work item you can't see returns 404 before any permission check. An archived work item also returns 404, so you can't vote on it.

Response shaping

The list and cast responses accept ?fields= for sparse responses and ?expand=actor to embed the voter. See Sparse fields and Expanding relations. Errors follow the shared problem+json contract.

Changed from v1

• The list returns the standard paginated envelope instead of a bare array.
• Retracting when you haven't voted returns 204. v1 returned 404.
• issue, project, and actor are now work_item_id, project_id, and actor_id, with ?expand=actor for the user object.

See Migrating from v1 for the full list.