Update subscribers by identifier

PATCH/api/v2/workspaces/{slug}/work-items/{identifier}/subscribers/

Subscribe the users in add and unsubscribe the users in remove on a work item addressed by its key (PROJ-142) or its UUID. You don't need the project UUID, so this is the route for a chat command, a bot, or anything else that only has the key.

It behaves the same as Update subscribers. Subscribers you don't name stay as they are, and the response is the full list after the change.

This is the only write on the /work-items/{identifier}/ route. Every other change to a work item goes through the project-scoped routes.

Path Parameters

slug:requiredstring

The workspace slug. It appears in your Plane URLs. In https://app.plane.so/my-team/projects/, the slug is my-team.

identifier:requiredstring

The work item's key, such as PROJ-142, or its UUID.

The project part of the key is upper-cased before lookup, so proj-142 finds the same work item as PROJ-142.

Body Parameters

add:optionalarray of string (uuid)

User ids to subscribe. Up to 100. Adding someone who is already subscribed changes nothing, and duplicate ids count once.

Every id must belong to an active member of the project or, while teamspaces are on for the workspace, a member of a teamspace linked to the project. Bots can't be subscribed. Anyone other than you must also already be able to see the work item. See Who can be subscribed.

remove:optionalarray of string (uuid)

User ids to unsubscribe. Up to 100. Removing someone who isn't subscribed changes nothing.

This also clears a subscription that GET doesn't list, such as someone who has left the project or a bot. See Removing unlisted subscribers.

An id in both add and remove is a 400. A body with neither field, such as {}, changes nothing and returns the current list.

This works on archived work items without ?archived=.

Permissions

Naming only your own id needs view access to the work item. Naming anyone else's id, in either array, needs edit access to the work item and the manage-subscribers feature turned on for the workspace, even if nothing would change for them.

See Who can change what.

Scopes

projects.work_items:write

Errors

Status	Code	Cause
400	invalid_request	add or remove isn't an array of UUIDs, has more than 100 ids, or shares an id with the other. Or someone in add is a bot, isn't a project member, or can't see the work item.
401	unauthorized	Missing or invalid credentials.
402	payment_required	You named someone else and the manage-subscribers feature is off for the workspace.
403	forbidden	You named someone else without edit access to the work item, or your token can't write.
404	not_found	Malformed identifier, no such work item, it's in another workspace, you can't view it, or it's a draft, a triage work item, or in an archived project.
405	method_not_allowed	You sent PUT. Use PATCH.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
413	payload_too_large	The request body is over the size limit.
415	unsupported_media_type	The Content-Type isn't one this endpoint accepts.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Update subscribers by identifier

curl -X PATCH \
  "https://api.plane.so/api/v2/workspaces/my-team/work-items/PROJ-142/subscribers/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "add": ["a3d9e0c4-7b21-4f58-9e6d-2c84b1f07a95"]
}'

import requests

response = requests.patch(
    "https://api.plane.so/api/v2/workspaces/my-team/work-items/PROJ-142/subscribers/",
    headers={"X-Api-Key": "your-api-key"},
    json={"add": ["a3d9e0c4-7b21-4f58-9e6d-2c84b1f07a95"]},
)
print(response.json()["subscriber_ids"])

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/work-items/PROJ-142/subscribers/",
  {
    method: "PATCH",
    headers: { "X-Api-Key": "your-api-key", "Content-Type": "application/json" },
    body: JSON.stringify({ add: ["a3d9e0c4-7b21-4f58-9e6d-2c84b1f07a95"] }),
  },
);
const data = await response.json();

Response200

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

Response403

{
  "type": "forbidden",
  "code": "forbidden",
  "detail": "You don't have permission to edit this workitem"
}