Changelog

Changes to the Ollav REST API, MCP server and docs, newest first. Feeds: Atom, RSS.

API versions

Breaking changes ship as dated versions; additive ones (new endpoints, new fields) reach every version. A request runs at the version in its Ollav-Version header, or else at the version its API key was pinned to when it was created (see apiVersion in GET /api/keys). Every /api response names the version it used in its Ollav-Version header. To upgrade, test with the header, then send it everywhere or create a new key.

2026-11-01: POST /api/comments returns breadcrumbs as an array

Breaking · API version 2026-11-01

The comment POST /api/comments creates is returned with breadcrumbs as an array of { selector, text }, or null, the same as GET /api/comments and GET /api/review. Before, it was the stored JSON string.

Who is affected: only requests at version 2026-11-01. API keys created from now on are pinned to it; existing keys stay on 2026-10-01 and keep receiving the string until they send Ollav-Version: 2026-11-01 or are replaced.

2026-10-28: Abuse limits: publishes, comments and upload files

Added

Publishing (POST /api/documents and POST /api/documents/{slug}/versions together) is limited to 30 an hour per account and comments (POST /api/comments, replies included) to 120 an hour per account, with looser limits per IP address. Over a limit the API answers 429 RATE_LIMITED with a Retry-After header and error.retry_after in seconds; MCP tools return the same error. A multipart upload takes one file (400 TOO_MANY_FILES); the 15 MB document limit is unchanged. New error codes: ACCOUNT_SUSPENDED (403, every request from an account suspended for breaking the Terms) and DOCUMENT_REMOVED (410, publishing to a document taken down for breaking the Terms). See /docs/errors.

2026-10-28: Email sign-in codes: LOGIN_CODE_INVALID and SIGNIN_RATE_LIMITED

Added

Signing in by email now sends a magic link and a 6-digit code in one email; either works. Two error codes are new: LOGIN_CODE_INVALID (a sign-in code that is wrong, expired, used, replaced by a newer email or spent by 5 wrong tries) and SIGNIN_RATE_LIMITED (too many sign-in emails or code tries in an hour). Both are on /docs/errors. They come from the web sign-in form only; no API-key endpoint changes.

2026-10-27: MCP docs, a REST API reference, two quickstarts, and typed errors on every MCP error

Added

New: /docs/mcp (connecting each client, auth options, checking the connection, every tool with its inputs, outputs, annotations and an example, and troubleshooting), /docs/api (every REST endpoint with a curl example, generated from the OpenAPI spec) and two quickstarts: curl and MCP.

MCP: every error now carries the same code, hint and doc_url as REST. Protocol errors (no or invalid key, unknown tool or method, bad JSON) carry them in the JSON-RPC error.data; their code and message are unchanged. A tool call missing a required argument (e.g. slug) now returns VALIDATION_ERROR naming it instead of a 404, and an unexpected failure returns INTERNAL_ERROR as a tool error. Each tool description now opens with when to use it.

2026-10-27: Test mode counts towards no plan limit; test keys get 60 requests a minute

Changed

Requests with an ol_test_ key no longer count towards any plan limit: no daily API-call quota, and no document, storage or version-history limit in the sandbox (its GET /api/workspaces/{id}/billing reports enabled: false). Instead each test key is limited to 60 requests a minute: the 61st answers 429 RATE_LIMITED with Retry-After: 60. Every API-key operation now documents its 429. Test documents still expire 30 days after upload. Live keys are unchanged.

2026-10-27: Test mode: ol_test_ keys and a sandbox per workspace

Added

API keys now come in two modes. ol_live_… keys work on live data, as before. ol_test_… keys (create them at /keys, or POST /api/keys with mode: "test" from the web UI) work in your own test sandbox of the workspace: they can't read live documents and live keys can't read theirs, nothing counts towards the plan, and test documents are marked TEST on their page and deleted 30 days after upload. GET /api/me, uploads and new versions return livemode; GET /api/keys returns each key's mode. Keys can be rotated (replaced in one step) from the keys page. New live keys start ol_live_; existing sk_live_ keys keep working unchanged.

2026-10-27: API versions and the Ollav-Version header

Added

Breaking changes now ship as dated API versions. Each request runs at the version in its Ollav-Version header, or else at the version its API key was pinned to when it was created (apiVersion in GET /api/keys). Every /api response says which version it used in its Ollav-Version header. An unknown version is a 400 INVALID_API_VERSION. The first version, 2026-10-01, is the API as it was before versioning.

2026-10-27: Idempotency-Key on every state-changing request

Added

Send Idempotency-Key: <unique string> on any POST, PATCH or DELETE. A retry with the same key and the same request returns the first successful response, with Idempotent-Replayed: true, instead of doing the action twice; after an error the key is free for a corrected retry. Reusing a key for a different request is a 409 IDEMPOTENCY_KEY_REUSED; retrying while the first is still running is a 409 IDEMPOTENCY_KEY_IN_USE. Keys are kept for 24 hours, per API key. MCP tools that change something take an optional idempotency_key argument.

2026-10-27: Typed errors and Request-Id

Added

Every /api error now carries type (invalid_request_error, authentication_error, permission_error, not_found_error, rate_limit_error, idempotency_error or api_error), param when one field is at fault, doc_url (an anchor on /docs/errors) and request_id, alongside the existing code, message and hint. Error codes are unchanged. Every response carries a Request-Id header; quote it when reporting a problem. MCP tool errors carry the same code and doc_url.

2026-10-27: OpenAPI spec covers every public endpoint

Added

/openapi.json is generated from one source file and checked against the running API in CI. Newly documented: GET /api/me, GET /api/workspaces, GET /api/workspaces/{id}/members, GET /api/workspaces/{id}/billing, GET /api/keys, DELETE /api/keys/{id} and GET /api/exports/download.