For AI agents: the complete documentation index is at https://docs.routebase.dev/llms.txt. Every page is also available as Markdown by appending index.md to its URL or by sending Accept: text/markdown.
API Policies

Idempotency Keys

A write can succeed on the server while its response gets lost on the way back to your client. An Idempotency-Key header lets you send that request again, because Routebase recognizes the repeat and returns the first result instead of running the request a second time.

The header is optional. A request without it behaves as if this page did not exist.

Sending a key

Create a new random value for each logical request, such as a UUID, and send the same value on every retry of that request.

curl -X POST "https://api.routebase.dev/api/projects/$PROJECT_ID/docs/$DOC_ID/versions/$VERSION_ID/pages" \
  -H "X-API-Key: $ROUTEBASE_API_KEY" \
  -H 'Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"' \
  -H "Content-Type: application/json" \
  -d '{"title": "Getting started"}'

A key holds between 1 and 255 characters. The header follows the IETF draft draft-ietf-httpapi-idempotency-key-header, which writes the value in double quotes. Routebase accepts it with or without them, and both forms are the same key.

Operations that accept a key

Operation Method and path
cliRunTestSuite POST /api/cli/run
executeTestSuite POST /api/projects/{projectId}/test-suites/{suiteId}/execute
promoteSpecVersion POST /api/projects/{projectId}/specs/{specId}/versions/{versionId}/promote
enqueueScanRun POST /api/projects/{projectId}/security/scan-profiles/{profileId}/run
createDocPage POST /api/projects/{projectId}/docs/{docId}/versions/{versionId}/pages
createDocFolder POST /api/projects/{projectId}/docs/{docId}/versions/{versionId}/folders
updateDocPage PUT /api/projects/{projectId}/docs/{docId}/versions/{versionId}/pages/{pageId}
reorderTreeItems PUT /api/projects/{projectId}/docs/{docId}/versions/{versionId}/tree/reorder

The SCIM endpoints don't use a key. Other operations ignore the header.

What a retry returns

Situation Response
The first request succeeded The stored status, headers and body, plus Idempotency-Replayed: true
The first request is still running 409 with the code IDEMPOTENCY_KEY_IN_PROGRESS. Send the same request again later.
The key was used with a different request body 422 with the code IDEMPOTENCY_KEY_REUSED. Use a new key.
The first request failed Routebase runs the request again, because only a success is stored.
The first response was larger than 1 MB 409 with the code IDEMPOTENCY_RESPONSE_NOT_STORED. The request is not run again.
The key is empty or longer than 255 characters 400 with the code IDEMPOTENCY_KEY_INVALID

How long a key lasts

Routebase keeps a successful result for 24 hours after the request finishes. After that, the same key starts a new request, so don't retry with an old key after that time.

A key belongs to your organization, your user and the API key that sent it, as well as to the method and path of the request. The same value on another path or from another API key is a different key.

  • Rate Limits explains how a retry counts against your budget.
  • API Keys explains how to create and scope a key.