Update subscribers

PATCH/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/subscribers/

Subscribe the users in add and unsubscribe the users in remove, then get back the work item's full subscriber list. Subscribers you don't name stay as they are, so you can follow, unfollow, or add a teammate without reading the list first.

If you only have a key like PROJ-142, use Update subscribers by identifier.

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.

project_id:requiredstring (uuid)

The project the work item belongs to.

pk:requiredstring (uuid)

The work item's UUID. A PROJ-142 identifier here returns 404.

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. That covers following and unfollowing.

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. Plane checks the ids you name, not what would change, so removing someone who isn't subscribed still needs edit access. When a check fails, nothing is written, including your own part of the change.

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	No such work item, it's outside your project or tenant, 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

curl -X PATCH \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/subscribers/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "add": ["a3d9e0c4-7b21-4f58-9e6d-2c84b1f07a95"],
  "remove": ["7f2b9e04-6c1d-4a58-9e3b-0d4c8a2f6b71"]
}'

import requests

response = requests.patch(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
    "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/subscribers/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "add": ["a3d9e0c4-7b21-4f58-9e6d-2c84b1f07a95"],
        "remove": ["7f2b9e04-6c1d-4a58-9e3b-0d4c8a2f6b71"],
    },
)
print(response.json()["subscriber_ids"])

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
    "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/subscribers/",
  {
    method: "PATCH",
    headers: { "X-Api-Key": "your-api-key", "Content-Type": "application/json" },
    body: JSON.stringify({
      add: ["a3d9e0c4-7b21-4f58-9e6d-2c84b1f07a95"],
      remove: ["7f2b9e04-6c1d-4a58-9e3b-0d4c8a2f6b71"],
    }),
  },
);
const data = await response.json();

Response200

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

Response400

{
  "type": "invalid_request",
  "code": "invalid_request",
  "detail": "One or more fields failed validation.",
  "errors": [
    {
      "field": "add",
      "code": "invalid",
      "message": "Can't subscribe users who can't see this work item: ['5b7e2f90-c3a1-4d6e-8f42-91d0a6c3e7b8']"
    }
  ]
}

Response402

{
  "type": "payment_required",
  "code": "payment_required",
  "detail": "Managing other people's work item subscriptions is not enabled for this workspace."
}

What a PATCH changes

• The response is the full subscriber list after the change, oldest subscription first. It isn't limited to the users you named.
• Subscribing or unsubscribing someone else adds an entry to the work item's activity and notifies that person. Changing your own subscription adds an entry with no notification. Ids that didn't change anything add nothing.
• Plane applies writes to one work item one at a time, so two clients adding or removing different people at once both get their change.

Follow or unfollow as the caller

To follow a work item as the user behind your token, put your own user id in add. To unfollow, put it in remove. This needs only view access and works with the manage-subscribers feature off. Get your id from Get current user.

{ "add": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"] }