Work item subscribers overview

Subscribers are the users who get notified when a work item changes. In the Plane app they appear in the work item's subscribers panel, and the subscribe toggle adds or removes the current user.

The subscriber list belongs to the work item, so there is no subscriber object with its own id. GET returns the whole list. PATCH takes the users to add and the users to remove, and returns the list after the change.

Learn more about work items

The subscriber list

Attributes

• subscriber_ids array of string (uuid)

  User ids of everyone subscribed to the work item, oldest subscription first. An empty array means nobody is subscribed.

  The list only includes active members of the work item's project and, while teamspaces are on for the workspace, members of a teamspace linked to that project. Bots are never listed. A user who subscribed and then left the project drops out of the list, though you can still remove them by id.

Response200

{
  "subscriber_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430", "a3d9e0c4-7b21-4f58-9e6d-2c84b1f07a95"]
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/subscribers/	Get subscribers
GET	/api/v2/workspaces/{slug}/work-items/{identifier}/subscribers/	Get subscribers by identifier
PATCH	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/subscribers/	Update subscribers
PATCH	/api/v2/workspaces/{slug}/work-items/{identifier}/subscribers/	Update subscribers by identifier

GET needs projects.work_items:read and PATCH needs projects.work_items:write. Both routes read and write the same list. Use the project-scoped route when you have the project and work item UUIDs, and the identifier route when you only have a key like PROJ-142. The identifier route also accepts the work item UUID.

Both routes work on archived work items without ?archived=. Drafts, triage work items, and work items in an archived project return 404.

PUT is not supported and returns 405.

Adding and removing

A PATCH body has two optional arrays of user ids:

{
  "add": ["a3d9e0c4-7b21-4f58-9e6d-2c84b1f07a95"],
  "remove": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"]
}

• Users in add get subscribed. Adding someone who is already subscribed changes nothing.
• Users in remove get unsubscribed. Removing someone who isn't subscribed changes nothing.
• Subscribers you don't name stay as they are, so you don't need to read the list before you change it.
• Each array takes up to 100 ids. Duplicate ids count once.
• Putting the same id in both arrays is a 400.
• A body with neither array, such as {}, changes nothing and returns the current list.

The response is the list after the change, in the same shape as GET.

Plane applies writes to one work item one at a time. Two clients that add or remove different people at the same moment both get their change, and activity is recorded only for subscriptions that actually changed.

Removing unlisted subscribers

Some stored subscriptions don't appear in GET:

• Someone who subscribed and then left the project
• A bot that was subscribed before Plane started blocking bots
• A teamspace-only member while teamspaces are off for the workspace

If you know the user id, put it in remove to clear the subscription. remove doesn't check membership or whether the user is a bot.

Who can change what

The permission check depends on which user ids your PATCH names.

Request	Needs
Reading the list	View access to the work item
add or remove with only your own id	View access to the work item
add or remove with anyone else's id	Edit access to the work item, and the manage-subscribers feature on for the workspace

Plane checks the ids you name, not what would change. Naming someone else needs edit access even when nothing would happen to them, for example removing a user who isn't subscribed. The result doesn't depend on who is currently subscribed, so a denied request doesn't reveal it either.

• Without edit access to the work item, naming anyone else returns 403 forbidden.
• With edit access but with the feature switched off for the workspace, it returns 402 payment_required. Following or unfollowing yourself still works. The OpenAPI spec calls this feature MANAGE_WORK_ITEM_SUBSCRIBERS.

A denied request changes nothing, including your own part of it.

Who can be subscribed

Every user in add, including you, must be one of these:

• An active member of the work item's project
• A member of a teamspace linked to the project, while teamspaces are on for the workspace. With teamspaces off, a teamspace-only member fails the membership check.

Bots can't be subscribed, even when they are project members, and a bot can't subscribe itself.

Anyone else you add must also already be able to see the work item. Their project role has to let them view it, and if the work item's type limits who can view it, they have to be in that audience. A project guest who can only see work items they created usually fails this check, and so does a deactivated account.

The visibility rule exists because Plane lets subscribers see a work item even when its type limits who can view it. Subscribing someone through the API never widens who can see the work item.

If any id in add fails one of these rules, the whole request fails with 400 invalid_request and nothing is written. The error lists the ids it rejected:

{
  "type": "invalid_request",
  "code": "invalid_request",
  "detail": "One or more fields failed validation.",
  "errors": [
    {
      "field": "add",
      "code": "invalid",
      "message": "Not members of this project: ['5b7e2f90-c3a1-4d6e-8f42-91d0a6c3e7b8']"
    }
  ]
}

Plane checks the rules in this order and reports the first one that fails:

1. Bots can't be subscribed: [...]
2. Not members of this project: [...]
3. Can't subscribe users who can't see this work item: [...]

Subscriber ids are user ids, the same values as member_id on member rows. Look them up with List project members. Members of a linked teamspace can be subscribed too while teamspaces are on, but they don't appear on the project roster.

Activity and notifications

A PATCH records the same activity on the work item as the subscribe controls in the Plane app:

• Subscribing or unsubscribing yourself records the change in the work item's activity and sends no notification.
• Subscribing or unsubscribing someone else records the change and notifies them.

Adding someone who is already subscribed, or removing someone who isn't, records nothing. Read the history with List activities.

Errors

Errors follow the shared problem+json contract. A work item that doesn't exist, is in another workspace, is a draft or triage work item, is in an archived project, or that you can't view returns 404 not_found on every route. The 404 doesn't tell you which of those it was. Archived work items are found.