Create a project
const url = 'https://beta-api.plune.ai/v1/projects';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"Mobile app"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://beta-api.plune.ai/v1/projects \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "Mobile app" }'A name, and the caller is its owner (api.ts → createProject, the “New project…” dialog of the switcher). Nothing is copied into it — settings, tags and the steps database are per project and start empty. Put its id in X-Plune-Project to work in it; mint a token for it on Account → API tokens to give CI one bound to it. The tier caps the projects an account owns (Free 3, Personal 10; GET /v1/usage shows limits.projects). That cap only refuses (429 with quota.kind: "projects"; no Retry-After, there is no reset time to give) once the operator sets TIER_LIMITS_ENFORCE=true; until then it is counted and logged.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”The body of POST /v1/projects and of PATCH /v1/projects/{id} alike — a project has a name and nothing else to set.
object
Example
{ "name": "Mobile app"}Responses
Section titled “ Responses ”Created — you are its owner
A project the caller is a member of, with their role in it — one row of GET /v1/projects.
object
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).
In GET /v1/projects only: the project’s newest live run — when, how many results, how many passed — or null for a project with no run yet. Counted as GET /v1/runs counts a row: the summary an upload stored, else its results. The Projects page reads it under each name.
object
In GET /v1/projects only: the company the project is in (ADR 0038), or null for a personal one. The Projects page names it as the owner of the card.
object
Example
{ "id": "9c4e7d10-0000-4000-8000-0000000000a4", "name": "Mobile app", "role": "owner", "createdAt": "2026-09-16T09:12:04.151Z"}Invalid body — a name is 1 to 100 characters
object
Example generated
{ "error": "example"}No / invalid token or session
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