API Specs

List the specifications of a project

GET /api/projects/{projectId}/specs

Returns the specifications of a project together with the number of their latest published version, so a pipeline can resolve a spec by name and see at a glance what is live.

Parameters

Responses

200 — A page of specifications.

401 — The API key is missing, invalid, expired or revoked. A US organization calling

without X-RB-Region: us also lands here, because the request reached the wrong region.

403 — The key is valid but lacks the permission or the project scope for this call.

A scoped key is also refused on organization level operations by design.

404 — The resource does not exist, or it belongs to another organization or project.

Both cases answer the same way on purpose, so the API cannot be used to probe for foreign identifiers.

429 — The rate limit was exceeded. The Retry-After header gives the seconds to wait.

List the versions of a specification

GET /api/projects/{projectId}/specs/{specId}/versions

Returns the versions of a specification with their status and publish target. Only a version whose status is published is frozen, so anything else can still change underneath you.

Parameters

Responses

200 — A page of versions.

401 — The API key is missing, invalid, expired or revoked. A US organization calling

without X-RB-Region: us also lands here, because the request reached the wrong region.

403 — The key is valid but lacks the permission or the project scope for this call.

A scoped key is also refused on organization level operations by design.

404 — The resource does not exist, or it belongs to another organization or project.

Both cases answer the same way on purpose, so the API cannot be used to probe for foreign identifiers.

429 — The rate limit was exceeded. The Retry-After header gives the seconds to wait.

Export the current state of a specification

GET /api/projects/{projectId}/specs/{specId}/export

Returns the working state of a specification as OpenAPI, which is the draft as it stands in the designer right now. To export something stable, export a published version instead.

Parameters

Responses

200 — The specification document.

401 — The API key is missing, invalid, expired or revoked. A US organization calling

without X-RB-Region: us also lands here, because the request reached the wrong region.

403 — The key is valid but lacks the permission or the project scope for this call.

A scoped key is also refused on organization level operations by design.

404 — The resource does not exist, or it belongs to another organization or project.

Both cases answer the same way on purpose, so the API cannot be used to probe for foreign identifiers.

429 — The rate limit was exceeded. The Retry-After header gives the seconds to wait.

Export a published version

GET /api/projects/{projectId}/specs/{specId}/versions/{versionId}/export

Returns a published version as a downloadable OpenAPI document. A published version is frozen, so the same call returns the same bytes forever, which makes it safe to generate clients from in a build.

Parameters

Responses

200 — The specification document as a file.

401 — The API key is missing, invalid, expired or revoked. A US organization calling

without X-RB-Region: us also lands here, because the request reached the wrong region.

403 — The key is valid but lacks the permission or the project scope for this call.

A scoped key is also refused on organization level operations by design.

404 — The resource does not exist, or it belongs to another organization or project.

Both cases answer the same way on purpose, so the API cannot be used to probe for foreign identifiers.

429 — The rate limit was exceeded. The Retry-After header gives the seconds to wait.

Record that a version went into an environment

POST /api/projects/{projectId}/specs/{specId}/versions/{versionId}/promote

Tells Routebase which version an environment now serves. The intended order is that your pipeline deploys first and then makes this call, so the pin reflects what is actually running rather than what someone intended.

A call authenticated with an API key is recorded with source cli, which is how a pipeline assertion is told apart from someone clicking in the UI. If the target environment freezes versions, the promoted version becomes immutable here.

Parameters

Request body

Required.

Content type: application/json

Responses

200 — The promotion was recorded.

400 — The request was malformed or failed validation.

401 — The API key is missing, invalid, expired or revoked. A US organization calling

without X-RB-Region: us also lands here, because the request reached the wrong region.

403 — The key is valid but lacks the permission or the project scope for this call.

A scoped key is also refused on organization level operations by design.

404 — The resource does not exist, or it belongs to another organization or project.

Both cases answer the same way on purpose, so the API cannot be used to probe for foreign identifiers.

409 — The promotion is blocked. The most common reason is an unacknowledged impact

on dependent services, which you clear by sending impactAcknowledged.

With an Idempotency-Key, a 409 can also mean that a request with this key is still running or that its response was too large to keep. The code is then IDEMPOTENCY_KEY_IN_PROGRESS or IDEMPOTENCY_RESPONSE_NOT_STORED.

422 — This Idempotency-Key was already used with a different request body, so use a new key. The code is IDEMPOTENCY_KEY_REUSED.

429 — The rate limit was exceeded. The Retry-After header gives the seconds to wait.