Import an OpenAPI 3 document
const url = 'https://beta-api.plune.ai/v1/api-endpoints/import';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"document":{"openapi":"3.0.3","info":{"title":"Shop API","version":"2.1.0"},"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/orders/{orderId}":{"get":{"summary":"One order","responses":{"200":{"description":"The order"}}}}}}}'};
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/import \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "document": { "openapi": "3.0.3", "info": { "title": "Shop API", "version": "2.1.0" }, "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "paths": { "/orders/{orderId}": { "get": { "summary": "One order", "responses": { "200": { "description": "The order" } } } } } } }'A written spec, or a draft Cairn built from a Postman collection, a HAR file or the traffic it recorded while exploring the UI. Only what an operation is called and asks for is read: the method, the path, the summary, the auth scheme names - no schema, example or value. What is marked x-cairn-derived (the document, an operation, a body schema) is derived, the rest confirmed; a confirmed endpoint is never lowered. A traffic draft (or source: traffic) says each endpoint was seen, at seenAt on environment. A path that is not a template is kept out and counted in skipped, never named. A person’s import writes the rows; an agent’s import marks seen what the catalog has and queues the rest for a person, and so does a token’s import of a derived draft. The room for all of it is asked before anything is written, so a document is imported whole or not at all: the new endpoints under apiEndpointsPerProject, the new proposals under pendingReviewItems (429 quota); an endpoint the catalog has, and one already waiting in the queue, takes no place. Into one API (apiId, or the project’s only one); the rows of another API are not touched. JSON only.
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)
An OpenAPI 3 document, as JSON
object
Where it came from; left out, a traffic draft of Cairn is traffic and anything else spec
Where the traffic of a traffic draft was seen
When the traffic of a traffic draft was seen; now when left out or ahead of the server
Example
{ "document": { "openapi": "3.0.3", "info": { "title": "Shop API", "version": "2.1.0" }, "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "paths": { "/orders/{orderId}": { "get": { "summary": "One order", "responses": { "200": { "description": "The order" } } } } } }}Responses
Section titled “ Responses ”What the import did
object
The document is marked x-cairn-derived
Endpoints new to the catalog
Endpoints the catalog had, described further or seen again
Endpoints new to the catalog queued for a person instead (an agent’s import, or a token’s import of a derived draft)
Operations kept out because their path is not a template; counted, never named
Example
{ "source": "spec", "derived": false, "created": 1, "updated": 0, "proposed": 0, "skipped": 0}Invalid JSON or body; a document that is not OpenAPI 3 (Swagger 2.0 is named); with several APIs, no apiId (api_required)
object
Example generated
{ "error": "example"}No / invalid token or session
You are in the project as a reader, or the token is read-only
No such API in your project
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