Skip to content

Create a project

POST
/v1/projects
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.

Media type application/json

The body of POST /v1/projects and of PATCH /v1/projects/{id} alike — a project has a name and nothing else to set.

object
name
required
string
>= 1 characters <= 100 characters
Example
{
"name": "Mobile app"
}

Created — you are its owner

Media type application/json

A project the caller is a member of, with their role in it — one row of GET /v1/projects.

object
id
required
string
name
required
string
<= 100 characters
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
createdAt
required
string format: date-time
lastRun

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
at
required
string format: date-time
total
required
integer
passed
required
integer
company

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
id
required
string
name
required
string
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

Media type application/json
object
error
required
string
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.

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