Docs as Code

List the documentations of a project

GET /api/projects/{projectId}/docs

Returns the documentations of a project with their versions, which is how a pipeline finds the id of the version it should write into. Only a version whose status is draft or review accepts changes, so pick one of those.

Parameters

Responses

200 — The documentations of the project.

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.

Get the page tree of a version

GET /api/projects/{projectId}/docs/{docId}/versions/{versionId}/tree

Returns the full hierarchy of a documentation version. Each node is exactly one of a page, a folder or an API reference snapshot, and the type field says which of the three is filled.

The response carries an ETag, so a pipeline that syncs repeatedly can send If-None-Match and skip the work when nothing moved.

Parameters

Responses

200 — The documentation tree.

304 — Nothing changed since the ETag you sent.

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.

Create a page

POST /api/projects/{projectId}/docs/{docId}/versions/{versionId}/pages

Creates a page inside a version, at the root or under a folder. The slug is derived from the title when you do not send one, and it is what the public portal URL is built from, so set it explicitly if the URL matters to you.

Parameters

Request body

Required.

Content type: application/json

Responses

201 — The page was created.

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 — A request with this Idempotency-Key is still running, or its response was too large to keep. The code is IDEMPOTENCY_KEY_IN_PROGRESS or IDEMPOTENCY_RESPONSE_NOT_STORED, and in the second case the request is not run again.

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.

Get a page with its content

GET /api/projects/{projectId}/docs/{docId}/versions/{versionId}/pages/{pageId}

Returns one page including its Markdown content and its rowVersion. Send that rowVersion back on the next update and a concurrent edit is rejected with 409 instead of silently overwriting someone else's work.

Parameters

Responses

200 — The page.

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.

Update a page

PUT /api/projects/{projectId}/docs/{docId}/versions/{versionId}/pages/{pageId}

Replaces the title and content of a page, which is the call that carries a Markdown file from your repository into Routebase. A page that a person has locked in the editor is not writable, and the call is rejected until the lock is released.

Parameters

Request body

Required.

Content type: application/json

Responses

200 — The updated page.

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 resource changed since you read it. Reload it, reapply your change and send

the fresh rowVersion. The code is CONCURRENCY_CONFLICT.

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.

Create a folder

POST /api/projects/{projectId}/docs/{docId}/versions/{versionId}/folders

Creates a folder in a version. A folder with isSection set becomes a top level section in the portal header rather than an entry in the sidebar, and only a folder at the root can be one.

Parameters

Request body

Required.

Content type: application/json

Responses

201 — The folder was created.

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 — A request with this Idempotency-Key is still running, or its response was too large to keep. The code is IDEMPOTENCY_KEY_IN_PROGRESS or IDEMPOTENCY_RESPONSE_NOT_STORED, and in the second case the request is not run again.

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.

Reorder the items under one parent

PUT /api/projects/{projectId}/docs/{docId}/versions/{versionId}/tree/reorder

Sets the order of the items inside one folder, or at the root when parentFolderPublicId is null. Send the complete list of ids in the order you want, because the position of an item is its index in that list.

Parameters

Request body

Required.

Content type: application/json

Responses

204 — The order was applied.

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 — A request with this Idempotency-Key is still running, or its response was too large to keep. The code is IDEMPOTENCY_KEY_IN_PROGRESS or IDEMPOTENCY_RESPONSE_NOT_STORED, and in the second case the request is not run again.

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.