Change a member’s role
const url = 'https://beta-api.plune.ai/v1/members/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"role":"reader"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://beta-api.plune.ai/v1/members/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "role": "reader" }'The owner or a manager, by the rules of ADR 0050 §2 (api.ts → setMemberRole, the role select on a row). The id is the member’s user id, as GET /v1/members lists it. The same role again is a no-op that answers 200. Give your own level and below: a manager makes members and readers managers, members or readers, and does not touch another manager (403 manager_cannot_touch_manager) — a manager is demoted by the owner alone. Nobody changes the owner’s role (409 owner_protected) and nobody is made the owner (400 use_handover): ownership moves by a handover. In a company’s project (ADR 0038) only a manager or the owner of the project who is also the owner or a manager of the company changes a role (403 company owner or manager only for the rest). Seats (#1439): adding a person (or inviting an address) who is not yet counted in the account or company that owns the tier is capped by the tier — write roles Free 1, Personal 1, Team 50, Enterprise none; readers Free 1, Personal 3, Team 5, Enterprise none. 429 with quota.kind: "writeSeats" or "readerSeats" and no Retry-After, only once the operator sets TIER_LIMITS_ENFORCE=true (until then counted and logged). Moving a writer down to a reader takes a reader seat (#2012): the same 429 with quota.kind: "readerSeats" when the readers are full, and the role is left as it was. An invitation not yet accepted takes no seat but is checked when created and again when accepted (a refused acceptance leaves it pending).
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The member’s userId
Header Parameters
Section titled “Header Parameters ”Which of your projects to act in — an id from GET /v1/projects. Absent, your default project. A project you are not a member of answers 404, the same as one that does not exist. Ignored under a bearer token, which is bound to the project it was minted in.
Request Body required
Section titled “Request Body required ”object
A role an invitation or a change of role gives (ADR 0050 §2): anything but owner. owner here is answered 400 with code: use_handover — ownership moves by POST /v1/projects/{id}/handover (or the company’s). Give your own level and below: the owner and a manager may give any of the three.
Example
{ "role": "reader"}Responses
Section titled “ Responses ”The member as they are now
object
The display name, once people have one (T3); null until then.
What a member may do (B8-team, ADR 0050). owner — exactly one a project: its secrets (bucket, CI, AI keys), statuses, name, the move into a company, and the handover of ownership; never demoted or removed, and does not leave — ownership moves only by a handover the recipient accepts. manager runs the people of their level and below: invites as manager, member or reader, and changes and removes members and readers (a manager is demoted and removed by the owner alone). member works in the project and manages nobody; reader is refused every write at the boundary, before a handler runs, but a comment, a pending proposal and leaving the project (#1440, #2055).
Who invited them (a userId); null for the person the project was created by.
Present while the person’s account waits in the Bin (#952): the place stays until the purge; screens say «deleted account».
ADR 0050 §3: on the row of the person the owner asked to take the project over, while the request waits — absent on every other row.
object
Example
{ "userId": "6f1c2b3a-0000-4000-8000-0000000000a2", "email": "colleague@example.com", "name": null, "role": "reader", "joinedAt": "2026-09-16T09:12:04.151Z", "invitedBy": "u-shop"}Invalid body — one of the three roles; owner is code: use_handover
object
Example
{ "error": "nobody is made the owner here — ownership moves by a handover (POST /v1/projects/{id}/handover)", "code": "use_handover"}No / invalid token or session
A member or a reader asked (project owner or manager only); a manager asked about another manager (code: manager_cannot_touch_manager); or, in a company’s project, somebody who is not the owner or a manager of the company
object
Examples
{ "error": "project owner or manager only"}{ "error": "a manager is demoted or removed by the owner only", "code": "manager_cannot_touch_manager"}No such member in this project
object
Example
{ "error": "member '6f1c2b3a-0000-4000-8000-0000000000a2' not found"}The owner — never demoted; ownership moves by a handover
object
Example
{ "error": "the owner of the project is never demoted or removed — ownership moves by a handover", "code": "owner_protected"}Two refusals share this status, and what to do about them is opposite. Rate-limited — the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442, #2092): Retry-After carries the seconds until the window rolls over, and waiting that long is the way out. Quota reached — a ceiling on what the project holds (runs in the last 24 hours, test cases, items waiting in the review queue, rules in force in the project’s memory): { error, quota }. A retry straight away frees nothing, so do not loop on it; the message says what makes room — deleting cases, working the queue down, an operator raising the limit — and the run quota, a rolling 24 hours, frees its oldest runs as they age out. Tell the two apart by the body: a 429 whose body has a quota object is a quota, one without it is a throttle. quota carries kind, limit, used, remaining and resetsAt: the figures behind the sentence, and for the run quota the instant its oldest run ages out (#1258). Retry-After is sent on a quota only where there is such an instant (the run quota: the whole seconds, at least 1, until resetsAt); the case, review-queue and project quotas free only by an action, have resetsAt: null, and send no Retry-After. GET /v1/quotas reads the same figures without a refusal.
object
The body of a 429 that is a quota and not a throttle: the sentence, and the figures behind it.
object
What was reached and the way out.
object
The ceiling. A write that would take used past it is refused with 429.
What the project holds now, counted by the same query that refuses a write.
limit - used, never below 0.
When the oldest counted run ages out of the rolling 24 hours and a slot frees on its own. null for the two quotas only an action frees (delete cases, decide queue items), and for a run quota with no runs in the window.
Examples
A throttle: no `quota`; wait `Retry-After`
{ "error": "rate limit exceeded — slow down"}A quota (#2458): the MCP server ceiling; `resetsAt` is null, nothing frees it by waiting
{ "error": "MCP server quota reached — at most 50 servers per project, and a server cannot be removed yet. Ask an operator to raise the limit.", "quota": { "kind": "mcpServersPerProject", "limit": 50, "used": 50, "remaining": 0, "resetsAt": null }}Headers
Section titled “Headers ”Seconds until the window rolls over on a throttle; on a quota, until quota.resetsAt — sent only for the run quota, which has one