Skip to content

Import an OpenAPI 3 document

POST
/v1/api-endpoints/import
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.

Media type application/json
object
apiId

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)

string
document
required

An OpenAPI 3 document, as JSON

object
source

Where it came from; left out, a traffic draft of Cairn is traffic and anything else spec

string
Allowed values: spec code traffic
environment

Where the traffic of a traffic draft was seen

string
>= 1 characters <= 100 characters
seenAt

When the traffic of a traffic draft was seen; now when left out or ahead of the server

string format: date-time
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"
}
}
}
}
}
}
}

What the import did

Media type application/json
object
source
required
string
Allowed values: spec code traffic
derived
required

The document is marked x-cairn-derived

boolean
created
required

Endpoints new to the catalog

integer
updated
required

Endpoints the catalog had, described further or seen again

integer
proposed
required

Endpoints new to the catalog queued for a person instead (an agent’s import, or a token’s import of a derived draft)

integer
skipped
required

Operations kept out because their path is not a template; counted, never named

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

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

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

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