Add an endpoint by hand
const url = 'https://beta-api.plune.ai/v1/api-endpoints';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"method":"get","path":"/orders/{orderId}","source":"spec","summary":"One order","auth":["bearerAuth"]}'};
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/api-endpoints \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "method": "get", "path": "/orders/{orderId}", "source": "spec", "summary": "One order", "auth": [ "bearerAuth" ] }'A person, or a write token without X-Plune-Session. An agent proposes instead - POST /v1/review-items/endpoints - and is refused here (403 agent_proposes): nothing an agent finds enters the catalog without a person. One endpoint a method and path shape in an API: /orders/{id} and /orders/{orderId} are the same one (409 endpoint_exists), and two APIs each hold their own. A new endpoint takes a place under the project’s ceiling (429 quota, kind: apiEndpointsPerProject). Logged as an update of the project, one field an endpoint.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
The API it is for (GET /v1/apis). Left out: the project’s only API, made as API when there is none; refused with several (400 api_required)
Upper or lower case; stored upper case
A path TEMPLATE: it starts with /, a parameter is a whole segment written {name}, and a segment that names one thing - digits, a UUID, a long hex run, anything with @ - is refused: write it as a parameter. No query, no fragment.
manual when left out
confirmed when left out
The auth scheme names it asks for, as a spec names them; [] is public
Example
{ "method": "get", "path": "/orders/{orderId}", "source": "spec", "summary": "One order", "auth": [ "bearerAuth" ]}Responses
Section titled “ Responses ”The endpoint
object
The API it belongs to (#2398); one endpoint a method and path shape within an API
A template, /orders/{orderId}; one endpoint a method and path shape, whatever its parameters are called
Where the catalog learnt of it; a description replaces traffic once one names it
derived - inferred from examples or traffic (x-cairn-derived); confirmed - a written spec or a person says so
A spec, the code or a person describes it - not only traffic. The drift tells its two sides apart by it
The auth scheme names it asks for; [] public, null not known
When traffic last showed it
Where traffic last showed it
object
The live cases linked to it, each with its external keys - the tests that run it
object
An identifier another tool already uses for this test, so a report can find its case without anyone typing a Plune id. The order of kind is load-bearing: it is the ranking that decides which key wins when several match different cases.
object
Example
{ "id": "6f1c2b3a-0000-4000-8000-000000002192", "projectId": "u-shop::default", "apiId": "4b6f3c1e-8d2a-4f5b-9c7e-1a2b3c4d5e6f", "method": "GET", "path": "/orders/{orderId}", "source": "spec", "trust": "confirmed", "inSpec": true, "summary": "One order", "auth": [ "bearerAuth" ], "lastSeenAt": null, "lastSeenEnvironment": null, "createdBy": "6f1c2b3a-0000-4000-8000-0000000000a2", "createdAt": "2026-11-04T09:00:00.000Z", "updatedAt": "2026-11-04T09:05:00.000Z", "coverage": { "cases": [] }}Invalid JSON or body; a path that is not a template; with several APIs, no apiId (api_required)
object
Example generated
{ "error": "example"}No / invalid token or session
A reader, a read token, or an agent (agent_proposes)
object
Example generated
{ "error": "example"}No such API in your project
object
Example generated
{ "error": "example"}The API has this endpoint already (endpoint_exists)
object
Example generated
{ "error": "example"}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