Skip to content

Invite an address

POST
/v1/members
curl --request POST \
--url https://beta-api.plune.ai/v1/members \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "email": "newcomer@example.com", "role": "reader" }'

The owner or a manager (api.ts → inviteMember, the Invite form), as a manager, a member or a reader — owner is 400 with code: use_handover: ownership moves by POST /v1/projects/{id}/handover (ADR 0050). Two outcomes, told apart by kind: an address that already has a Plune account is a member at once; any other address gets an invitation — a mail says where to sign in, the beta door lets the address through, and the sign-in itself turns the invitation into a membership. No token in the mail: the magic link is the proof. The address is lower-cased before it is compared or stored. Twice for the same address is 409, and so is a project at its member limit, and the address of an account that waits in the Bin (code: account_in_bin, #2053) until the purge frees it. In a company’s project (ADR 0038) the company decides: only its owner and managers ask anybody in (403 company owner or manager only for the rest); a member of the company comes in with the role their company role maps to, whatever role was asked; an address from outside is asked into the company as well, with the role chosen, and the sign-in makes it a member of both. 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). An invitation not yet accepted takes no seat but is checked when created and again when accepted (a refused acceptance leaves it pending).

X-Plune-Project
string

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.

Media type application/json
object
email
required
string format: email
role
required

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.

string
Allowed values: manager member reader
Examples

An address without an account — an invitation

{
"email": "newcomer@example.com",
"role": "reader"
}

Invited — kind says which of the two it became

Media type application/json
One of:

What inviting an address produced: a member at once when an account holds it (kind: member), else an invitation for the address to sign in with (kind: invitation).

object
kind
required
string
Allowed values: member
userId
required
string format: uuid
email
required
string format: email
name
required

The display name, once people have one (T3); null until then.

string
nullable
role
required

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).

string
Allowed values: owner manager member reader
joinedAt
required
string format: date-time
invitedBy
required

Who invited them (a userId); null for the person the project was created by.

string
nullable
deleted

Present while the person’s account waits in the Bin (#952): the place stays until the purge; screens say «deleted account».

boolean
pendingHandover

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
id
required
string format: uuid
expiresAt
required
string format: date-time
Example
{
"kind": "invitation",
"id": "6f1c2b3a-0000-4000-8000-0000000000a3",
"email": "newcomer@example.com",
"role": "reader",
"invitedBy": "u-shop",
"createdAt": "2026-09-16T09:12:04.151Z"
}

Invalid body — an email address and one of the three roles; owner is code: use_handover

Media type application/json
object
error
required
string
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 — or, in a company’s project, somebody who is not the owner or a manager of the company

Media type application/json
object
error
required
string
Example
{
"error": "project owner or manager only"
}

The header names a project you are not in — or one that went to the Bin while the request waited for it (#2070)

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

Already in, already invited, the project is at its member limit, or the address is an account’s in the Bin (code: account_in_bin)

Media type application/json
object
error
required
string
Example
{
"error": "newcomer@example.com is already in this project, or already invited"
}

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.

Media type application/json
One of:
object
error
required
string
Examples

A throttle: no `quota`; wait `Retry-After`

{
"error": "rate limit exceeded — slow down"
}
Retry-After
integer

Seconds until the window rolls over on a throttle; on a quota, until quota.resetsAt — sent only for the run quota, which has one