---
title: "Add or remove a task's collaborators"
method: PUT
path: "/tasks/{id}/collaborators"
tags: ["tasks"]
---

# Add or remove a task's collaborators

`PUT /tasks/{id}/collaborators`

## Request

- Base URL: `https://api.onplana.com/api`
- URL: `https://api.onplana.com/api/tasks/{id}/collaborators`
- Auth: one of:
  - HTTP bearer
  - API key in header `Authorization`

Adding or removing others needs task.assign plus task.edit.any (or being the assignee); anyone may remove themselves. Otherwise 403 COLLABORATORS_NOT_ALLOWED. A collaborator must be an active member of the task's project, and a task holds at most 20. Each person who could not be added or removed is listed in skipped with a reason; the rest still land.

## Path parameters

- `id` string, required

## Headers

- `X-Organization-Id` string, required

## Request body

- object: At least one person to add or remove
  - `add` string[]: User ids to add
  - `remove` string[]: User ids to remove

## Response `200`

What changed, and the list after it

- object
  - `added` string[]
  - `removed` string[]
  - `skipped` object[]
    - `userId` string
    - `reason` 'NOT_ORG_MEMBER' | 'NOT_PROJECT_MEMBER' | 'IS_ASSIGNEE' | 'ALREADY_COLLABORATOR' | 'NOT_COLLABORATOR' | 'CAP_REACHED'
  - `collaborators` TaskCollaborator[]
    - `id` string, required: User id
    - `name` string, nullable, required
    - `avatar` string, nullable, required
    - `isAgentPersona` boolean, required: An AI agent member of the organization

## Other responses

- `400`: Validation error
- `401`: Unauthorized - missing or invalid JWT
- `403`: Forbidden - insufficient role
- `404`: Task not found, or not visible to the caller

---

[API](https://skmtc.dev/onplana/apis/onplana-api.md) · [All operations](https://skmtc.dev/onplana/apis/onplana-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onplana/apis/onplana-api/revisions/c3d6c89e9dc8?raw)