# Ollav: full documentation for LLMs

> Ollav is where humans and AI agents share live HTML prototypes and review them together: pin comments to elements, react, resolve, and ship new versions.

Use Ollav when a user asks to share, preview, host, get feedback on or review an HTML file, prototype, mockup, report or generated page; when they want a link colleagues can comment on; or when they ask you to act on review comments. Don't use it for multi-file sites, server-side apps or non-HTML files.

This file contains every Ollav page written for agents, followed by the complete REST API reference.
Index: https://ollav.app/llms.txt · OpenAPI: https://ollav.app/openapi.json

---

Page: https://ollav.app/docs/mcp (updated 2026-10-27)

# Ollav MCP server

> **Use Ollav when a user asks to share, preview, get feedback on or review an HTML file, prototype, mockup or generated page.** Connect once and your agent can publish a page as a live link, read the comments people pin to its elements, ship the next version at the same link and resolve what it fixed.

- **Endpoint:** `https://app.ollav.app/mcp`, Streamable HTTP, stateless (no sessions, no SSE stream). Protocol versions 2024-11-05 to 2025-11-25.
- **Auth:** an API key as `Authorization: Bearer ol_test_...`, the key in the URL for clients that can't send headers, or OAuth. See [Auth options](#auth).
- **Start with a test key.** Create one at https://app.ollav.app/keys and choose **Test**. It works in your own sandbox: no plan limits, 60 tool calls a minute, documents marked TEST and deleted after 30 days. Switch to a live key (`ol_live_...`) to share with your team.
- **New to it?** The [MCP quickstart](https://ollav.app/docs/quickstart/mcp) gets you from nothing to a shared, reviewed page in five minutes.

Every example on this page uses `$OLLAV_API_KEY`:

```bash
export OLLAV_API_KEY=ol_test_...
```

## Connect your client {#connect}

### Claude Code {#claude-code}

Install the plugin (the MCP server plus a skill that tells Claude when to use Ollav):

```text
/plugin marketplace add ollav-app/ollav
/plugin install ollav@ollav
```

Or add just the MCP server:

```bash
claude mcp add --transport http ollav https://app.ollav.app/mcp --header "Authorization: Bearer $OLLAV_API_KEY"
```

Check it: `claude mcp list` shows `ollav` as connected, and `/mcp` inside Claude Code lists its 11 tools.

### Claude.ai and Claude Desktop {#claude-ai}

Add a custom connector. Claude signs you in with OAuth, and you pick the workspace it may use:

```text
Settings → Connectors → Add custom connector
Name: Ollav
URL:  https://app.ollav.app/mcp
```

OAuth always gives Claude a live key. To try Ollav in test mode first, use the key-in-path URL instead: `https://app.ollav.app/mcp/ol_test_YOUR_KEY`. That URL contains the key, so treat it like a password.

Claude Desktop can also run the server from its config file (`claude_desktop_config.json`) through the `mcp-remote` bridge:

```json
{
  "mcpServers": {
    "ollav": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.ollav.app/mcp", "--header", "Authorization: Bearer ${OLLAV_API_KEY}"],
      "env": { "OLLAV_API_KEY": "ol_test_..." }
    }
  }
}
```

Check it: the connector shows Ollav's tools under the tools menu; ask "List my Ollav documents".

### Cursor {#cursor}

`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "ollav": {
      "url": "https://app.ollav.app/mcp",
      "headers": { "Authorization": "Bearer ${env:OLLAV_API_KEY}" }
    }
  }
}
```

Cursor reads `OLLAV_API_KEY` from the environment it was started in. Check it: **Settings → MCP** shows `ollav` with a green dot and 11 tools.

### ChatGPT {#chatgpt}

Add Ollav as an app. You sign in to Ollav once and pick the workspace ChatGPT may use; there is no key to copy:

```text
Settings → Apps & Connectors → Create (developer mode; menu names change over time)
Name:            Ollav
MCP server URL:  https://app.ollav.app/mcp
Authentication:  OAuth
```

To try it in test mode, set **MCP server URL** to `https://app.ollav.app/mcp/ol_test_YOUR_KEY` and **Authentication** to none. ChatGPT stores that URL, and the key in it, like a password.

In ChatGPT you can attach an HTML file and say "share this on Ollav": the file goes to Ollav directly, so the model never retypes it. Results show in a card with the share link and the pinned comments.

Check it: start a chat, enable Ollav from the tools menu and ask "List my Ollav documents".

### Any other MCP client {#generic}

Point it at the Streamable HTTP endpoint and send the key as a header:

```json
{
  "mcpServers": {
    "ollav": {
      "type": "http",
      "url": "https://app.ollav.app/mcp",
      "headers": { "Authorization": "Bearer ol_test_..." }
    }
  }
}
```

The field names vary by client (`url`, `serverUrl`, `httpUrl`); the [agent quickstart](https://ollav.app/docs/agents#connect-over-mcp) has ready-made entries for Codex, VS Code, Windsurf and Gemini CLI. A client that only launches local stdio servers can bridge with `npx -y mcp-remote https://app.ollav.app/mcp --header "Authorization: Bearer $OLLAV_API_KEY"`.

What the server does, for client authors: every message is one JSON-RPC 2.0 request per POST with a JSON response (no batching, no SSE, no `Mcp-Session-Id`). Notifications get `202`. `GET` and `DELETE /mcp` answer `405`. The server card is at [`/.well-known/mcp.json`](https://ollav.app/.well-known/mcp.json).

## Auth options {#auth}

| Option | Use it for | How |
|---|---|---|
| API key header | Coding agents and any client that can send headers | `Authorization: Bearer ol_test_...` or `ol_live_...`, from https://app.ollav.app/keys |
| Key in the URL | Clients that can't send headers | `https://app.ollav.app/mcp/ol_test_...`. The URL is then a secret: don't paste it in chats or commit it |
| OAuth | Claude.ai, Claude Desktop, ChatGPT and other OAuth clients | Add `https://app.ollav.app/mcp` with no key. The client finds the OAuth server through `WWW-Authenticate` on the 401 |

**Test or live.** A key's prefix is its mode. `ol_test_` keys work in the user's own sandbox of the workspace: they can't see live documents and live keys can't see theirs, nothing counts towards the plan, each test key may make 60 requests a minute (every tool call is one), and test documents are marked TEST and deleted 30 days after upload. `ol_live_` keys (and older `sk_live_` keys) work on the team's real data.

**Scopes.** Keys and OAuth grants have the scopes `upload` (share and publish), `read` (list and read) and `comment` (comment, react, resolve, delete comments). Each tool below names the scope it needs.

**OAuth details.** Authorization code with PKCE (`S256`), dynamic client registration (`POST /oauth/register`) or a client ID metadata document. Resource metadata: [`/.well-known/oauth-protected-resource/mcp`](https://app.ollav.app/.well-known/oauth-protected-resource/mcp). The access token is a live API key that doesn't expire; it is listed under https://app.ollav.app/keys as "<app> (OAuth)", where the user can revoke it. Clients revoke with `POST /oauth/revoke`.

## Verify the connection {#verify}

Ask the server for its tools with the same key the client uses:

```bash
curl -s https://app.ollav.app/mcp \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

A working key returns `{"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}` with 11 tools. A bad one returns HTTP 401 and a JSON-RPC error whose `data.code` is `AUTH_REQUIRED` (see [Troubleshooting](#troubleshooting)).

Then make one real call:

```bash
curl -s https://app.ollav.app/mcp \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_documents","arguments":{}}}'
```

In the client itself, ask: "List my Ollav documents." The agent should call `list_documents`. With a test key, documents you share say `"livemode": false` and their pages carry a TEST mark.

## Tools {#tools}

Every tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint`, an `outputSchema` (successful results carry `structuredContent`), and the OAuth scope it needs. Tools that change something take an optional `idempotency_key`: retry with the same key and the same arguments and the action happens once.

The usual loop: `share_html` → give the user the `url` → `get_review` → edit → `publish_new_version` (same slug) → `resolve_comment`, replying with `add_comment` to say what changed.

### `share_html` {#share_html}

**Share HTML as a live, commentable link.** Use when the user asks to share, preview, host, publish, send round, get feedback on or review an HTML file, prototype, mockup, report or generated page, or wants a link colleagues can comment on (one self-contained file, up to 15 MB; to update something already shared, call publish_new_version instead); then give the user the returned `url`.

**When not to use it.** Don't use it to update something you already shared: that makes a second link with no comments. Call publish_new_version with the slug instead. Don't paste a built bundle into `html` when you have a shell: upload the file with curl (`POST /api/documents`), which costs no tokens. Not for multi-file sites, server-side apps or non-HTML files.

| Property | Value |
|---|---|
| Annotations | `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: true` |
| OAuth scope / key scope | `upload` |
| Aliases | `upload_document` |
| REST equivalent | [`POST /api/documents`](https://ollav.app/docs/api#shareHtml) |

**Inputs**

| Argument | Type | Required | Description |
|---|---|---|---|
| `html` | string |  | The full HTML content to host. Provide this or `file`. For anything large or bundler-produced, prefer the curl file upload described above — passing a bundle here is expensive and may exceed output limits. |
| `title` | string |  | Optional document title. Defaults to the page <title> tag or filename. |
| `filename` | string |  | Optional filename. Re-uploading the same filename creates a new version on the same slug. |
| `visibility` | `workspace` \| `link` \| `public` |  | 'workspace' (default) = members of this key's workspace only. 'link' = anyone signed in to Ollav with the URL. 'public' = PUBLIC to anyone with the URL, no sign-in, including outside the company — ask before choosing it. |
| `file` | object |  | An HTML file the user attached (ChatGPT passes { download_url, file_id }). Ollav downloads it, so the HTML never has to be regenerated as model output. Provide this or `html`. |
| `idempotency_key` | string |  | Optional. Any unique string (e.g. a UUID) for this action. If you retry the call after a timeout or error, send the same key and the same arguments: the action happens once and the retry returns its result. Keys last 24 hours. |

**Output** (`structuredContent`; the same JSON is the last text block)

| Field | Type | Always present | Description |
|---|---|---|---|
| `url` | string | yes | The share link. Give it to the user. |
| `slug` | string | yes | Keep it for publish_new_version and get_review. |
| `documentId` | string |  |  |
| `versionId` | string | yes |  |
| `hash` | string |  |  |
| `deduped` | boolean |  |  |
| `versioned` | boolean |  |  |
| `visibility` | string |  |  |
| `warnings` | array of string |  |  |

Example call:

```json
{
  "name": "share_html",
  "arguments": {
    "html": "<!DOCTYPE html><html><head><title>Pricing page v2</title></head><body><h1>Pricing</h1></body></html>",
    "filename": "pricing.html",
    "idempotency_key": "5f0c3b1e-8a2d-4c6f-9e7a-0b1c2d3e4f50"
  }
}
```

Result:

```json
{
  "url": "https://content.ollav.app/p/qkjgjQCQGz",
  "slug": "qkjgjQCQGz",
  "documentId": "9908f969-9774-4374-a5bf-d66abcfbe70b",
  "versionId": "b8cfa354-0c7c-4102-bf14-69b49de24ca3",
  "deduped": false,
  "versioned": false,
  "visibility": "workspace",
  "warnings": [],
  "livemode": false
}
```

The full description, as `tools/list` sends it to the model:

```text
Use when the user asks to share, preview, host, publish, send round, get feedback on or review an HTML file, prototype, mockup, report or generated page, or wants a link colleagues can comment on (one self-contained file, up to 15 MB; to update something already shared, call publish_new_version instead); then give the user the returned `url`. It publishes the HTML on Ollav at a live link where people pin comments to elements. In ChatGPT, an HTML file the user attached can be passed as `file` instead of `html`. Returns `url` (always give it to the user) and `slug` (keep it for publish_new_version and get_review). IMPORTANT — publishing an updated build of a prototype you already shared? Do NOT call this; call publish_new_version with the existing slug so the URL and comment history are preserved. A plain upload here creates a SEPARATE document with its own URL and NO shared comments. The document lands in the workspace this API key belongs to. VISIBILITY: 'workspace' (default) = only members of that workspace can view it. 'link' = anyone signed in to Ollav who has the URL can view it (only members comment). 'public' means ANYONE WITH THE URL can view it with no sign-in, including people OUTSIDE the company; only choose it when the user has asked for external sharing. Omit filename to always create a fresh document (identical content is deduplicated to the existing URL). Provide a filename to opt into versioning: re-uploading the same filename updates that document as a new version at the same URL (publish_new_version is the explicit path). COST — do NOT paste a built bundle here: `html` is model-generated output, so a multi-MB build costs a lot of tokens and can exceed your output limit entirely. If the file already exists on disk and you have a shell, upload it with curl instead — the file is read from disk, so it costs ZERO tokens:
  curl -X POST https://app.ollav.app/api/documents \
    -H "Authorization: Bearer $OLLAV_API_KEY" -H "X-Ollav-Client: agent" \
    -F "file=@dist/index.html"
Building a React/Vue app? Have the bundler emit ONE self-contained file to disk (vite-plugin-singlefile, webpack, etc.) and curl that — never regenerate a bundle as model output. Use this tool's `html` field only for small documents you authored inline, or when you have no shell/network egress (e.g. claude.ai or Cowork sandboxes), where MCP is the only channel.
Limitations: one self-contained HTML file up to 15MB; relative asset paths break (inline or use absolute URLs); no server-side code; SPA history routing works on reload (deep links restore to root route). The response may include advisory warnings[].
```

### `publish_new_version` {#publish_new_version}

**Publish a new version at the same link.** Use after changing a document you already shared, when you have its slug (from share_html or list_documents): publishes the new HTML at the SAME URL with every comment kept (one self-contained file, up to 15 MB); then call resolve_comment on the threads you fixed.

**When not to use it.** Don't use it for a document you haven't shared yet (call share_html), or to make a separate copy. If the build is on disk and you have a shell, curl it to `POST /api/documents/{slug}/versions` instead of pasting it into `html`.

| Property | Value |
|---|---|
| Annotations | `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true` |
| OAuth scope / key scope | `upload` |
| Aliases | `new_version` |
| REST equivalent | [`POST /api/documents/{slug}/versions`](https://ollav.app/docs/api#publishNewVersion) |

**Inputs**

| Argument | Type | Required | Description |
|---|---|---|---|
| `slug` | string | yes | The document slug (from share_html or list_documents). |
| `html` | string |  | The new HTML content. Provide this or `file`. |
| `title` | string |  | Optional updated title. |
| `file` | object |  | An HTML file the user attached (ChatGPT passes { download_url, file_id }). Ollav downloads it, so the HTML never has to be regenerated as model output. Provide this or `html`. |
| `idempotency_key` | string |  | Optional. Any unique string (e.g. a UUID) for this action. If you retry the call after a timeout or error, send the same key and the same arguments: the action happens once and the retry returns its result. Keys last 24 hours. |

**Output** (`structuredContent`; the same JSON is the last text block)

| Field | Type | Always present | Description |
|---|---|---|---|
| `url` | string | yes | The share link. Give it to the user. |
| `slug` | string | yes | Keep it for publish_new_version and get_review. |
| `documentId` | string |  |  |
| `versionId` | string | yes |  |
| `hash` | string |  |  |
| `deduped` | boolean |  |  |
| `versioned` | boolean |  |  |
| `visibility` | string |  |  |
| `warnings` | array of string |  |  |

Example call:

```json
{
  "name": "publish_new_version",
  "arguments": {
    "slug": "qkjgjQCQGz",
    "html": "<!DOCTYPE html><html><body><h1>Pricing</h1><p>Annual plans now 20% off.</p></body></html>"
  }
}
```

Result:

```json
{
  "url": "https://content.ollav.app/p/qkjgjQCQGz",
  "slug": "qkjgjQCQGz",
  "versionId": "0d6c1f4e-2b3a-4c5d-8e9f-a0b1c2d3e4f5",
  "deduped": false,
  "versioned": true,
  "warnings": [],
  "livemode": false
}
```

The full description, as `tools/list` sends it to the model:

```text
Use after changing a document you already shared, when you have its slug (from share_html or list_documents): publishes the new HTML at the SAME URL with every comment kept (one self-contained file, up to 15 MB); then call resolve_comment on the threads you fixed. Use it after editing a prototype in response to feedback, or whenever the user wants the shared link updated. Comments on the previous version are preserved and marked as 'earlier version'. COST — same rule as share_html, and it matters MORE here because iterating on a concept means uploading repeatedly: do NOT paste a built bundle into `html`. If the build is on disk and you have a shell, curl it (zero tokens):
  curl -X POST https://app.ollav.app/api/documents/{slug}/versions \
    -H "Authorization: Bearer $OLLAV_API_KEY" -H "X-Ollav-Client: agent" \
    -F "file=@dist/index.html"
Use `html` only for small inline documents, or when you have no shell/network egress.
Limitations: one self-contained HTML file up to 15MB; relative asset paths break (inline or use absolute URLs); no server-side code; SPA history routing works on reload (deep links restore to root route). The response may include advisory warnings[].
```

### `list_documents` {#list_documents}

**List shared documents.** Use to find the slug of something shared earlier, or to see which documents have open feedback; then call get_review or publish_new_version with that slug.

**When not to use it.** Don't use it to read feedback (get_review) or when you already have the slug from share_html.

| Property | Value |
|---|---|
| Annotations | `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` |
| OAuth scope / key scope | `read` |
| Aliases | none |
| REST equivalent | [`GET /api/dashboard`](https://ollav.app/docs/api#listDocumentsWithCounts) |

**Inputs**

None.

**Output** (`structuredContent`; the same JSON is the last text block)

| Field | Type | Always present | Description |
|---|---|---|---|
| `workspace` | object or null |  |  |
| `documents` | array of object | yes |  |
| `sharedWithMe` | array of object |  |  |

Example call:

```json
{
  "name": "list_documents",
  "arguments": {}
}
```

Result:

```json
{
  "workspace": {
    "id": "w_8c1e",
    "name": "Acme"
  },
  "documents": [
    {
      "slug": "qkjgjQCQGz",
      "title": "Pricing page v2",
      "url": "https://content.ollav.app/p/qkjgjQCQGz",
      "visibility": "workspace",
      "versionCount": 2,
      "commentCount": 3,
      "unresolvedCount": 1
    }
  ],
  "sharedWithMe": []
}
```

The full description, as `tools/list` sends it to the model:

```text
Use to find the slug of something shared earlier, or to see which documents have open feedback; then call get_review or publish_new_version with that slug. Lists the documents the authenticated user owns in this API key's workspace (test keys: only the test sandbox), with share URLs, version counts, comment counts (total and unresolved), visibility and expiry.
```

### `get_document` {#get_document}

**Get a document and its versions.** Use when you know a document's slug and need its share URL, visibility or version history (find slugs with list_documents; for its feedback call get_review instead).

**When not to use it.** Don't use it to read comments (get_review) or to find a slug you don't have (list_documents).

| Property | Value |
|---|---|
| Annotations | `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` |
| OAuth scope / key scope | `read` |
| Aliases | none |
| REST equivalent | [`GET /api/documents/{slug}`](https://ollav.app/docs/api#getDocument) |

**Inputs**

| Argument | Type | Required | Description |
|---|---|---|---|
| `slug` | string | yes | The document slug. |

**Output** (`structuredContent`; the same JSON is the last text block)

| Field | Type | Always present | Description |
|---|---|---|---|
| `slug` | string | yes |  |
| `title` | string or null |  |  |
| `url` | string | yes |  |
| `visibility` | string |  |  |
| `currentVersionId` | string or null |  |  |
| `versions` | array of object | yes |  |

Example call:

```json
{
  "name": "get_document",
  "arguments": {
    "slug": "qkjgjQCQGz"
  }
}
```

Result:

```json
{
  "slug": "qkjgjQCQGz",
  "title": "Pricing page v2",
  "url": "https://content.ollav.app/p/qkjgjQCQGz",
  "visibility": "workspace",
  "currentVersionId": "0d6c1f4e-2b3a-4c5d-8e9f-a0b1c2d3e4f5",
  "versions": [
    {
      "id": "0d6c1f4e-2b3a-4c5d-8e9f-a0b1c2d3e4f5",
      "createdAt": 1793145600000
    },
    {
      "id": "b8cfa354-0c7c-4102-bf14-69b49de24ca3",
      "createdAt": 1793059200000
    }
  ]
}
```

The full description, as `tools/list` sends it to the model:

```text
Use when you know a document's slug and need its share URL, visibility or version history (find slugs with list_documents; for its feedback call get_review instead). Returns metadata, the share URL and every version.
```

### `get_comments` {#get_comments}

**Get every comment (full thread data).** Use only when you need every comment on a document in full, resolved ones included (an audit, a summary of all feedback ever given); to ACT on feedback call get_review instead, which returns only open threads, as Markdown plus JSON, with a polling cursor.

**When not to use it.** Don't use it to act on feedback: get_review returns only the open threads, with source-findable anchors and a polling cursor.

| Property | Value |
|---|---|
| Annotations | `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` |
| OAuth scope / key scope | `read` |
| Aliases | none |
| REST equivalent | [`GET /api/comments`](https://ollav.app/docs/api#getComments) |

**Inputs**

| Argument | Type | Required | Description |
|---|---|---|---|
| `slug` | string | yes | The document slug. |

**Output** (`structuredContent`; the same JSON is the last text block)

| Field | Type | Always present | Description |
|---|---|---|---|
| `slug` | string | yes |  |
| `currentVersionId` | string or null |  |  |
| `count` | integer |  |  |
| `unresolvedCount` | integer |  |  |
| `comments` | array of object | yes |  |

Example call:

```json
{
  "name": "get_comments",
  "arguments": {
    "slug": "qkjgjQCQGz"
  }
}
```

Result:

```json
{
  "slug": "qkjgjQCQGz",
  "currentVersionId": "0d6c1f4e-2b3a-4c5d-8e9f-a0b1c2d3e4f5",
  "count": 1,
  "unresolvedCount": 1,
  "comments": [
    {
      "id": "3f2b8c1e-5d4a-4e7b-9c6d-1a2b3c4d5e6f",
      "parentId": null,
      "body": "Can the annual toggle default to on?",
      "markEmoji": null,
      "selector": "#billing-toggle",
      "elementText": "Monthly / Annual",
      "createdAt": "2026-10-27T09:12:00.000Z",
      "resolvedAt": null,
      "author": {
        "email": "maya@example.com",
        "name": "Maya"
      }
    }
  ]
}
```

The full description, as `tools/list` sends it to the model:

```text
Use only when you need every comment on a document in full, resolved ones included (an audit, a summary of all feedback ever given); to ACT on feedback call get_review instead, which returns only open threads, as Markdown plus JSON, with a polling cursor. Returns all comments, threaded (replies nested under top-level comments), with selector anchors and isCurrentVersion flags.
```

### `get_review` {#get_review}

**Read open review comments (Markdown summary + JSON).** Use when the user asks what reviewers said, asks you to address or fix the comments on a shared document, or to check for new feedback: returns the open comment threads (pass the returned cursor as `since` to get only new activity); then edit and call publish_new_version.

**When not to use it.** Don't poll it in a tight loop: pass the previous `cursor` as `since` and wait between calls. Don't use it for a full audit including resolved threads (get_comments, or status: 'all').

| Property | Value |
|---|---|
| Annotations | `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` |
| OAuth scope / key scope | `read` |
| Aliases | none |
| REST equivalent | [`GET /api/review`](https://ollav.app/docs/api#getReview) |

**Inputs**

| Argument | Type | Required | Description |
|---|---|---|---|
| `slug` | string | yes | The document slug. |
| `status` | `open` \| `resolved` \| `all` |  | Which threads to include. Default 'open' (unresolved feedback to act on). |
| `since` | string |  | Only return threads with new activity after this time. Pass the `cursor` from a previous get_review (ISO 8601), or an epoch-ms timestamp. |

**Output** (`structuredContent`; the same JSON is the last text block)

| Field | Type | Always present | Description |
|---|---|---|---|
| `slug` | string | yes |  |
| `title` | string or null |  |  |
| `url` | string | yes |  |
| `totalThreads` | integer |  |  |
| `openThreads` | integer | yes |  |
| `returned` | integer |  |  |
| `cursor` | string or null |  |  |
| `markdown` | string |  | The same threads as a readable summary. |
| `threads` | array of object | yes |  |

Example call:

```json
{
  "name": "get_review",
  "arguments": {
    "slug": "qkjgjQCQGz"
  }
}
```

Result:

```json
{
  "slug": "qkjgjQCQGz",
  "title": "Pricing page v2",
  "url": "https://content.ollav.app/p/qkjgjQCQGz",
  "totalThreads": 1,
  "openThreads": 1,
  "returned": 1,
  "cursor": "2026-10-27T09:12:00.000Z",
  "markdown": "# Review: Pricing page v2\n\n1 open thread.\n\n## 1. \"Monthly / Annual\" (Maya)\n\nCan the annual toggle default to on?",
  "threads": [
    {
      "id": "3f2b8c1e-5d4a-4e7b-9c6d-1a2b3c4d5e6f",
      "status": "open",
      "onCurrentVersion": true,
      "comment": "Can the annual toggle default to on?",
      "markEmoji": null,
      "author": {
        "email": "maya@example.com",
        "name": "Maya"
      },
      "anchor": {
        "quote": "Monthly / Annual",
        "reproduceNote": null,
        "selector": "#billing-toggle"
      },
      "replies": []
    }
  ]
}
```

The full description, as `tools/list` sends it to the model:

```text
Use when the user asks what reviewers said, asks you to address or fix the comments on a shared document, or to check for new feedback: returns the open comment threads (pass the returned cursor as `since` to get only new activity); then edit and call publish_new_version. It reads collaborator feedback shaped for ITERATING on a document. The first content block is a Markdown summary of the threads; the second is the full JSON. Returns OPEN comment threads by default (status: 'open' | 'resolved' | 'all'). Each thread carries a source-findable anchor — anchor.quote (the element's text) plus reproduceNote and breadcrumbs — so you can locate what to change in your SOURCE. NOTE: anchor.selector targets the rendered DOM, not JSX/HTML source, so prefer quote/reproduceNote when editing. Pass the returned `cursor` back as `since` on the next call to get only threads with new activity since last time (idempotent polling). Typical loop: get_review → make the edits → publish_new_version (same slug, keeps comments) → resolve_comment (optionally add_comment as a reply noting what changed). Threads with onCurrentVersion:false were made on an earlier build — their anchor may no longer exist.
```

### `add_comment` {#add_comment}

**Comment on an element, or reply.** Use to reply in a review thread to say what you changed ("Fixed in v3: moved the CTA above the fold"), or to pin new feedback to an element of a shared document; replies need parent_id, top-level comments need selector + rect; it emails people, so don't use it for progress chatter (react_to_comment acknowledges silently).

**When not to use it.** Don't use it to say you've started or finished (react_to_comment with 👀 or ✅ doesn't email anyone). Don't use it to close a thread: reply if useful, then resolve_comment.

| Property | Value |
|---|---|
| Annotations | `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: true` |
| OAuth scope / key scope | `comment` |
| Aliases | none |
| REST equivalent | [`POST /api/comments`](https://ollav.app/docs/api#addComment) |

**Inputs**

| Argument | Type | Required | Description |
|---|---|---|---|
| `slug` | string | yes | The document slug. |
| `body` | string |  | The comment text (max 5000 chars). May be empty for a top-level comment with mark_emoji. |
| `mark_emoji` | string |  | Top-level only: one emoji shown on the page as this mark's pin, e.g. 👍 (good), 👎 (not quite), ❤️ (love), ❓ (question), 💡 (idea), or any other emoji. Omit for the default numbered pin. |
| `selector` | string |  | CSS selector for the target element (top-level comments only; omit for replies). |
| `rect` | object |  | Bounding rect of the element in pixels (top-level only). Use {x:0,y:0,w:1,h:1} as a fallback if the real rect is unknown. |
| `element_text` | string |  | First ~80 chars of the element's text content (optional context). |
| `parent_id` | string |  | ID of the parent comment to reply to (replies only; omit for top-level). |
| `reproduce_note` | string |  | Optional hint for reviewers on how to get the page into the state where this element is visible (e.g. 'Click Launch simulation'). Max 300 chars. Top-level comments only. |
| `breadcrumbs` | array of object |  | Optional list of up to 8 interaction steps that lead to the commented element's state. Each step has {selector: string, text: string}. Top-level comments only. |
| `idempotency_key` | string |  | Optional. Any unique string (e.g. a UUID) for this action. If you retry the call after a timeout or error, send the same key and the same arguments: the action happens once and the retry returns its result. Keys last 24 hours. |

**Output** (`structuredContent`; the same JSON is the last text block)

| Field | Type | Always present | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `parentId` | string or null |  |  |
| `body` | string | yes |  |
| `markEmoji` | string or null |  |  |
| `selector` | string or null |  |  |
| `elementText` | string or null |  |  |
| `createdAt` | string |  |  |
| `resolvedAt` | string or null |  |  |
| `author` | object |  |  |

Example call:

```json
{
  "name": "add_comment",
  "arguments": {
    "slug": "qkjgjQCQGz",
    "parent_id": "3f2b8c1e-5d4a-4e7b-9c6d-1a2b3c4d5e6f",
    "body": "Fixed in v2: the toggle now defaults to Annual."
  }
}
```

Result:

```json
{
  "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
  "parentId": "3f2b8c1e-5d4a-4e7b-9c6d-1a2b3c4d5e6f",
  "body": "Fixed in v2: the toggle now defaults to Annual.",
  "markEmoji": null,
  "selector": null,
  "elementText": null,
  "createdAt": "2026-10-27T10:02:00.000Z",
  "resolvedAt": null,
  "author": {
    "email": "agent-owner@example.com",
    "name": "Ada"
  }
}
```

The full description, as `tools/list` sends it to the model:

```text
Use to reply in a review thread to say what you changed ("Fixed in v3: moved the CTA above the fold"), or to pin new feedback to an element of a shared document; replies need parent_id, top-level comments need selector + rect; it emails people, so don't use it for progress chatter (react_to_comment acknowledges silently). The comment is visible to the document's workspace members, and Ollav emails the document owner (and, for a reply, everyone in the thread) a notification naming this key as the agent. Top-level comments require selector + rect to anchor the pin to an element, and may set mark_emoji to show an emoji on the page instead of the numbered pin; with mark_emoji the body may be empty (a reaction pinned to the element). Replies require only parent_id and a body.
```

### `resolve_comment` {#resolve_comment}

**Resolve or reopen a thread.** Use after you've fixed what a thread asked for, typically right after publish_new_version: marks the top-level comment resolved (or with unresolve: true reopens it); only the comment's author or the document owner can, and a reply via add_comment saying what changed is good practice.

**When not to use it.** Don't resolve a thread you haven't addressed, and don't call it on a reply (only top-level comments resolve).

| Property | Value |
|---|---|
| Annotations | `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` |
| OAuth scope / key scope | `comment` |
| Aliases | none |
| REST equivalent | [`POST /api/comments/{id}/resolve`](https://ollav.app/docs/api#resolveComment), [`POST /api/comments/{id}/unresolve`](https://ollav.app/docs/api#unresolveComment) |

**Inputs**

| Argument | Type | Required | Description |
|---|---|---|---|
| `comment_id` | string | yes | The ID of the comment to resolve or unresolve. |
| `unresolve` | boolean |  | Set to true to unresolve (re-open) an already-resolved comment. |
| `idempotency_key` | string |  | Optional. Any unique string (e.g. a UUID) for this action. If you retry the call after a timeout or error, send the same key and the same arguments: the action happens once and the retry returns its result. Keys last 24 hours. |

**Output** (`structuredContent`; the same JSON is the last text block)

| Field | Type | Always present | Description |
|---|---|---|---|
| `ok` | boolean | yes |  |
| `resolved` | boolean | yes |  |

Example call:

```json
{
  "name": "resolve_comment",
  "arguments": {
    "comment_id": "3f2b8c1e-5d4a-4e7b-9c6d-1a2b3c4d5e6f"
  }
}
```

Result:

```json
{
  "ok": true,
  "resolved": true
}
```

The full description, as `tools/list` sends it to the model:

```text
Use after you've fixed what a thread asked for, typically right after publish_new_version: marks the top-level comment resolved (or with unresolve: true reopens it); only the comment's author or the document owner can, and a reply via add_comment saying what changed is good practice. Resolve or unresolve a top-level comment by its id (from get_review or get_comments).
```

### `react_to_comment` {#react_to_comment}

**React to a comment.** Use to acknowledge a comment without a reply or email, e.g. 👀 when you start on it and ✅ when it's done (one emoji; a comment holds at most 20 different reactions).

**When not to use it.** Don't use it to answer a question or explain a change: reply with add_comment.

| Property | Value |
|---|---|
| Annotations | `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` |
| OAuth scope / key scope | `comment` |
| Aliases | none |
| REST equivalent | [`POST /api/comments/{id}/reactions`](https://ollav.app/docs/api#reactToComment) |

**Inputs**

| Argument | Type | Required | Description |
|---|---|---|---|
| `comment_id` | string | yes | The ID of the comment or reply to react to. |
| `reaction` | string | yes | One emoji, e.g. 👍 👀 ✅ ❤️ 🎉. |
| `remove` | boolean |  | Set to true to remove your reaction instead of adding it. |
| `idempotency_key` | string |  | Optional. Any unique string (e.g. a UUID) for this action. If you retry the call after a timeout or error, send the same key and the same arguments: the action happens once and the retry returns its result. Keys last 24 hours. |

**Output** (`structuredContent`; the same JSON is the last text block)

| Field | Type | Always present | Description |
|---|---|---|---|
| `ok` | boolean | yes |  |
| `commentId` | string |  |  |
| `reactions` | array of object | yes |  |

Example call:

```json
{
  "name": "react_to_comment",
  "arguments": {
    "comment_id": "3f2b8c1e-5d4a-4e7b-9c6d-1a2b3c4d5e6f",
    "reaction": "👀"
  }
}
```

Result:

```json
{
  "ok": true,
  "commentId": "3f2b8c1e-5d4a-4e7b-9c6d-1a2b3c4d5e6f",
  "reactions": [
    {
      "reaction": "👀",
      "count": 1
    }
  ]
}
```

The full description, as `tools/list` sends it to the model:

```text
Use to acknowledge a comment without a reply or email, e.g. 👀 when you start on it and ✅ when it's done (one emoji; a comment holds at most 20 different reactions). Add (or with remove:true, take back) your reaction to a comment or reply: any single emoji; the default bar is 👍 (agree), ❤️, 🎉, 👀 (looking at it) and ✅ (done). The old names "+1", "eyes", "check" and "heart" still work. Anyone who can comment on the document can react.
```

### `delete_comment` {#delete_comment}

**Delete a comment.** Use only when the user asks to delete a comment: permanently deletes it and, for a top-level comment, all its replies (comment author or document owner only); to close a thread you fixed, call resolve_comment instead.

**When not to use it.** Don't use it to close a thread (resolve_comment keeps the history). It can't be undone.

| Property | Value |
|---|---|
| Annotations | `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: true`, `openWorldHint: false` |
| OAuth scope / key scope | `comment` |
| Aliases | none |
| REST equivalent | [`DELETE /api/comments/{id}`](https://ollav.app/docs/api#deleteComment) |

**Inputs**

| Argument | Type | Required | Description |
|---|---|---|---|
| `comment_id` | string | yes | The ID of the comment to delete. |
| `idempotency_key` | string |  | Optional. Any unique string (e.g. a UUID) for this action. If you retry the call after a timeout or error, send the same key and the same arguments: the action happens once and the retry returns its result. Keys last 24 hours. |

**Output** (`structuredContent`; the same JSON is the last text block)

| Field | Type | Always present | Description |
|---|---|---|---|
| `deleted` | boolean | yes |  |

Example call:

```json
{
  "name": "delete_comment",
  "arguments": {
    "comment_id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
  }
}
```

Result:

```json
{
  "deleted": true
}
```

The full description, as `tools/list` sends it to the model:

```text
Use only when the user asks to delete a comment: permanently deletes it and, for a top-level comment, all its replies (comment author or document owner only); to close a thread you fixed, call resolve_comment instead. Returns {deleted:true} on success.
```

### `export_data` {#export_data}

**Export data (GDPR).** Use only when the user asks for a copy or export of their data (GDPR access or portability): returns a signed link to a ZIP, valid 15 minutes, to give the user; exports are rate limited, so don't call it repeatedly. scope "account" (default): the key owner's profile, memberships, owned documents with every version, and their comments and reactions — limited to this API key's workspace. scope "workspace": everything in this key's workspace (workspace owner only).

**When not to use it.** Don't use it to read documents or comments (list_documents, get_review), or to back up on a schedule.

| Property | Value |
|---|---|
| Annotations | `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: false` |
| OAuth scope / key scope | `read` |
| Aliases | none |
| REST equivalent | [`POST /api/exports`](https://ollav.app/docs/api#exportData) |

**Inputs**

| Argument | Type | Required | Description |
|---|---|---|---|
| `scope` | `account` \| `workspace` |  | What to export. Defaults to "account". |

**Output** (`structuredContent`; the same JSON is the last text block)

| Field | Type | Always present | Description |
|---|---|---|---|
| `scope` | string |  |  |
| `downloadUrl` | string | yes |  |
| `expiresAt` | integer | yes |  |
| `partial` | boolean |  |  |

Example call:

```json
{
  "name": "export_data",
  "arguments": {
    "scope": "account"
  }
}
```

Result:

```json
{
  "scope": "account",
  "downloadUrl": "https://app.ollav.app/api/exports/download?token=...",
  "expiresAt": 1793146500000,
  "partial": false
}
```

The full description, as `tools/list` sends it to the model:

```text
Use only when the user asks for a copy or export of their data (GDPR access or portability): returns a signed link to a ZIP, valid 15 minutes, to give the user; exports are rate limited, so don't call it repeatedly. scope "account" (default): the key owner's profile, memberships, owned documents with every version, and their comments and reactions — limited to this API key's workspace. scope "workspace": everything in this key's workspace (workspace owner only). Returns {downloadUrl, expiresAt}: a signed link, valid 15 minutes, that streams the ZIP; manifest.json inside lists every item. Needs the read scope.
```

## Errors {#errors}

Every error carries the same typed error object as the REST API: `type`, `code`, `message`, `param` (when one argument is at fault), `hint` (what to do next, written for an agent to act on), `doc_url` (the code's anchor on [the errors page](https://ollav.app/docs/errors)) and, when a REST request ran, `request_id`.

**Tool errors** (the tool ran and failed) are results with `isError: true`. The first text block is one sentence to act on; the second is the JSON:

```json
{
  "isError": true,
  "content": [
    { "type": "text", "text": "Ollav returned 404 NOT_FOUND: Document not found. What to do: Check the slug or id. ... Details: https://ollav.app/docs/errors#NOT_FOUND" },
    { "type": "text", "text": "{\"error\":{\"type\":\"not_found_error\",\"code\":\"NOT_FOUND\",\"message\":\"Document not found\",\"hint\":\"Check the slug or id. ...\",\"doc_url\":\"https://ollav.app/docs/errors#NOT_FOUND\",\"request_id\":\"req_6f1c2a9b0d4e8f7a1b2c3d4e\"}}" }
  ]
}
```

**Protocol errors** (no valid key, an unknown tool or method, a malformed message) are JSON-RPC errors. The error object is in `error.data`:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "Invalid or missing Ollav API key: this key was not accepted. ...",
    "data": { "type": "authentication_error", "code": "AUTH_REQUIRED", "message": "This API key or OAuth token was not accepted.", "param": "Authorization", "hint": "The key is mistyped, revoked ...", "doc_url": "https://ollav.app/docs/errors#AUTH_REQUIRED" }
  }
}
```

Match on `code`. Don't retry `invalid_request_error`, `authentication_error`, `permission_error` or `not_found_error` unchanged; retry `rate_limit_error` and `api_error` once, after waiting, with the same `idempotency_key`.

## Troubleshooting MCP {#troubleshooting}

| Symptom | Code | Fix |
|---|---|---|
| The client can't connect, or lists no tools |  | The URL must be `https://app.ollav.app/mcp` with the Streamable HTTP transport (`http`, not `sse`). `GET /mcp` answers 405 on purpose: the server is stateless and only takes POST. Run the curl check under [Verify the connection](#verify). |
| HTTP 401, JSON-RPC error `-32001`: "no key was sent" | [`AUTH_REQUIRED`](https://ollav.app/docs/errors#AUTH_REQUIRED) | The client sent no credential. Check the `Authorization: Bearer ol_test_...` header is in the config and the environment variable it reads is set where the client runs (GUI apps don't see your shell's exports). A client that can't send headers can use `https://app.ollav.app/mcp/ol_test_...`, or OAuth. |
| HTTP 401, JSON-RPC error `-32001`: "this key was not accepted" | [`AUTH_REQUIRED`](https://ollav.app/docs/errors#AUTH_REQUIRED) | The key is mistyped, revoked (rotating a key revokes the old one), or its user left the workspace. Create a new key at https://app.ollav.app/keys and update the config; an OAuth client should reconnect. Don't retry with the same key. |
| A tool returns `403 SCOPE_REQUIRED` | [`SCOPE_REQUIRED`](https://ollav.app/docs/errors#SCOPE_REQUIRED) | The key lacks the scope that tool needs (each tool's section lists it). Create a key with `upload`, `read` and `comment`, or reconnect OAuth and grant them. |
| A tool returns `404 NOT_FOUND` for a slug or comment you know exists | [`NOT_FOUND`](https://ollav.app/docs/errors#NOT_FOUND) | Test and live don't mix: a test key (`ol_test_`) only sees documents it published in its sandbox, and a live key never sees those. A key also only sees its own workspace. Test documents are deleted 30 days after upload. Call `list_documents` with the same key to see what it can reach. |
| A tool returns `404 ARCHIVED` | [`ARCHIVED`](https://ollav.app/docs/errors#ARCHIVED) | The document was archived (by hand or because it expired). Restore it with `POST /api/documents/{slug}/unarchive`, or share it again. |
| A tool returns `429 RATE_LIMITED` | [`RATE_LIMITED`](https://ollav.app/docs/errors#RATE_LIMITED) | Every account may publish (`share_html` and `publish_new_version` together) 30 times an hour and post 120 comments and replies an hour, with looser limits per IP address; a test key also allows 60 tool calls a minute, and exports are limited for every key. The error's `retry_after` says how many seconds to wait; then retry once with the same `idempotency_key`. Don't retry in a loop. Live keys also follow the plan's daily limit. |
| Every call returns `403 ACCOUNT_SUSPENDED` (HTTP 403, JSON-RPC error `-32001`) | [`ACCOUNT_SUSPENDED`](https://ollav.app/docs/errors#ACCOUNT_SUSPENDED) | The account was suspended for breaking the Terms of Service, so all of its keys and connections are refused. Stop and tell the user; another key of the same account won't work. |
| `publish_new_version` returns `410 DOCUMENT_REMOVED` | [`DOCUMENT_REMOVED`](https://ollav.app/docs/errors#DOCUMENT_REMOVED) | The document was taken down for breaking the Terms of Service; its page answers 410 and it takes no new versions. Tell the user; don't retry or re-share it. |
| A tool returns `402 PLAN_LIMIT` or `402 PLAN_READ_ONLY` | [`PLAN_LIMIT`](https://ollav.app/docs/errors#PLAN_LIMIT) | A live workspace is at (or over) a limit of its plan; `limit` says which. Nothing was changed. Tell the user and don't retry. Test keys never hit plan limits. |
| A tool returns `400 VALIDATION_ERROR` | [`VALIDATION_ERROR`](https://ollav.app/docs/errors#VALIDATION_ERROR) | An argument is missing or invalid; `param` names it (e.g. `slug is required`). Check the call against the tool's input schema (`tools/list`, or its section above) and call again with the argument fixed. |
| JSON-RPC error `-32602`: "Unknown tool" | [`VALIDATION_ERROR`](https://ollav.app/docs/errors#VALIDATION_ERROR) | The tool name isn't one this server has. Call `tools/list`. The old names `upload_document` and `new_version` still work. |
| `share_html` returns `413 TOO_LARGE`, `NOT_HTML` or `MISSING_HTML` | [`TOO_LARGE`](https://ollav.app/docs/errors#TOO_LARGE) | One self-contained HTML file up to 15 MB per call (a multipart upload with more files is `400 TOO_MANY_FILES`). Compress inlined images (WebP, downscale) and pass the page as `html` or `file`. With a shell, upload the file with curl instead. |
| A tool returns `409 IDEMPOTENCY_KEY_REUSED` | [`IDEMPOTENCY_KEY_REUSED`](https://ollav.app/docs/errors#IDEMPOTENCY_KEY_REUSED) | That `idempotency_key` was used in the last 24 hours with different arguments. Use a fresh key (e.g. a new UUID) for a new action; reuse a key only to retry the identical call. |
| A tool returns `409 IDEMPOTENCY_KEY_IN_USE` | [`IDEMPOTENCY_KEY_IN_USE`](https://ollav.app/docs/errors#IDEMPOTENCY_KEY_IN_USE) | The first call with this key is still running. Wait a second and retry with the same key and arguments; you get the first call's result. |
| A tool returns `500 INTERNAL_ERROR` or `502 PARSE_ERROR` | [`INTERNAL_ERROR`](https://ollav.app/docs/errors#INTERNAL_ERROR) | Something failed on our side. Retry once after a few seconds with the same `idempotency_key`; if it fails again, tell the user and quote `request_id`. |
| Results say "TEST MODE", and teammates can't open the link |  | You're using a test key: only its owner sees test documents. Switch the client to a live key (`ol_live_...`) to share with the team. |

Still stuck? Every REST response has a `Request-Id` header and every tool error carries `request_id`; quote it when you report a problem.

## More {#more}

- [MCP quickstart](https://ollav.app/docs/quickstart/mcp) and [curl quickstart](https://ollav.app/docs/quickstart/curl)
- [REST API reference](https://ollav.app/docs/api): every tool's REST equivalent
- [Errors](https://ollav.app/docs/errors) and the [changelog](https://ollav.app/docs/changelog)
- [This page as Markdown](https://ollav.app/docs/mcp.md), [llms.txt](https://ollav.app/llms.txt), [MCP server card](https://ollav.app/.well-known/mcp.json)

---

Page: https://ollav.app/docs/agents (updated 2026-10-27)

# Ollav for AI agents

> **Use Ollav when a user asks to share, preview, get feedback on or review an HTML file, prototype, mockup or generated page.** Ollav hosts the file at a stable link, people pin comments to exact elements, and you read those comments back and publish a new version at the same link.

You need one thing: an API key. Ask the user to create one at https://app.ollav.app/keys and set it as `OLLAV_API_KEY`. A key belongs to one workspace. **Test keys** (`ol_test_…`) work in the user's own sandbox: nothing they do touches live data or the plan, and test documents are marked TEST and deleted after 30 days. Start with one; switch to a **live key** (`ol_live_…`) to share with the team. Keys made before test mode start `sk_live_` and are live.

```bash
export OLLAV_API_KEY=ol_test_...
```

## The whole loop in three commands

```bash
# 1. Publish → returns {"url": "https://content.ollav.app/p/<slug>", "slug": "<slug>", ...}
curl -s -F "file=@prototype.html" -H "Authorization: Bearer $OLLAV_API_KEY" -H "X-Ollav-Client: agent" https://app.ollav.app/api/documents

# 2. Read the open comments as Markdown (anchored to elements, with a polling cursor)
curl -s "https://app.ollav.app/api/review?slug=$SLUG&format=markdown" -H "Authorization: Bearer $OLLAV_API_KEY"

# 3. Ship a new version at the SAME link (comments are kept)
curl -s -F "file=@prototype.html" -H "Authorization: Bearer $OLLAV_API_KEY" -H "X-Ollav-Client: agent" https://app.ollav.app/api/documents/$SLUG/versions
```

Always give the user the `url` from step 1. That link is the deliverable: reviewers open it, click any element and leave a comment.

## Connect over MCP

**The full MCP docs are at [/docs/mcp](https://ollav.app/docs/mcp):** connect guides with copy-paste configs, auth options, how to check the connection works, every tool with its inputs, outputs and an example, and troubleshooting for every error. New to it? [Use Ollav from your agent via MCP](https://ollav.app/docs/quickstart/mcp) takes five minutes.

The MCP endpoint is `https://app.ollav.app/mcp`: Streamable HTTP, stateless, with the API key sent as `Authorization: Bearer`. Clients that can't send headers can use `https://app.ollav.app/mcp/ol_test_...` instead. That URL contains the key, so treat it like a password.

### Claude Code

Install the plugin (MCP server plus a skill that tells Claude when to use Ollav):

```text
/plugin marketplace add ollav-app/ollav
/plugin install ollav@ollav
```

Or add just the MCP server:

```bash
claude mcp add --transport http ollav https://app.ollav.app/mcp --header "Authorization: Bearer $OLLAV_API_KEY"
```

### Cursor

Add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "ollav": {
      "url": "https://app.ollav.app/mcp",
      "headers": { "Authorization": "Bearer ${env:OLLAV_API_KEY}" }
    }
  }
}
```

### OpenAI Codex CLI

```bash
codex mcp add ollav --url https://app.ollav.app/mcp --bearer-token-env-var OLLAV_API_KEY
```

Or in `~/.codex/config.toml`:

```toml
[mcp_servers.ollav]
url = "https://app.ollav.app/mcp"
bearer_token_env_var = "OLLAV_API_KEY"
```

### ChatGPT

Add Ollav as an app with OAuth. You sign in to Ollav once and pick the workspace ChatGPT may use. No API key to copy:

```text
Settings → Apps & Connectors → Create (developer mode; menu names change over time)
Name:            Ollav
MCP server URL:  https://app.ollav.app/mcp
Authentication:  OAuth
```

In ChatGPT you can attach an HTML file and say "share this on Ollav". The file is passed to Ollav directly, so the model doesn't retype it. Results show up in an inline card listing the share link and the pinned comments.

### Claude.ai and Claude Desktop

```text
Settings → Connectors → Add custom connector
URL: https://app.ollav.app/mcp
```

Claude signs you in with OAuth. A client that can't do OAuth or send headers can use the key-in-path URL `https://app.ollav.app/mcp/ol_test_YOUR_KEY` instead.

### VS Code (GitHub Copilot)

`.vscode/mcp.json`. VS Code prompts for the key once and stores it securely:

```json
{
  "inputs": [
    { "type": "promptString", "id": "ollav-key", "description": "Ollav API key (ol_test_... or ol_live_...)", "password": true }
  ],
  "servers": {
    "ollav": {
      "type": "http",
      "url": "https://app.ollav.app/mcp",
      "headers": { "Authorization": "Bearer ${input:ollav-key}" }
    }
  }
}
```

### Windsurf

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "ollav": {
      "serverUrl": "https://app.ollav.app/mcp",
      "headers": { "Authorization": "Bearer ${env:OLLAV_API_KEY}" }
    }
  }
}
```

### Gemini CLI

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "ollav": {
      "httpUrl": "https://app.ollav.app/mcp",
      "headers": { "Authorization": "Bearer $OLLAV_API_KEY" }
    }
  }
}
```

### Any stdio-only MCP client (npx bridge)

If a client only launches local stdio servers, bridge to the remote endpoint with `mcp-remote`:

```bash
npx -y mcp-remote https://app.ollav.app/mcp --header "Authorization: Bearer $OLLAV_API_KEY"
```

As a config entry:

```json
{
  "mcpServers": {
    "ollav": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.ollav.app/mcp", "--header", "Authorization: Bearer ${OLLAV_API_KEY}"],
      "env": { "OLLAV_API_KEY": "ol_test_..." }
    }
  }
}
```

## OAuth

`https://app.ollav.app/mcp` implements the MCP authorization spec, so OAuth clients connect with no key to copy:

- A request without a token gets `401` with `WWW-Authenticate: Bearer resource_metadata="https://app.ollav.app/.well-known/oauth-protected-resource/mcp"`.
- Resource metadata: [`/.well-known/oauth-protected-resource/mcp`](https://app.ollav.app/.well-known/oauth-protected-resource/mcp). Server metadata: [`/.well-known/oauth-authorization-server`](https://app.ollav.app/.well-known/oauth-authorization-server).
- Authorization code with PKCE (`S256` only). Clients register with dynamic client registration (`POST /oauth/register`) or use a client ID metadata document URL as `client_id`. Public clients (`none`) and `client_secret_post` / `client_secret_basic` are supported.
- Scopes: `read`, `upload`, `comment`. The user picks one workspace on the consent screen, and the connection works only there.
- The access token is an Ollav API key that doesn't expire. The user can see and revoke it under API keys, listed as "<app> (OAuth)". Clients can revoke it with `POST /oauth/revoke`.

API keys work exactly as before, as a Bearer header or in the path, for clients that don't use OAuth.

## MCP tools

Each tool's inputs, outputs, annotations, an example call and its result are on [the MCP docs](https://ollav.app/docs/mcp#tools). Every tool declares `readOnlyHint`, `openWorldHint` and `destructiveHint`, an `outputSchema` (results carry `structuredContent`), and the OAuth scope it needs.

| Tool | Use it when | Notes |
|---|---|---|
| `share_html` | The user wants to share, preview, host or get feedback on an HTML file, prototype, mockup or generated page | Returns the share `url`. Takes `html` or an attached `file`. Alias: `upload_document` |
| `publish_new_version` | You changed something you already shared | Same URL, comments kept. Takes `html` or `file`. Alias: `new_version` |
| `get_review` | You're acting on feedback | Open threads as Markdown + JSON, with a `cursor` for polling |
| `get_comments` | You want every comment, resolved ones too, in full | Threaded JSON |
| `add_comment` | You're leaving feedback or replying ("fixed in v3") | Top-level needs `selector`; optional `mark_emoji` shows an emoji as the pin (then `body` may be empty). Replies need `parent_id`. Emails the document owner |
| `resolve_comment` | You addressed a thread | `unresolve: true` reopens it |
| `react_to_comment` | Acknowledge without a reply | Any emoji: 👍 agree, 👀 on it, ✅ done, ❤️, 🎉 |
| `list_documents` | Find something shared earlier | Version and unresolved-comment counts |
| `get_document` | Version history of one document | |
| `delete_comment` | Remove your own comment | |
| `export_data` | The user asks for a copy of their data | Signed ZIP link, valid 15 minutes |

The old names `upload_document` and `new_version` keep working, so existing configs and permission rules don't break.

## The feedback loop

1. `share_html` (or `POST /api/documents`): give the user the `url`.
2. Wait for reviewers. Poll with `get_review`. Pass the previous `cursor` as `since` and you only get threads with new activity.
3. For each open thread, find the element in **your source** with `anchor.quote` (the element's text) and `anchor.reproduceNote`. `anchor.selector` points at the rendered DOM, not your JSX.
4. Edit, then `publish_new_version` with the same `slug`.
5. `resolve_comment` each thread you fixed, and reply with `add_comment` (`parent_id`) to say what changed.

Comments made on an earlier build are marked `onCurrentVersion: false`. Their element may have moved or gone.

## Notifications

Your comments email people, exactly like a person's. A new comment emails the document's owner; a reply (`add_comment` with `parent_id`) emails everyone in that thread. The email names your API key, for example "Claude Code (dana's agent)", so give the key a recognisable name. The author is never emailed about their own comment.

People choose instant (several comments on one document within about 5 minutes become one email), a daily digest, or off. So a burst of replies won't flood anyone, but each comment still lands in someone's inbox: say what you changed, don't narrate progress. `react_to_comment` acknowledges a thread without emailing anyone. Comments made with an `ol_test_` key never send email.

## Rules that keep users happy

- **Built apps: upload the file, don't paste it.** Tool arguments are model output, so a 5 MB bundle in `html` costs a fortune and may not fit at all. If you have a shell, use `curl -F "file=@dist/index.html"`. curl reads the file from disk, so it costs zero tokens.
- **One self-contained HTML file, up to 15 MB.** Inline CSS/JS/images or use absolute `https://` URLs. Relative paths like `src="assets/app.js"` won't load. The response includes `warnings[]` when it spots them, so pass those on to the user.
- **Visibility: leave it out.** The default `workspace` means only workspace members can see it. `link` lets anyone signed in to Ollav open it. Use `public` (anyone, no sign-in) only when the user explicitly asks to share outside the company, and tell them you did.
- **Iterating? Use `publish_new_version`, not another upload.** A second upload creates a different link with no comment history.

## Errors

Every error looks like this, from REST and from MCP tools alike ([MCP troubleshooting](https://ollav.app/docs/mcp#troubleshooting)). Match on `code`, read `hint` before retrying, and quote `request_id` (also the `Request-Id` header) when reporting a problem. Every code, with its cause and fix, is on [the errors page](https://ollav.app/docs/errors).

```json
{ "error": { "type": "permission_error", "code": "SCOPE_REQUIRED", "message": "upload scope required", "hint": "This API key lacks the 'upload' scope. Ask the user to create a key with it at https://app.ollav.app/keys (scopes: upload, read, comment).", "doc_url": "https://ollav.app/docs/errors#SCOPE_REQUIRED", "request_id": "req_6f1c2a9b0d4e8f7a1b2c3d4e", "docs": "https://ollav.app/docs/agents#errors" } }
```

| Code | Status | What to do |
|---|---|---|
| `AUTH_REQUIRED` | 401 | Send `Authorization: Bearer ol_live_...` (or `ol_test_...`). If you did, the key is wrong, revoked or its user left the workspace. Ask the user for a new key. |
| `SCOPE_REQUIRED` | 403 | The key lacks a scope (`upload`, `read`, `comment`). Ask the user for a key with it. |
| `CSRF_REQUIRED` | 403 | Add `X-Ollav-Client: agent` to every POST, PATCH and DELETE. |
| `NOT_FOUND` | 404 | Check the slug or id. A key only sees its own workspace, so other workspaces' documents also return 404. |
| `ARCHIVED` | 404 | The document was archived. `POST /api/documents/{slug}/unarchive` restores it. |
| `TOO_LARGE` | 413 | Over 15 MB. Compress images (WebP, downscale) and upload again. |
| `NOT_HTML`, `EMPTY_BODY`, `MISSING_HTML`, `MISSING_FILE` | 400 | Send a non-empty HTML document as `file=@...`, a JSON `html` field or a `text/html` body. |
| `VALIDATION_ERROR`, `BAD_JSON` | 400 | Fix the request body. The message names the field. |
| `ROLE_REQUIRED`, `FORBIDDEN` | 403 | The user's role doesn't allow it. Tell the user instead of retrying. |
| `PLAN_LIMIT`, `PLAN_READ_ONLY` | 402 | The workspace is at a limit of its plan (`limit` says which), or over one and read-only. Nothing was changed. Tell the user instead of retrying. |
| `RATE_LIMITED`, `TOO_MANY_REQUESTS` | 429 | Wait and retry later (a test key allows 60 requests a minute). Don't loop. |
| `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_KEY_IN_USE` | 409 | The `Idempotency-Key` was used for a different request, or its first request is still running. Use a new key for a new request. |

**Retries.** Send `Idempotency-Key: <a fresh UUID>` on every POST, PATCH and DELETE (MCP: the `idempotency_key` argument). If a call times out, retry it with the same key and the same body: it happens once, and the retry returns the first result. Keys last 24 hours.

**Versions.** Breaking changes ship as dated API versions. Your key is pinned to the version current when it was created; send `Ollav-Version: 2026-11-01` to choose one explicitly. Every response names its version in the `Ollav-Version` header. See the [changelog](https://ollav.app/docs/changelog).

## All docs {#all-docs}

- [MCP server](https://ollav.app/docs/mcp): connect, auth, verify, every tool, troubleshooting
- [Quickstart: use Ollav from your agent via MCP](https://ollav.app/docs/quickstart/mcp)
- [Quickstart: publish your first prototype with curl](https://ollav.app/docs/quickstart/curl)
- [REST API reference](https://ollav.app/docs/api): every endpoint with a curl example
- [Errors](https://ollav.app/docs/errors): every error code, its cause and fix
- [Changelog](https://ollav.app/docs/changelog): API changes and versions

## Machine-readable references

- [llms.txt](https://ollav.app/llms.txt), the index for LLMs, and [llms-full.txt](https://ollav.app/llms-full.txt), everything in one file
- [OpenAPI 3.1](https://ollav.app/openapi.json), every endpoint an API key can call
- [MCP server card](https://ollav.app/.well-known/mcp.json), the MCP endpoint, transport and auth
- [Full API reference](https://app.ollav.app/llms.txt) with curl examples for every endpoint
- [This page as Markdown](https://ollav.app/docs/agents.md)

---

Page: https://ollav.app/docs/quickstart/mcp (updated 2026-10-27)

# Use Ollav from your agent via MCP

Connect your agent once and it can share an HTML page as a live link, read the comments people pin to it and publish the fix at the same link. This takes about five minutes with a **test key**, so nothing touches your team's live documents or your plan.

## 1. Get a test key {#key}

Open https://app.ollav.app/keys, choose **Test**, keep the scopes `upload`, `read` and `comment`, and create the key. It is shown once.

```bash
export OLLAV_API_KEY=ol_test_...
```

A test key works in your own sandbox: documents carry a TEST mark and are deleted after 30 days, there are no plan limits, and it may make 60 tool calls a minute.

## 2. Connect your client {#connect}

### Claude Code

```bash
claude mcp add --transport http ollav https://app.ollav.app/mcp --header "Authorization: Bearer $OLLAV_API_KEY"
claude mcp list
```

`ollav` shows as connected. Or install the plugin, which adds a skill telling Claude when to use Ollav: `/plugin marketplace add ollav-app/ollav`, then `/plugin install ollav@ollav`.

### Cursor

`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ollav": {
      "url": "https://app.ollav.app/mcp",
      "headers": { "Authorization": "Bearer ${env:OLLAV_API_KEY}" }
    }
  }
}
```

Restart Cursor from the shell where `OLLAV_API_KEY` is set. **Settings → MCP** shows `ollav` with a green dot.

### ChatGPT

ChatGPT connects with OAuth, which gives it a live key. To try test mode first, create the app with the key in the URL:

```text
Settings → Apps & Connectors → Create (developer mode)
Name:            Ollav
MCP server URL:  https://app.ollav.app/mcp/ol_test_YOUR_KEY
Authentication:  No authentication
```

That URL contains the key, so treat it like a password. When you're ready to share with your team, recreate the app with `https://app.ollav.app/mcp` and **OAuth**.

Claude.ai, Claude Desktop, Codex, VS Code and other clients: see [Connect your client](https://ollav.app/docs/mcp#connect).

## 3. Share something {#share}

Ask your agent:

> Make a one-page pricing mockup in HTML and share it on Ollav.

It calls `share_html` and gives you a link like `https://content.ollav.app/p/qkjgjQCQGz`. Open it: the page has a TEST mark, and you can click any element to pin a comment. Leave one, say on the main button: "Make this say Start free trial".

A coding agent with a shell uploads a file on disk with curl instead of passing the HTML through the model, which costs no tokens. The `share_html` description tells it how.

## 4. Have it act on the review {#review}

> Read the review comments on that page and fix them.

The agent calls `get_review` (the open threads as Markdown and JSON, each with the element's text so it can find it in the source), edits the page, calls `publish_new_version` with the same slug (same link, comments kept) and `resolve_comment` on the thread, often replying with `add_comment` to say what changed. Reload the link to see the new version.

That's the loop: share, review, publish a new version, resolve.

## 5. Check it, or fix it {#check}

To confirm the key and endpoint outside the client:

```bash
curl -s https://app.ollav.app/mcp \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

You get 11 tools. If the client reports an error, every Ollav error carries a `code`, a `hint` the agent can follow and a `doc_url`. The common ones:

| Code | Why | Fix |
|---|---|---|
| `AUTH_REQUIRED` | No key sent, or the key is mistyped or revoked | Check the header or URL in the client config, and that the client sees `OLLAV_API_KEY` |
| `NOT_FOUND` | A test key asked for a live document (or the other way round) | Use the same key that shared it |
| `RATE_LIMITED` | Over 60 tool calls a minute with a test key | Wait a minute |

Everything else: [Troubleshooting MCP](https://ollav.app/docs/mcp#troubleshooting).

## Next {#next}

- Switch the client to a live key (`ol_live_...`), or OAuth, to share with your team.
- Every tool, its inputs, outputs and errors: [the MCP docs](https://ollav.app/docs/mcp).
- No MCP? [Publish your first prototype with curl](https://ollav.app/docs/quickstart/curl).

---

Page: https://ollav.app/docs/quickstart/curl (updated 2026-10-27)

# Publish your first prototype with curl

Five commands, about five minutes. You publish an HTML file, get a link people can comment on, read their comments, ship a fix at the same link and close the thread. Everything here runs with a **test key**, so nothing touches your team's live documents or your plan.

## 1. Get a test key {#key}

Open https://app.ollav.app/keys, choose **Test**, keep the scopes `upload`, `read` and `comment`, and create the key. It is shown once.

```bash
export OLLAV_API_KEY=ol_test_...
```

Check it works:

```bash
curl -s https://app.ollav.app/api/me -H "Authorization: Bearer $OLLAV_API_KEY"
```

The response says `"livemode": false`: this key works in your own sandbox. Test documents carry a TEST mark and are deleted after 30 days, and a test key may make 60 requests a minute.

## 2. Publish a file {#publish}

Any self-contained HTML file up to 15 MB works. No file handy? Make one:

```bash
cat > prototype.html <<'HTML'
<!DOCTYPE html>
<html><head><title>Pricing page</title></head>
<body><h1>Pricing</h1><p>Pro: €12 a month.</p><button id="buy">Buy now</button></body></html>
HTML
```

Upload it. curl reads the file from disk, which is also the cheapest way for an agent with a shell to publish:

```bash
curl -s -F "file=@prototype.html" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent" \
  -H "Idempotency-Key: $(uuidgen)" \
  https://app.ollav.app/api/documents
```

```json
{ "url": "https://content.ollav.app/p/qkjgjQCQGz", "slug": "qkjgjQCQGz", "versionId": "...", "deduped": false, "versioned": false, "warnings": [], "livemode": false }
```

Open the `url`: that link is the deliverable. Keep the `slug`:

```bash
export SLUG=qkjgjQCQGz
```

Every POST, PATCH and DELETE needs `X-Ollav-Client: agent`. `Idempotency-Key` is optional: retry with the same key and the upload happens once.

## 3. Leave a comment {#comment}

Normally a reviewer opens the link and clicks an element. To try the loop alone, pin one yourself:

```bash
curl -s -X POST https://app.ollav.app/api/comments \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent" \
  -H "Content-Type: application/json" \
  -d "{\"slug\":\"$SLUG\",\"body\":\"Make the button say Start free trial\",\"selector\":\"#buy\",\"rect\":{\"x\":0,\"y\":0,\"w\":1,\"h\":1},\"elementText\":\"Buy now\"}"
```

## 4. Read the feedback {#review}

`/api/review` returns the open threads. With `format=markdown` they come as a summary an agent can act on directly:

```bash
curl -s "https://app.ollav.app/api/review?slug=$SLUG&format=markdown" -H "Authorization: Bearer $OLLAV_API_KEY"
```

Without `format`, the JSON has each thread's `id`, `comment` and `anchor.quote` (the element's text, for finding it in your source), plus a `cursor`: pass it as `since` next time to get only new activity.

Keep the first thread's id (this uses `jq`):

```bash
export COMMENT_ID=$(curl -s "https://app.ollav.app/api/review?slug=$SLUG" -H "Authorization: Bearer $OLLAV_API_KEY" | jq -r '.threads[0].id')
```

## 5. Ship the fix at the same link, and resolve {#version}

Edit the file, then publish a new version. The URL stays the same and every comment is kept:

```bash
sed -i.bak 's/Buy now/Start free trial/' prototype.html
curl -s -F "file=@prototype.html" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent" \
  https://app.ollav.app/api/documents/$SLUG/versions
```

Close the thread:

```bash
curl -s -X POST https://app.ollav.app/api/comments/$COMMENT_ID/resolve \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent"
```

## When something fails {#errors}

Errors are JSON with a stable `code`, a `hint` saying what to do and a `doc_url`. The common ones here:

| Code | Why | Fix |
|---|---|---|
| `AUTH_REQUIRED` | The key is missing, mistyped or revoked | Check `$OLLAV_API_KEY` is exported in this shell |
| `CSRF_REQUIRED` | A POST without `X-Ollav-Client` | Add `-H "X-Ollav-Client: agent"` |
| `NOT_FOUND` | Wrong slug or id, or a live document with a test key | Use the slug from step 2 with the same key |
| `TOO_LARGE` | Over 15 MB | Compress inlined images |
| `RATE_LIMITED` | Over 60 requests a minute with a test key | Wait a minute |

Every code: [errors](https://ollav.app/docs/errors).

## Next {#next}

- Switch to a live key (`ol_live_...`) to share with your team. Live documents count towards your plan.
- Let your agent do this: [Use Ollav from your agent via MCP](https://ollav.app/docs/quickstart/mcp).
- Every endpoint: [REST API reference](https://ollav.app/docs/api).

---

Page: https://ollav.app/security (updated 2026-10-26)

# Security and privacy

Ollav hosts HTML that people and AI agents generate, which means arbitrary JavaScript. The design starts from that. This page describes what is actually built today, with no promises we haven't shipped.

## Your data stays in the EU

- Uploaded documents and comment images are stored in **Cloudflare R2 with EU jurisdiction**. Metadata (accounts, comments, versions) is in **Cloudflare D1 with EU jurisdiction**. Both are set when the store is created and can't be moved out later.
- Nightly database backups go to an EU-jurisdiction bucket and are **deleted after 28 days**, so erased data leaves the backups within 30 days.
- Cloudflare is a US company. EU jurisdiction controls where data is physically stored, not which law Cloudflare is subject to. We say this plainly because buyers ask.

## Your content is never used to train AI models

Ollav doesn't train models on your documents, comments or images, and doesn't send them to any model provider. When *your* agent reads comments through the API, it does so with your API key, under your agreement with that provider.

## Untrusted HTML runs on a separate origin

- Documents are served from **a separate content origin** (`content.ollav.app`), never from the app origin that holds sessions and API keys. A prototype's own JavaScript can't read your Ollav session.
- The commenting overlay injected into each document is **credential-free**. It draws pins and works out which element you clicked. Authenticated calls happen in an app-origin frame that talks to it only through `postMessage` with a strict target origin.
- Served documents get `X-Content-Type-Options: nosniff`, a `frame-ancestors` policy and `noindex`, so search engines don't index customer documents.
- Comment images are checked by their file signature (PNG, JPEG, WebP or GIF; SVG is refused) and served only from the content origin, behind a short-lived token that's re-checked on every request.

## Access control

- **Workspaces** with roles: owner, admin, member and guest. A guest sees only the documents shared with them.
- Each document has its own visibility: **workspace** (default, members only), **link** (anyone signed in who has the URL) or **public** (anyone with the URL). Only members can comment, whatever the visibility.
- Access is **re-checked on every request**. When someone leaves a workspace, their session and API keys stop reaching its documents straight away. Unknown, archived and forbidden documents all return the same 404, so an outsider can't tell which documents exist.
- **API keys** for agents have scopes (`upload`, `read`, `comment`), are pinned to one workspace, are stored only as SHA-256 hashes, are shown once, and can be revoked at any time.
- Sign-in uses Google (with full ID-token verification) or a magic link. Sessions are HttpOnly, Secure, SameSite=Lax cookies.

## GDPR: export and deletion, self-serve

- **Export (Art. 15 and 20).** "Download my data" gives any user a ZIP of their profile, memberships, documents with every version, comments, reactions and images. Workspace owners can export the whole workspace. Agents can do the same with `POST /api/exports` or the `export_data` MCP tool.
- **Deletion (Art. 17).** Delete a document, a workspace or your account from the Account page. Stored files nothing else references are removed straight away, and any that fail are retried nightly. An audit log keeps ids and counts, never content, for 365 days.

## Questions

For security questions, a DPA or a vulnerability report, write to **security@ollav.app**. See also the [privacy policy](https://ollav.app/privacy) and [terms](https://ollav.app/terms).

---

Page: https://ollav.app/terms (updated 2026-10-28)

# Terms of Service

Version 2026-10-20

These terms are the agreement between you and **[LEGAL ENTITY NAME]** ("Ollav", "we", "us"), of [REGISTERED ADDRESS], about your use of Ollav at ollav.app, app.ollav.app and content.ollav.app, its API and its MCP server (together, "the service"). By creating an account or using the service you agree to them. Questions: **[CONTACT EMAIL]**.

How we handle personal data is in the [Privacy Policy](https://ollav.app/privacy).

## Accounts

- You sign in with Google or with a link we email you. Keep access to that Google account or mailbox safe: whoever controls it controls your Ollav account.
- You must be at least [MINIMUM AGE] years old to use the service.
- You're responsible for what happens under your account, including the API keys you create and the people you invite to your workspaces.
- If you use Ollav for an organisation, you confirm you're allowed to accept these terms for it.

## Plans and billing

- Ollav has a free plan and paid plans. The current plans, limits and prices are on the [pricing page](https://app.ollav.app/pricing).
- Paid plans are sold through **Stripe**, which acts as the **merchant of record** (Stripe Managed Payments). You buy the subscription from Stripe; Stripe takes your payment, holds your payment details, and calculates and collects VAT and sales tax. Stripe's own terms apply to the purchase.
- Subscriptions renew automatically each month or year until cancelled. The Team plan is billed per member, and the amount follows the number of members (guests are free).
- You can change plan or cancel at any time under **Workspace → Billing → Manage billing**. A cancellation takes effect at the end of the period you've paid for.
- Refunds follow the Stripe Managed Payments setup and applicable consumer law. [TODO: Darragh to confirm the refund policy.]
- If a payment fails, the paid limits stay in place for 14 days. After that, or after you cancel or downgrade, the workspace gets the free plan's limits. A workspace over a limit becomes read-only: we don't delete anything because of it.
- We may change prices. We'll tell you before a change applies to your subscription, and you can cancel before it does.

## Your content

- **You own what you upload**: HTML documents, comments, images and anything else ("your content"). We don't claim any ownership of it.
- You give us a licence to store, copy, process and display your content **only to run the service for you**: to host it, show it to the people you've chosen to share it with, back it up and keep it secure. This licence ends when you delete the content, except for backup copies, which expire as described in the Privacy Policy.
- We don't use your content to train AI models, and we don't send it to model providers.
- You confirm you have the rights to upload and share your content, and that it doesn't break these terms or the law.

## Public pages and sharing

- Each document has a visibility: **workspace** (members only), **link** (anyone signed in who has the URL) or **public** (anyone with the URL, no sign-in). You choose it, and you're responsible for what you make public.
- Anyone who can see a document can copy what's in it. We can't undo that after you change the visibility or delete the document.
- Documents are served from content.ollav.app, a separate origin, and run their own JavaScript in the visitor's browser. We don't check or vouch for what an uploaded document does.

## AI agents, the API and MCP

- You can let AI agents and other software use Ollav for you through the REST API, the MCP server, an API key or an OAuth connection.
- **You're responsible for what your agents do with your keys and connections**, as if you had done it yourself, including what they upload, share, comment or delete. Give a key only the scopes it needs, and revoke it when you no longer need it.
- Your agreement with an AI provider (for example, the company that runs your agent) is between you and that provider. When your agent reads your Ollav content, that provider handles it under its own terms.
- The API has rate limits and daily quotas that depend on your plan. Don't try to get around them.

## Test mode

- Test keys (`ol_test_`) work in a private sandbox that's separate from your live workspace and doesn't count towards your plan's limits. Test keys are limited to 60 requests a minute.
- **Test documents are deleted automatically 30 days after upload.** Don't keep anything in test mode you want to keep.
- Test mode is for building and testing integrations, not for hosting real content.

## Acceptable use

You must not use the service, or let anyone else use it, to:

- host or send **phishing** pages, or pages that imitate another organisation or person to deceive people;
- **collect passwords, payment details or other credentials** under false pretences;
- distribute **malware**, or code that attacks, exploits or tracks visitors without their consent;
- host or share **illegal content**, including child sexual abuse material and terrorist content;
- send **spam**, including through invites, shares or comment notifications;
- **harass**, threaten or abuse anyone;
- host content that **infringes** someone else's copyright, trade mark, privacy or other rights;
- **abuse the service**: try to break or bypass its security or its isolation between documents and accounts, access data that isn't yours, overload it, get around plan limits or rate limits, resell it without our agreement, or use it as general file storage or a CDN.

We may remove or block content, revoke API keys and suspend or close accounts that break these rules, where possible after telling you, and immediately when we need to protect people or the service. We may report illegal content to the authorities.

To report abuse or content that infringes your rights, write to **[ABUSE EMAIL]**. [TODO: Darragh to confirm the abuse and notice address, and whether a formal notice-and-action process is needed for the EU Digital Services Act.]

## Availability

The service is provided **"as is" and "as available"**. We work to keep it running and your content safe, but we don't promise it will always be available, error-free or never lose data. Keep your own copy of anything important; you can download all your data at any time from the Account page.

We may change or remove features. If we stop offering the service altogether, we'll give you reasonable notice so you can export your data.

## Liability

- Nothing in these terms limits liability that can't be limited by law, including for death or personal injury caused by negligence, for fraud, or your rights as a consumer.
- Otherwise, we're not liable for indirect or consequential loss, or for loss of profits, revenue, data or goodwill.
- Otherwise, our total liability to you for anything arising from the service is limited to the greater of the amount you paid us for the service in the 12 months before the claim and €100.

[TODO: lawyer to confirm these limits, and how they apply to consumers as opposed to business customers.]

## Ending your use

- You can stop using Ollav at any time. Cancel any subscription, then delete your account from the Account page. Deleting the account removes your documents and personal data as described in the Privacy Policy.
- We may suspend or close your account if you seriously or repeatedly break these terms, or if the law requires us to. Where we can, we'll tell you first and give you the chance to export your data.
- The sections on your content, liability and governing law continue to apply after the agreement ends.

## Changes to these terms

We may update these terms. If a change matters to you, we'll ask you to agree to the new version the next time you sign in, and we'll update the version at the top of this page. If you don't agree, you can stop using the service and delete your account.

## Governing law

These terms are governed by the laws of **Ireland**, and the courts of Ireland have jurisdiction over any dispute. If you're a consumer living elsewhere in the EU, you also keep the protection of the mandatory laws of your country and can bring a claim there. [TODO: Darragh and lawyer to confirm governing law.]

## Contact

[LEGAL ENTITY NAME], [REGISTERED ADDRESS]. Email: **[CONTACT EMAIL]**.

---

Page: https://ollav.app/privacy (updated 2026-10-28)

# Privacy Policy

Version 2026-10-20

This policy explains what personal data Ollav collects when you use ollav.app, app.ollav.app, content.ollav.app, the API and the MCP server, why we collect it, and what your rights are under the EU General Data Protection Regulation (GDPR).

## Who we are

The data controller is **[LEGAL ENTITY NAME]**, of [REGISTERED ADDRESS], Ireland. Ollav is run by Darragh Flood. For anything about your data, write to **[PRIVACY EMAIL]**.

[TODO: Darragh to confirm whether a Data Protection Officer is required; if one is appointed, add their contact details here.]

When a workspace owner uses Ollav for their organisation, the documents and comments in that workspace belong to them. [TODO: lawyer to confirm whether Ollav acts as a processor for workspace content and needs a Data Processing Agreement for business customers.]

## What we collect

**Account data**

- Your **email address**. With Google sign-in we ask Google for your basic profile (`openid email profile`) and check that your email address is verified. We store only the email address, not your name or profile picture.
- With email sign-in, we send you a single-use link that expires after 15 minutes.
- The names of workspaces you create, your memberships and roles, invitations you send or accept (including the invited email address), and which version of these Terms and this Privacy Policy you agreed to, and when.

**Your content**

- The **HTML documents** you upload, with every version, their titles and file names and when they were uploaded.
- **Comments**, replies, reactions, the images you attach to comments, and the page state saved with a comment so a reviewer can see what you saw.

**API keys and agent access**

- For each API key: its name, the first 12 characters, a one-way hash of the key (never the key itself), its scopes, live or test mode, when it was created and last used, and when it was revoked. OAuth connections from AI clients create the same kind of key.

**Usage and technical data**

- Sign-in sessions: when each started, when it was last used and when it expires.
- Counters used to limit how often actions can be repeated (for example, sign-in links per email address, API calls per day).
- An audit log of exports and deletions, which holds ids and counts, never content.
- Our hosting provider, Cloudflare, processes your **IP address**, browser details and the requests you make, to deliver the service and protect it from attacks. Our own database doesn't store IP addresses, except briefly in a counter that limits password sign-in attempts. Error logs can contain request details. [TODO: Darragh to confirm which Cloudflare logs are kept, and for how long.]

**Billing data**

- Paid plans are sold by **Stripe** as merchant of record. Stripe collects and holds your payment details, billing address and tax information; we never see your full card number. We keep the Stripe customer and subscription ids, the plan, its status, seat count and billing period for the workspace.

**Emails**

- When email is enabled, we send sign-in links, invitations, notifications about comments on documents, and warnings before a document expires.

We don't use analytics, advertising or tracking tools, and we don't sell your data. We don't use your content to train AI models, and we don't send it to model providers.

## Why we use it, and the legal basis

| Purpose | Legal basis |
|---|---|
| Creating your account, signing you in, hosting and showing your documents, comments, sharing, the API and MCP server, sending emails the service depends on | Performance of our contract with you (Art. 6(1)(b)) |
| Billing, tax and accounting records | Performance of contract, and legal obligation (Art. 6(1)(c)) |
| Keeping the service secure: rate limits, preventing abuse, enforcing the Acceptable Use rules, audit logs, backups | Our legitimate interest in running a safe, reliable service (Art. 6(1)(f)) |
| Responding to your requests and complying with the law | Legal obligation (Art. 6(1)(c)) |

## Who processes your data

We use these providers. Each processes data only as needed for its part of the service:

- **Cloudflare** (hosting, database, file storage, security): [privacy policy](https://www.cloudflare.com/privacypolicy/)
- **Stripe** (payments, tax; merchant of record for paid plans, so it is responsible for the payment data it collects): [privacy policy](https://stripe.com/privacy)
- **Google** (Google sign-in): [privacy policy](https://policies.google.com/privacy)
- **Resend** (sending email): [privacy policy](https://resend.com/legal/privacy-policy)
- **GitHub** (runs the nightly database backup job; the backup passes through a GitHub-hosted runner on its way to our EU storage and isn't kept there): [privacy statement](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement)

When your own AI agent reads your Ollav content with your API key, the company that runs that agent handles it under your agreement with them, not ours.

[TODO: Darragh to confirm the final list of processors and sign a Data Processing Agreement with each.]

## Where your data is stored

Documents, comment images, the database and its backups are stored by Cloudflare in the **European Union** (EU jurisdiction for R2 and D1). Cloudflare, Stripe, Google, Resend and GitHub are, or belong to, US companies, so some data (for example, request data passing through Cloudflare's network, emails sent through Resend and the backup passing through GitHub) can be processed outside the EU. Where that happens, the transfer is covered by the EU-US Data Privacy Framework or the European Commission's Standard Contractual Clauses. [TODO: Darragh to confirm the transfer safeguard for each provider, and Resend's sending region.]

## How long we keep it

- **Your account and content**: for as long as you keep them. You can delete documents, workspaces and your account yourself.
- **Documents**: a live document expires 90 days after upload unless you extend it or mark it permanent. When email is enabled, we send a warning first. An expired document is archived: it is no longer served, but it stays stored until you delete it or delete your account. [TODO: Darragh to decide whether archived documents are deleted after a set time.]
- **Test documents** (uploaded with an `ol_test_` key) are **deleted automatically 30 days after upload**.
- **Sessions** last up to 30 days; sign-in links 15 minutes; data export links 15 minutes.
- **Deletion**: when you delete a document, a workspace or your account, its database records are removed at once, and its stored files are removed straight away (any that fail are retried every night). Deleting your account also cancels your workspaces' subscriptions, and removes your sandboxes and your comments. A top-level comment someone else replied to is kept as "[deleted]" by "Deleted user", so the reply still makes sense. You can't delete your account while you're the only owner of a workspace other people use: transfer it first.
- **Backups** are kept for 28 days, so deleted data leaves them within 30 days.
- **Audit log** entries (ids and counts, no content) are kept for 365 days.
- **Billing records** are kept by Stripe, and by us as long as the law requires for tax and accounting. [TODO: Darragh to confirm retention periods for billing records and logs.]

## Your rights

Under the GDPR you have the right to:

- **access** the personal data we hold about you, and get a copy;
- **export** it in a machine-readable format (portability);
- have it **corrected** if it is wrong;
- have it **deleted**;
- **restrict** or **object to** our use of it, including use based on our legitimate interests.

Most of this is self-serve: **Account → Download my data** gives you a ZIP of your profile, documents and every version, comments, reactions and images, and **Account → Delete my account** deletes it. For anything else, write to **[PRIVACY EMAIL]**. We'll reply within one month, and may need to confirm it's you first.

You also have the right to complain to the **Data Protection Commission** in Ireland ([dataprotection.ie](https://www.dataprotection.ie)), or to the data protection authority where you live. We'd appreciate the chance to sort it out with you first.

## Cookies and local storage

Ollav uses only what it needs to work. There are no analytics or advertising cookies, so we don't ask for cookie consent.

| Name | Where | What it does | How long |
|---|---|---|---|
| `ollav_session` | app.ollav.app | Keeps you signed in | Until you sign out or close the browser, at most 30 days |
| `ollav_oauth` | app.ollav.app | Protects the Google sign-in step | 10 minutes |
| `ollav_onboard` | app.ollav.app | Remembers you between signing in and agreeing to these terms | 30 minutes |
| `ollav_view_{document}` | content.ollav.app | Lets you view a document that isn't public | Until you close the browser |
| `ol-theme` (local storage) | your browser | Remembers light or dark mode | Until you clear it |
| `ol-emoji-recent` (local storage) | your browser | Remembers emoji you used recently | Until you clear it |

Uploaded documents are other people's HTML and may set their own cookies or load third-party content; that is outside our control. Stripe's checkout and billing pages set their own cookies under Stripe's policy.

[TODO: Darragh to confirm no analytics or other cookies are added before launch.]

## Children

Ollav isn't meant for children. You must be at least [MINIMUM AGE] to use it.

## Changes to this policy

If we change this policy in a way that matters, we'll ask you to agree to the new version the next time you sign in, and update the version at the top of this page.

## Contact

[LEGAL ENTITY NAME], [REGISTERED ADDRESS], Ireland. Email: **[PRIVACY EMAIL]**. See also the [Terms of Service](https://ollav.app/terms) and our [security overview](https://ollav.app/security).

---

Page: https://ollav.app/guides/feedback-on-ai-generated-prototypes (updated 2026-10-26)

# How to get feedback on an AI-generated prototype

An assistant can produce a clickable prototype in minutes. Getting useful feedback on it takes longer. A screenshot loses the interactions, a zip file never gets opened, and "looks good 👍" in chat doesn't tell anyone what to change. Here's a workflow that gets specific feedback and feeds it back to the agent.

## 1. Make it one self-contained HTML file

Reviewers should open a link and see the real thing. That works when the prototype is **a single HTML file** with its CSS, JavaScript and images inlined, or loaded from absolute `https://` URLs.

- If the assistant wrote one file, you're done.
- If it built a React or Vue app, have the bundler emit one file. With Vite that's `vite-plugin-singlefile`. See [single-file HTML builds](https://ollav.app/guides/single-file-html-builds).
- Avoid relative paths like `src="assets/logo.png"`. Nothing else gets uploaded with the file, so they won't load.

## 2. Share a live link, not a picture

Upload the file to Ollav: drag it onto https://app.ollav.app, or let your agent do it with the `share_html` MCP tool or one curl call:

```bash
curl -F "file=@prototype.html" -H "Authorization: Bearer $OLLAV_API_KEY" -H "X-Ollav-Client: agent" https://app.ollav.app/api/documents
```

You get a stable link. Workspace members can open it straight away, and you can share a single document with an outside reviewer as a guest.

## 3. Ask for feedback on elements, not in a thread

Ask reviewers to **click the thing they're talking about** and comment there. Each comment is pinned to that element, so "this" always means something. Make the request specific:

- "Comment on anything that would stop you finishing checkout."
- "React 👍 on comments you agree with instead of repeating them."
- "Resolve your own comment if a later version fixes it."

Reactions keep the noise down: five people agreeing is one comment with 👍 5, not five replies.

## 4. Feed the comments back to the agent

The agent that built the prototype can read the feedback directly. `get_review` returns the open threads as Markdown, each with the text of the element it's pinned to, so the agent can find it in the source:

```text
Read the open comments on the Ollav prototype, fix them, publish a new version
and resolve what you fixed.
```

Under the hood that's `get_review` → edit → `publish_new_version` → `resolve_comment`. The link stays the same and earlier comments are kept and marked as being on an older version.

## 5. Repeat until it's quiet

Each round, reviewers reload the same link. When `get_review` comes back empty, you're done. The link and the full discussion stay with the work, for whoever picks it up next.

## Checklist

- One HTML file, everything inlined or absolute
- Shared as a live link with the right visibility (workspace by default)
- Reviewers comment on elements and react instead of repeating
- The agent reads open threads, ships a new version, resolves what it fixed

[Connect your agent](https://ollav.app/docs/agents) · [Get started](https://app.ollav.app/signin)

---

Page: https://ollav.app/guides/share-claude-artifact-html-with-your-team (updated 2026-10-26)

# Share an AI-made HTML artifact with your team

Assistants are good at producing small interactive pages: a dashboard mock, a pricing calculator, a one-page explainer. Getting colleagues to *see it working* is the awkward part. This guide covers sharing that kind of single-file HTML "artifact" as a live link your team can comment on.

## What works

Ollav hosts **one self-contained HTML file up to 15 MB**. Most assistant-made artifacts already fit:

- Inline `<style>` and `<script>`: fine.
- Libraries from a CDN (`https://cdn.jsdelivr.net/...`): fine.
- Calls to public, CORS-friendly APIs: fine.
- Images as `data:` URIs or absolute URLs: fine.
- Relative files (`./data.json`, `img/logo.png`): **won't load**. Ask the assistant to inline them.
- Server code (API routes, databases): **not supported**. It's static hosting.

If the artifact is React or TSX source rather than HTML, ask the assistant: *"Give me this as a single self-contained HTML file that loads React from a CDN."*

## Three ways to share it

### From the browser

1. Save the HTML to a file (or copy it).
2. Open https://app.ollav.app and drop the file, or paste the HTML.
3. Copy the link and send it to your team.

### From an agent with MCP

Connect Ollav once ([setup for each client](https://ollav.app/docs/agents)), then just ask:

```text
Share this page on Ollav and give me the link.
```

The agent calls `share_html` and replies with the URL.

### From a terminal

```bash
curl -F "file=@artifact.html" -H "Authorization: Bearer $OLLAV_API_KEY" -H "X-Ollav-Client: agent" https://app.ollav.app/api/documents
```

## Who can see it

| Visibility | Who can open the link | Who can comment |
|---|---|---|
| `workspace` (default) | Members of your workspace | Members |
| `link` | Anyone signed in to Ollav with the URL | Members |
| `public` | Anyone with the URL, no sign-in | Members |

To bring in one outside reviewer without opening the whole workspace, share that document with their email. They become a guest of just that document.

## Updating it

When you change the artifact, publish it as a **new version** of the same document rather than uploading it again. The link stays the same and the comments carry over. In the browser, re-upload with the same filename. An agent calls `publish_new_version` with the document's slug.

[Get started](https://app.ollav.app/signin) · [How reviewing works](https://ollav.app/guides/review-html-mockups-with-comments)

---

Page: https://ollav.app/guides/review-html-mockups-with-comments (updated 2026-10-26)

# Review HTML mockups with pinned comments

A design review breaks down when nobody can tell what "the button" refers to. In Ollav every comment is pinned to an element of the live mockup, so the conversation sits on the thing it's about.

## Leaving a comment

1. Open the shared link.
2. Click the element you mean: a heading, a button, a table cell.
3. Write the comment. You can paste a screenshot into it.

The pin stays attached to that element after reloads and most re-renders. Ollav anchors to stable attributes (`data-*`, ARIA roles, text) rather than generated class names, and falls back to matching the element's text.

**State matters.** If the element only appears after a few clicks (a modal, step 3 of a wizard), Ollav records the clicks that got you there, and you can add a short note like "Open the pricing modal first". Reviewers and agents can then reproduce the state.

## Reacting instead of replying

Use reactions to show agreement or progress without adding noise. Every comment has a default bar, and the **+** opens a searchable picker with every emoji (your recent ones first):

- 👍 agree
- ❤️ love it
- 🎉 nice
- 👀 looking at it
- ✅ done

You can also mark an element with an emoji alone. When you place a mark, pick its look: the numbered pin, a quick 👍 👎 ❤️ ❓ 💡, or any emoji. Then add a comment or leave it as a reaction. The emoji is what shows on the page.

## Resolving

When a thread is dealt with, resolve it. Resolved threads turn grey and drop out of the agent's default view (`get_review` returns open threads only). Reopen one if the fix didn't hold.

## Versions

Publishing a new version keeps the same link. Comments from earlier versions stay, marked as made on an earlier version, because their element may have changed. Review rounds then look like this:

| Round | What happens |
|---|---|
| v1 | Reviewers pin comments and react |
| v2 | Designer or agent fixes the top threads, resolves them and replies "fixed in v2" |
| v3 | Remaining threads, then sign-off |

## Running a good review round

- **Set a scope.** "Comment on the onboarding flow only" keeps feedback relevant.
- **Set a deadline.** The link is always live, so tell people when you'll ship the next version.
- **One thread per issue.** Reply in the thread rather than starting a new pin on the same element.
- **Let the agent do the busywork.** If an agent built the mockup, it can read the open threads, make the edits and resolve them. See the [agent feedback loop](https://ollav.app/guides/agent-feedback-loop).

[Get started](https://app.ollav.app/signin)

---

Page: https://ollav.app/guides/agent-feedback-loop (updated 2026-10-26)

# Let your coding agent act on review comments

People are good at spotting what's wrong in a prototype, and agents are good at the edit that fixes it. This guide connects the two: reviewers comment in Ollav and your agent reads the comments, edits the source, ships a new version and resolves the threads.

## Prerequisites

- An Ollav API key in `OLLAV_API_KEY` (create one at https://app.ollav.app/keys)
- Ollav connected to your agent over MCP ([setup for each client](https://ollav.app/docs/agents)), or a shell with curl

## The loop

```text
share_html ──► reviewers comment ──► get_review ──► edit source ──► publish_new_version ──► resolve_comment
                     ▲                                                                      │
                     └──────────────────────────────────────────────────────────────────────┘
```

### 1. Share

```text
Build the prototype as a single HTML file and share it on Ollav. Give me the link.
```

### 2. Read the open threads

`get_review` returns the open threads as Markdown, then as JSON. Each thread has:

- `comment`: what the reviewer said
- `anchor.quote`: the text of the element it's pinned to. **Search your source for this.**
- `anchor.reproduceNote` and `breadcrumbs`: how to reach the state where the element is visible
- `anchor.selector`: a selector for the rendered DOM (useful for checking, but not a source location)
- `onCurrentVersion`: false if the comment was made on an earlier build

### 3. Fix and publish

Edit the source, rebuild, and publish a new version at the same link. If the build is a file on disk, upload the file instead of pasting it into a tool call:

```bash
curl -F "file=@dist/index.html" -H "Authorization: Bearer $OLLAV_API_KEY" -H "X-Ollav-Client: agent" https://app.ollav.app/api/documents/$SLUG/versions
```

### 4. Close the loop

Resolve each thread you fixed and reply with a one-liner on what changed, so the reviewer can check it:

```text
resolve_comment {comment_id}
add_comment {slug, parent_id: comment_id, body: "Fixed in v3: moved the CTA above the fold."}
```

## Polling without repeats

`get_review` returns a `cursor`. Pass it back as `since` and you get only threads with new activity, or nothing. That makes it safe to run on a schedule:

```bash
curl -s "https://app.ollav.app/api/review?slug=$SLUG&since=$CURSOR&format=markdown" -H "Authorization: Bearer $OLLAV_API_KEY"
```

In Claude Code, `/loop 15m check Ollav for new comments on <slug> and address them` does this for you.

## Guardrails worth keeping

- Don't change visibility to `public` unless the user asked for it.
- Don't resolve a thread you didn't fix. Reply with a question instead.
- If a comment is on an earlier version (`onCurrentVersion: false`), check the element still exists before acting on it.

[Agent quickstart](https://ollav.app/docs/agents) · [OpenAPI](https://ollav.app/openapi.json)

---

Page: https://ollav.app/guides/single-file-html-builds (updated 2026-10-26)

# Build a single-file HTML prototype

Ollav hosts **one self-contained HTML file** per document, up to 15 MB. Hand-written prototypes usually already are one. A Vite, React or Vue project needs a build step that inlines everything into `index.html`.

## Vite (React, Vue, Svelte, vanilla)

```bash
npm install -D vite-plugin-singlefile
```

```js
// vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { viteSingleFile } from "vite-plugin-singlefile";

export default defineConfig({
  plugins: [react(), viteSingleFile()],
});
```

```bash
npm run build      # → dist/index.html with JS, CSS and small assets inlined
```

Then upload the file. With curl it costs an agent no tokens:

```bash
curl -F "file=@dist/index.html" -H "Authorization: Bearer $OLLAV_API_KEY" -H "X-Ollav-Client: agent" https://app.ollav.app/api/documents
```

## Routing

Client-side routing works. Every sub-path of a document serves the same file, so reloading `/p/<slug>/settings` doesn't 404. With React Router either:

- use `HashRouter`, the simplest option, which always restores the exact route, or
- use `BrowserRouter` with `basename` set to the document path.

## Keeping it under 15 MB

Inlined images are base64, about a third larger than the original file. Most oversized builds are screenshots:

- convert PNG screenshots to WebP at quality 80
- downscale anything wider than about 2000 px
- load big media from an absolute URL instead of inlining it

## Things that won't work

- **Relative asset paths** (`src="assets/app.js"`). Only the one file is uploaded. Ollav returns a warning when it spots them.
- **Server code.** API routes, SSR and databases don't run. Call external CORS-friendly APIs from the browser instead.
- **A `<base href>` pointing elsewhere.** It breaks relative links. Ollav warns about this too.

[Share it](https://app.ollav.app) · [Agent quickstart](https://ollav.app/docs/agents)

---

Page: https://ollav.app/compare/screenshots-in-slack (updated 2026-10-26)

# Ollav vs. screenshots in Slack

Most prototype feedback happens like this: someone posts a screenshot in a channel, people reply in a thread, and somebody tries to turn the thread into a to-do list. It works, and it costs nothing extra. This page compares it honestly with sharing the live prototype on Ollav.

## Side by side

| | Screenshots in chat | Live link on Ollav |
|---|---|---|
| What reviewers see | A still image of one state | The working prototype: hover, click, scroll, type |
| What "this" refers to | Guesswork, or a drawn-on arrow | The element the comment is pinned to |
| Interactions and states | One screenshot per state, if someone takes them | Reviewers reach the state themselves; the clicks are recorded |
| Agreement | A reply per person | A reaction: 👍 5 |
| Knowing what's done | Re-read the thread | Open vs. resolved threads |
| The next iteration | New screenshots, new thread, context lost | New version at the same link, comments kept |
| AI agents | Can't read the thread without extra plumbing | Read open threads with `get_review` and resolve them |
| Setup | None | Upload a file or let an agent share it |
| Cost | Included in your chat tool | See [pricing](https://ollav.app/pricing) |

## When screenshots are the better choice

- **A quick gut check.** "Which of these two headers?" is faster as two images in a channel.
- **It isn't HTML.** Figma frames, slides and PDFs aren't what Ollav hosts.
- **Nobody needs to interact.** If the question is about a static visual, a screenshot carries all of it.

## When a live link pays off

- The prototype has **flows or states**, like onboarding, checkout or a wizard.
- **Several people** review it and you want agreement to count once.
- You'll go through **more than one version**.
- An **AI agent** built it and should act on the feedback itself.

## Using both

Post the Ollav link in your channel. People still discuss it in Slack, and the specific, element-level feedback lands on the prototype, where the next version and the agent can see it.

[Get started](https://app.ollav.app/signin) · [How reviewing works](https://ollav.app/guides/review-html-mockups-with-comments)

---

Page: https://ollav.app/compare/static-hosting (updated 2026-10-26)

# Ollav vs. generic static hosting

Any static host can put an HTML file on the internet: a bucket with a CDN, a git-based deploy platform or a pastebin for HTML. If you just need the file online, use one. This page is about what changes when the goal is **getting the file reviewed**.

## Side by side

| | Generic static host | Ollav |
|---|---|---|
| Hosting a single HTML file | Yes | Yes, up to 15 MB |
| Multi-file sites, custom domains, server functions | Usually yes | No: one self-contained file, no server code |
| Comments on the page | Not built in; add a widget or collect elsewhere | Built in, pinned to elements, with reactions and resolving |
| Versions at a stable URL | Depends on the platform; often a new URL per deploy | Every version at the same link, earlier comments kept |
| Who can view | Usually public, or a password per site | Workspace, link (signed-in) or public, per document; guests for single documents |
| Untrusted HTML isolation | Your site is the origin | Served from a separate origin that never sees Ollav credentials |
| Agent API | Deploy APIs and CLIs | REST + MCP built around share → comment → new version |
| Search indexing | Indexed unless you configure otherwise | Documents are `noindex` |
| Data residency | Depends on the provider and plan | Stored in the EU |

## When a static host is the better choice

- You're shipping a **production site**, not a prototype.
- You need **multiple files**, a custom domain or server-side code.
- You want it **public and indexed**.

## When Ollav fits better

- The page is a **prototype, mockup or generated report** and the point is feedback.
- Reviewers include **people who shouldn't need a git account** or a deploy preview login.
- An **AI agent** produces the HTML and should also handle the feedback.
- Documents should be **private by default** and stay out of search results.

[Get started](https://app.ollav.app/signin) · [Single-file builds](https://ollav.app/guides/single-file-html-builds)

---

Page: https://ollav.app/docs/api (updated 2026-10-27)

# REST API reference

Every endpoint an API key can call, generated from the [OpenAPI 3.1 spec](https://ollav.app/openapi.json) (version 1.3.0), which CI checks against the running API. Prefer MCP from an agent? See [the MCP docs](https://ollav.app/docs/mcp). New here? [Publish your first prototype with curl](https://ollav.app/docs/quickstart/curl).

## Basics {#basics}

- **Base URL:** `https://app.ollav.app`. Shared documents are served from `https://content.ollav.app/p/{slug}`.
- **Auth:** `Authorization: Bearer $OLLAV_API_KEY`. The user creates the key at https://app.ollav.app/keys; it belongs to one workspace and has the scopes `upload`, `read` and `comment`. `ol_test_...` keys work in the user's test sandbox: no plan limits, 60 requests a minute, documents deleted after 30 days, and responses say `"livemode": false`. `ol_live_...` keys (and older `sk_live_...` keys) work on live data.
- **`X-Ollav-Client: agent`** on every POST, PATCH and DELETE (a CSRF guard; any value works). Without it: `403 CSRF_REQUIRED`.
- **`Idempotency-Key`** (optional, any unique string) on POST, PATCH and DELETE makes a retry safe: it runs once and replays the first response for 24 hours.
- **`Ollav-Version`** (optional) picks a dated API version; otherwise the version your key was pinned to is used. See the [changelog](https://ollav.app/docs/changelog).
- **Errors** are JSON `{"error": {"type", "code", "message", "param", "hint", "doc_url", "request_id"}}`. Match on `code`; every code is on [the errors page](https://ollav.app/docs/errors). Every response has a `Request-Id` header.
- **Examples** use `$OLLAV_API_KEY`; set it to a test key while you build: `export OLLAV_API_KEY=ol_test_...`.

## Endpoints {#endpoints}

- **Documents**: [`GET /api/documents`](#listDocuments), [`POST /api/documents`](#shareHtml), [`GET /api/documents/{slug}`](#getDocument), [`PATCH /api/documents/{slug}`](#updateDocumentVisibility), [`DELETE /api/documents/{slug}`](#deleteDocument), [`POST /api/documents/{slug}/archive`](#archiveDocument), [`POST /api/documents/{slug}/unarchive`](#unarchiveDocument), [`POST /api/documents/{slug}/expiry`](#setDocumentExpiry), [`GET /api/dashboard`](#listDocumentsWithCounts)
- **Versions**: [`GET /api/documents/{slug}/versions`](#listVersions), [`POST /api/documents/{slug}/versions`](#publishNewVersion)
- **Comments**: [`GET /api/comments`](#getComments), [`POST /api/comments`](#addComment), [`DELETE /api/comments/{id}`](#deleteComment), [`POST /api/comments/{id}/resolve`](#resolveComment), [`POST /api/comments/{id}/unresolve`](#unresolveComment), [`POST /api/comments/{id}/attachments`](#attachImage)
- **Reactions**: [`POST /api/comments/{id}/reactions`](#reactToComment)
- **Review**: [`GET /api/review`](#getReview)
- **Exports**: [`GET /api/documents/{slug}/export`](#exportDocument), [`POST /api/exports`](#exportData), [`GET /api/exports/download`](#downloadExport)
- **Workspaces**: [`GET /api/workspaces`](#listWorkspaces), [`GET /api/workspaces/{id}/members`](#listWorkspaceMembers)
- **Billing**: [`GET /api/workspaces/{id}/billing`](#getWorkspaceBilling)
- **Account**: [`GET /api/me`](#getMe)
- **API keys**: [`GET /api/keys`](#listApiKeys), [`DELETE /api/keys/{id}`](#revokeApiKey)

## Documents {#tag-documents}

A document is one self-contained HTML file (up to 15 MB) at a stable URL on the content origin. Uploading a file with the same filename as one you already own adds a version instead of a new document.

### List documents {#listDocuments}

`GET /api/documents`

Lists your non-archived documents in the key's workspace, newest first, as a bare array. Use GET /api/dashboard instead when you also need version and comment counts. Guests can't list (403 ROLE_REQUIRED).

**Responses**

| Status | Meaning |
|---|---|
| 200 | Your documents (a bare array). |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/documents" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
[
  {
    "id": "9908f969-9774-4374-a5bf-d66abcfbe70b",
    "slug": "qkjgjQCQGz",
    "title": "Pricing page v2",
    "filename": "pricing.html",
    "visibility": "workspace",
    "createdAt": 1793107356443,
    "url": "https://content.ollav.app/p/qkjgjQCQGz"
  }
]
```

### Upload (share) an HTML document {#shareHtml}

`POST /api/documents`

MCP tool: [`share_html`](https://ollav.app/docs/mcp#share_html)

Publishes one self-contained HTML file and returns its share url. Give that url to the user. Send JSON `{html, title?, filename?, visibility?}`, multipart/form-data with a `file` field, or a raw text/html body (title, filename and visibility then come from the query string or X-Title/X-Filename/X-Visibility headers). If you already own a document with the same filename and the content changed, this adds a version to it (201, versioned: true); identical content returns the existing version (200, deduped: true). To update a known document prefer POST /api/documents/{slug}/versions. `warnings` lists relative asset paths that won't load; it never blocks the upload. New documents expire after 90 days unless extended or made permanent. Publishing (this and new versions together) is limited to 30 an hour per account (looser per IP): over it, 429 RATE_LIMITED with error.retry_after in seconds. A multipart upload takes one file (400 TOO_MANY_FILES).

**Request body** (`application/json`, `multipart/form-data`, `text/html`)

| Field | Type | Required | Description |
|---|---|---|---|
| `html` | string | yes | The whole self-contained HTML document, up to 15 MB. |
| `title` | string |  | Defaults to the <title> tag, then the filename. |
| `filename` | string |  | Re-uploading the same filename adds a version to your document. |
| `visibility` | `workspace` \| `link` \| `public` |  | workspace (default): members of the workspace only. link: anyone signed in to Ollav with the URL. public: PUBLIC, anyone with the URL, no sign-in, including people outside the company. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Deduplicated. You already uploaded exactly this content; nothing changed. |
| 201 | A new document, or a new version of the document with the same filename. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 409 | [Conflict](#response-conflict) |
| 413 | [PayloadTooLarge](#response-payload-too-large) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X POST "https://app.ollav.app/api/documents" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent" \
  -H "Content-Type: application/json" \
  -d '{"html":"<!DOCTYPE html><html><head><title>Pricing page v2</title></head><body><h1>Pricing</h1></body></html>","filename":"pricing.html","visibility":"workspace"}'
```

Response (200):

```json
{
  "url": "https://content.ollav.app/p/qkjgjQCQGz",
  "slug": "qkjgjQCQGz",
  "documentId": "9908f969-9774-4374-a5bf-d66abcfbe70b",
  "versionId": "b8cfa354-0c7c-4102-bf14-69b49de24ca3",
  "hash": "859d1148aaf2854ea2a59a25b89063395b0ded22230bdb4c7aad72d2a83b537a",
  "deduped": true,
  "versioned": false,
  "warnings": [],
  "livemode": true
}
```

### Get a document {#getDocument}

`GET /api/documents/{slug}`

MCP tool: [`get_document`](https://ollav.app/docs/mcp#get_document)

Returns one document's metadata with every stored version (newest first). For the document's owner or a workspace admin; anyone else gets the same 404 as for a missing slug. Archived documents are returned too (archivedAt is set). Versions older than the plan's retention window are hidden, not deleted.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | path | string | yes | The document's slug, from the upload response or GET /api/dashboard. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | The document with its versions. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/documents/qkjgjQCQGz" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
{
  "id": "9908f969-9774-4374-a5bf-d66abcfbe70b",
  "workspaceId": "0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90",
  "slug": "qkjgjQCQGz",
  "title": "Pricing page v2",
  "filename": "pricing.html",
  "ownerId": "e970d2fd-66e4-4fa0-bac2-144f81995e32",
  "ownerEmail": "ada@example.com",
  "visibility": "workspace",
  "currentVersionId": "07120538-9e66-460f-9f26-22f3910a213a",
  "createdAt": 1793107356443,
  "updatedAt": 1793107356781,
  "archivedAt": null,
  "expiresAt": 1800883356443,
  "isPermanent": 0,
  "expiryWarnedAt": null,
  "url": "https://content.ollav.app/p/qkjgjQCQGz",
  "versions": [
    {
      "id": "07120538-9e66-460f-9f26-22f3910a213a",
      "workspaceId": "0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90",
      "documentId": "9908f969-9774-4374-a5bf-d66abcfbe70b",
      "hash": "97602aa74d0b26c2fcc8494d28a82c13430712aeacc549f67b7ce3c1dcf74221",
      "r2Key": "docs/97602aa74d0b26c2fcc8494d28a82c13430712aeacc549f67b7ce3c1dcf74221",
      "size": 53,
      "createdAt": 1793107356781
    }
  ]
}
```

### Change who can view a document {#updateDocumentVisibility}

`PATCH /api/documents/{slug}`

Sets the document's visibility. Only use `public` when the user explicitly asked to share outside their company: anyone with the URL can then view it without signing in. Commenting stays members-only whatever the visibility. Owner or workspace admin; needs the upload scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | path | string | yes | The document's slug, from the upload response or GET /api/dashboard. |

**Request body** (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `visibility` | `workspace` \| `link` \| `public` | yes | workspace (default): members of the workspace only. link: anyone signed in to Ollav with the URL. public: PUBLIC, anyone with the URL, no sign-in, including people outside the company. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Updated. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X PATCH "https://app.ollav.app/api/documents/qkjgjQCQGz" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent" \
  -H "Content-Type: application/json" \
  -d '{"visibility":"link"}'
```

Response (200):

```json
{
  "ok": true,
  "visibility": "link"
}
```

### Delete a document (session only) {#deleteDocument}

`DELETE /api/documents/{slug}`

Needs a signed-in browser session; an API key gets 401.

Permanently deletes the document, its versions, comments, reactions and images, and erases stored files nothing else references. Needs a signed-in browser session and the document's title or slug typed in `confirm`; an API key gets 403 FORBIDDEN. Agents: archive instead (POST /api/documents/{slug}/archive), or ask the user to delete it in the web UI.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | path | string | yes | The document's slug, from the upload response or GET /api/dashboard. |

**Request body** (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `confirm` | string | yes | The document's title or slug. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Deleted. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X DELETE "https://app.ollav.app/api/documents/qkjgjQCQGz" \
  --cookie "ollav_session=$OLLAV_SESSION" \
  -H "X-Ollav-Client: agent" \
  -H "Content-Type: application/json" \
  -d '{"confirm":"qkjgjQCQGz"}'
```

Response (200):

```json
{
  "deleted": true,
  "r2": {
    "deleted": 3,
    "pending": 0
  }
}
```

### Archive a document {#archiveDocument}

`POST /api/documents/{slug}/archive`

Takes the document offline: its URL answers 410 and it leaves listings. Nothing is deleted; undo with POST /api/documents/{slug}/unarchive. Owner or workspace admin; needs the upload scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | path | string | yes | The document's slug, from the upload response or GET /api/dashboard. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Archived. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X POST "https://app.ollav.app/api/documents/qkjgjQCQGz/archive" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent"
```

Response (200):

```json
{
  "ok": true,
  "archived": true
}
```

### Unarchive a document {#unarchiveDocument}

`POST /api/documents/{slug}/unarchive`

Brings an archived document back online at the same URL. Counts against the plan's document limit again, so it can answer 402.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | path | string | yes | The document's slug, from the upload response or GET /api/dashboard. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Restored. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X POST "https://app.ollav.app/api/documents/qkjgjQCQGz/unarchive" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent"
```

Response (200):

```json
{
  "ok": true,
  "archived": false
}
```

### Extend, set or remove a document's expiry {#setDocumentExpiry}

`POST /api/documents/{slug}/expiry`

Documents are archived automatically when they expire (90 days after upload by default). `extend` sets expiry to 90 days from now, `permanent` removes it, `custom` sets `expiresAt` (Unix ms, in the future). Test-mode documents are deleted 30 days after upload: for them `extend` sets that date, and `permanent` or a later `custom` date is a 400. Owner or workspace admin; needs the upload scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | path | string | yes | The document's slug, from the upload response or GET /api/dashboard. |

**Request body** (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | `extend` \| `permanent` \| `custom` | yes |  |
| `expiresAt` | integer |  | Unix ms; required when action is custom. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | The new expiry. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X POST "https://app.ollav.app/api/documents/qkjgjQCQGz/expiry" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent" \
  -H "Content-Type: application/json" \
  -d '{"action":"extend"}'
```

Response (200):

```json
{
  "ok": true,
  "isPermanent": false,
  "expiresAt": 1800883357891
}
```

### List documents with version and comment counts {#listDocumentsWithCounts}

`GET /api/dashboard`

MCP tool: [`list_documents`](https://ollav.app/docs/mcp#list_documents)

Your documents in the key's workspace, newest first, with version, comment and unresolved-comment counts: the quickest way to find which document has open feedback. Includes archived documents (archivedAt set). `sharedWithMe` is filled for browser sessions only.

**Responses**

| Status | Meaning |
|---|---|
| 200 | The key's workspace and its documents. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/dashboard" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
{
  "workspace": {
    "id": "0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90",
    "name": "Acme",
    "role": "owner"
  },
  "documents": [
    {
      "id": "9908f969-9774-4374-a5bf-d66abcfbe70b",
      "slug": "qkjgjQCQGz",
      "title": "Pricing page v2",
      "filename": "pricing.html",
      "visibility": "workspace",
      "createdAt": 1793107356443,
      "updatedAt": 1793107357969,
      "archivedAt": null,
      "expiresAt": 1800883356443,
      "isPermanent": 0,
      "versionCount": 3,
      "commentCount": 2,
      "unresolvedCount": 1,
      "url": "https://content.ollav.app/p/qkjgjQCQGz"
    }
  ],
  "sharedWithMe": []
}
```

## Versions {#tag-versions}

Every upload of new content is a version. The URL never changes; comments on earlier versions are kept and marked as such.

### List a document's versions {#listVersions}

`GET /api/documents/{slug}/versions`

Every visible version, newest first, numbered from 1 (the first upload), with which one is current. Versions older than the plan's retention window are hidden, not deleted. Owner or workspace admin; needs the read scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | path | string | yes | The document's slug, from the upload response or GET /api/dashboard. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | The versions. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/documents/qkjgjQCQGz/versions" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
{
  "document": {
    "slug": "qkjgjQCQGz",
    "title": "Pricing page v2",
    "versionCount": 2
  },
  "versions": [
    {
      "id": "07120538-9e66-460f-9f26-22f3910a213a",
      "hash": "97602aa74d0b26c2fcc8494d28a82c13430712aeacc549f67b7ce3c1dcf74221",
      "size": 53,
      "createdAt": "2026-10-27T13:22:36.781Z",
      "isCurrent": true,
      "versionNumber": 2
    },
    {
      "id": "b8cfa354-0c7c-4102-bf14-69b49de24ca3",
      "hash": "859d1148aaf2854ea2a59a25b89063395b0ded22230bdb4c7aad72d2a83b537a",
      "size": 99,
      "createdAt": "2026-10-27T13:22:36.443Z",
      "isCurrent": false,
      "versionNumber": 1
    }
  ]
}
```

### Publish a new version {#publishNewVersion}

`POST /api/documents/{slug}/versions`

MCP tool: [`publish_new_version`](https://ollav.app/docs/mcp#publish_new_version)

Replaces what the document's URL shows with new HTML; the URL stays the same and earlier comments are kept, marked "earlier version". Use this after editing in response to feedback, then resolve the threads you fixed. Same body formats as POST /api/documents. Identical content to the current version returns 200 with deduped: true. Needs the upload scope; archived documents answer 404 ARCHIVED, documents taken down for breaking the Terms 410 DOCUMENT_REMOVED. Counts towards the 30 publishes an hour per account (429 RATE_LIMITED).

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | path | string | yes | The document's slug, from the upload response or GET /api/dashboard. |

**Request body** (`application/json`, `multipart/form-data`, `text/html`)

| Field | Type | Required | Description |
|---|---|---|---|
| `html` | string | yes | The full new HTML. |
| `title` | string |  | Overrides the <title> tag. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Deduplicated. Same content as the current version; nothing changed. |
| 201 | New version published. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 410 | [Gone](#response-gone) |
| 413 | [PayloadTooLarge](#response-payload-too-large) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X POST "https://app.ollav.app/api/documents/qkjgjQCQGz/versions" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent" \
  -H "Content-Type: application/json" \
  -d '{"html":"<!DOCTYPE html><html><head><title>Pricing page v3</title></head><body><h1 style='\''color:blue'\''>Pricing</h1></body></html>"}'
```

Response (200):

```json
{
  "deduped": true,
  "slug": "qkjgjQCQGz",
  "url": "https://content.ollav.app/p/qkjgjQCQGz",
  "versionId": "f2d1c6e2-6960-488b-a198-6d4f33ab1841",
  "hash": "c0fb1a4309519139808296b940c600f23fa26a67fd1732f7610528fd95298909",
  "warnings": [],
  "livemode": true
}
```

## Comments {#tag-comments}

Element-anchored comments and single-level replies. Top-level comments carry the CSS selector and bounding rect of the element they pin to.

### List a document's comments {#getComments}

`GET /api/comments`

MCP tool: [`get_comments`](https://ollav.app/docs/mcp#get_comments)

Every comment thread on the document, resolved ones included, with replies, reactions and image attachments. For acting on feedback prefer GET /api/review, which returns open threads shaped for finding the element in your source. Needs the read scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | query | string | yes | The document's slug, from the upload response or GET /api/dashboard. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Threads, oldest first. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/comments?slug=qkjgjQCQGz" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
{
  "slug": "qkjgjQCQGz",
  "currentVersionId": "f2d1c6e2-6960-488b-a198-6d4f33ab1841",
  "docOwnerId": "e970d2fd-66e4-4fa0-bac2-144f81995e32",
  "viewerCanManage": true,
  "count": 1,
  "unresolvedCount": 1,
  "comments": [
    {
      "id": "e7cb98b7-c5e3-4048-8590-e7c1b1dea787",
      "documentId": "9908f969-9774-4374-a5bf-d66abcfbe70b",
      "versionId": "f2d1c6e2-6960-488b-a198-6d4f33ab1841",
      "parentId": null,
      "selector": "h1",
      "fallbackRect": {
        "x": 24,
        "y": 80,
        "w": 640,
        "h": 48
      },
      "elementText": "Pricing",
      "authorId": "e970d2fd-66e4-4fa0-bac2-144f81995e32",
      "body": "Make the headline blue",
      "createdAt": "2026-10-27T13:22:38.297Z",
      "resolvedAt": null,
      "resolvedBy": null,
      "author": {
        "email": "ada@example.com",
        "name": "Ada"
      },
      "isCurrentVersion": true,
      "reproduceNote": null,
      "breadcrumbs": null,
      "markEmoji": null,
      "attachment": null,
      "snapshotUrl": null,
      "reactions": [
        {
          "reaction": "👍",
          "count": 1,
          "mine": false
        }
      ],
      "replies": []
    }
  ]
}
```

### Post a comment or reply {#addComment}

`POST /api/comments`

MCP tool: [`add_comment`](https://ollav.app/docs/mcp#add_comment)

A top-level comment pins to an element: send `selector` (CSS) and `rect` (its bounding box, page coordinates). A reply sends `parentId` (a top-level comment's id) and no selector or rect; replies are one level deep. `markEmoji` without `body` places an emoji mark as a reaction to the element. Members only, whatever the document's visibility; needs the comment scope. Limited to 120 comments and replies an hour per account (looser per IP): over it, 429 RATE_LIMITED with error.retry_after in seconds.

**Request body** (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `slug` | string | yes |  |
| `body` | string |  | Required, unless a top-level comment sets markEmoji. |
| `parentId` | string |  | Set for a reply (a top-level comment's id); omit for a top-level comment. |
| `selector` | string |  | CSS selector of the element. Required for top-level comments. |
| `rect` | Rect |  | Bounding box of the element, in page pixels. |
| `elementText` | string |  | The element's visible text; helps re-anchor and find it in source. |
| `markEmoji` | string or null |  | One emoji to show as the pin (top-level only); null for a numbered pin. |
| `reproduceNote` | string |  | How to reach the UI state, for reviewers (top-level only). |
| `breadcrumbs` | array of Breadcrumb |  | Clicks that lead to the UI state (top-level only). |

**Responses**

| Status | Meaning |
|---|---|
| 201 | Created. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X POST "https://app.ollav.app/api/comments" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent" \
  -H "Content-Type: application/json" \
  -d '{"slug":"qkjgjQCQGz","body":"Make the headline blue","selector":"h1","rect":{"x":24,"y":80,"w":640,"h":48},"elementText":"Pricing"}'
```

Response (201):

```json
{
  "id": "e7cb98b7-c5e3-4048-8590-e7c1b1dea787",
  "workspaceId": "0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90",
  "documentId": "9908f969-9774-4374-a5bf-d66abcfbe70b",
  "versionId": "f2d1c6e2-6960-488b-a198-6d4f33ab1841",
  "parentId": null,
  "selector": "h1",
  "fallbackRect": {
    "x": 24,
    "y": 80,
    "w": 640,
    "h": 48
  },
  "elementText": "Pricing",
  "authorId": "e970d2fd-66e4-4fa0-bac2-144f81995e32",
  "body": "Make the headline blue",
  "createdAt": "2026-10-27T13:22:38.297Z",
  "resolvedAt": null,
  "resolvedBy": null,
  "reproduceNote": null,
  "breadcrumbs": null,
  "markEmoji": null,
  "author": {
    "email": "ada@example.com",
    "name": "Ada"
  }
}
```

### Delete a comment {#deleteComment}

`DELETE /api/comments/{id}`

MCP tool: [`delete_comment`](https://ollav.app/docs/mcp#delete_comment)

Deletes a comment; deleting a top-level comment deletes its replies. Only the comment's author or the document's owner. Anyone else, and unknown ids, get the same 404. Needs the comment scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | A comment id, from GET /api/review or GET /api/comments. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Deleted. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X DELETE "https://app.ollav.app/api/comments/e7cb98b7-c5e3-4048-8590-e7c1b1dea787" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent"
```

Response (200):

```json
{
  "deleted": true
}
```

### Resolve a comment thread {#resolveComment}

`POST /api/comments/{id}/resolve`

MCP tool: [`resolve_comment`](https://ollav.app/docs/mcp#resolve_comment)

Marks a top-level comment resolved. Do this after publishing a version that addresses it, and reply saying what changed. The comment's author or the document's owner; needs the comment scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | A comment id, from GET /api/review or GET /api/comments. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Resolved. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X POST "https://app.ollav.app/api/comments/e7cb98b7-c5e3-4048-8590-e7c1b1dea787/resolve" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent"
```

Response (200):

```json
{
  "ok": true,
  "resolved": true
}
```

### Reopen a comment thread {#unresolveComment}

`POST /api/comments/{id}/unresolve`

MCP tool: [`resolve_comment`](https://ollav.app/docs/mcp#resolve_comment)

Reopens a resolved top-level comment. Same rules as resolving (MCP: resolve_comment with resolved: false).

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | A comment id, from GET /api/review or GET /api/comments. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Reopened. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X POST "https://app.ollav.app/api/comments/e7cb98b7-c5e3-4048-8590-e7c1b1dea787/unresolve" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent"
```

Response (200):

```json
{
  "ok": true,
  "resolved": false
}
```

### Attach an image to a comment {#attachImage}

`POST /api/comments/{id}/attachments`

Attaches ONE image (a screenshot) to a top-level comment you wrote, or on a document you own. multipart/form-data with a `file` field, or the raw image as the body. PNG, JPEG, WebP or GIF, checked by content (SVG is refused), up to 5 MB. Served from the content origin to those who can view the document. Needs the comment scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | A comment id, from GET /api/review or GET /api/comments. |

**Request body** (`multipart/form-data`, `image/png`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | string (binary) | yes |  |
| `width` | integer |  | Display width in px (optional). |
| `height` | integer |  | Display height in px (optional). |

**Responses**

| Status | Meaning |
|---|---|
| 201 | Attached. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 413 | [PayloadTooLarge](#response-payload-too-large) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X POST "https://app.ollav.app/api/comments/e7cb98b7-c5e3-4048-8590-e7c1b1dea787/attachments" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent" \
  -F file=@screenshot.png
```

Response (201):

```json
{
  "id": "b8993718-40ff-49bc-aed5-cf0040a4105e",
  "url": "https://content.ollav.app/a/b8993718-40ff-49bc-aed5-cf0040a4105e?vt=eyJ...",
  "mime": "image/png",
  "width": 1280,
  "height": 720,
  "size": 48213
}
```

## Reactions {#tag-reactions}

Emoji reactions on comments and replies.

### Add or remove a reaction {#reactToComment}

`POST /api/comments/{id}/reactions`

MCP tool: [`react_to_comment`](https://ollav.app/docs/mcp#react_to_comment)

Adds (on: true, the default) or removes (on: false) your reaction on a comment or reply. Any single emoji; the legacy names +1, eyes, check and heart still work. A comment holds at most 20 different reactions. Anyone who may comment on the document; needs the comment scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | A comment id, from GET /api/review or GET /api/comments. |

**Request body** (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `reaction` | string | yes | One emoji, e.g. 👍. |
| `on` | boolean |  |  |

**Responses**

| Status | Meaning |
|---|---|
| 200 | The comment's reactions after the change. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X POST "https://app.ollav.app/api/comments/e7cb98b7-c5e3-4048-8590-e7c1b1dea787/reactions" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent" \
  -H "Content-Type: application/json" \
  -d '{"reaction":"👍"}'
```

Response (200):

```json
{
  "ok": true,
  "commentId": "e7cb98b7-c5e3-4048-8590-e7c1b1dea787",
  "reactions": [
    {
      "reaction": "👍",
      "count": 1,
      "mine": true
    }
  ]
}
```

## Review {#tag-review}

The agent feedback loop: read open threads shaped for editing source, publish a new version, resolve what you fixed.

### Read feedback to act on {#getReview}

`GET /api/review`

MCP tool: [`get_review`](https://ollav.app/docs/mcp#get_review)

The feedback digest for an iterating agent: open threads by default, each with a source-findable anchor (quote = the element's text, reproduceNote, breadcrumbs). `selector` is the rendered DOM, not your source; search your source for `quote`. Pass the response's `cursor` back as `since` to get only threads with new activity. format=markdown returns the same digest as text/markdown. Loop: get_review → edit → publish_new_version → resolve_comment. Needs the read scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | query | string | yes | The document's slug, from the upload response or GET /api/dashboard. |
| `format` | query | `json` \| `markdown` |  | json (default) or markdown (text/markdown, the same threads as a readable summary). |
| `status` | query | `open` \| `resolved` \| `all` |  | Which threads to return. |
| `since` | query | string |  | ISO 8601 or epoch ms. Only threads with activity after this; pass the previous response's cursor. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | The digest. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/review?slug=qkjgjQCQGz" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
{
  "slug": "qkjgjQCQGz",
  "title": "Pricing page v2",
  "url": "https://content.ollav.app/p/qkjgjQCQGz",
  "currentVersionId": "f2d1c6e2-6960-488b-a198-6d4f33ab1841",
  "filter": {
    "status": "open",
    "since": null
  },
  "totalThreads": 1,
  "openThreads": 1,
  "returned": 1,
  "cursor": "2026-10-27T13:22:38.402Z",
  "generatedAt": "2026-10-27T13:22:38.836Z",
  "note": "anchor.selector targets the rendered DOM; to locate the element in your SOURCE (JSX/HTML) prefer anchor.quote and anchor.reproduceNote.",
  "threads": [
    {
      "id": "e7cb98b7-c5e3-4048-8590-e7c1b1dea787",
      "status": "open",
      "onCurrentVersion": true,
      "versionId": "f2d1c6e2-6960-488b-a198-6d4f33ab1841",
      "author": {
        "email": "ada@example.com",
        "name": "Ada"
      },
      "createdAt": "2026-10-27T13:22:38.297Z",
      "lastActivityAt": "2026-10-27T13:22:38.402Z",
      "comment": "Make the headline blue",
      "markEmoji": null,
      "attachment": null,
      "anchor": {
        "quote": "Pricing",
        "reproduceNote": null,
        "breadcrumbs": null,
        "selector": "h1"
      },
      "replies": []
    }
  ],
  "markdown": "# Review: Pricing page v2\n\n..."
}
```

## Exports {#tag-exports}

Data exports (GDPR Art. 15/20) as JSON or a streamed ZIP.

### Export one document as JSON {#exportDocument}

`GET /api/documents/{slug}/export`

One JSON bundle: metadata, every version with its HTML inlined, and every comment. For everything in an account or workspace (with images and snapshots) use POST /api/exports. Owner or workspace admin; needs the read scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `slug` | path | string | yes | The document's slug, from the upload response or GET /api/dashboard. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | The bundle. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/documents/qkjgjQCQGz/export" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
{
  "exportedAt": "2026-10-27T13:22:38.141Z",
  "document": {
    "id": "9908f969-9774-4374-a5bf-d66abcfbe70b",
    "slug": "qkjgjQCQGz",
    "title": "Pricing page v2",
    "filename": "pricing.html",
    "visibility": "workspace",
    "createdAt": "2026-10-27T13:22:36.443Z",
    "updatedAt": "2026-10-27T13:22:37.969Z",
    "archivedAt": null,
    "expiresAt": null,
    "isPermanent": true,
    "url": "https://content.ollav.app/p/qkjgjQCQGz"
  },
  "versions": [
    {
      "id": "f2d1c6e2-6960-488b-a198-6d4f33ab1841",
      "hash": "c0fb1a4309519139808296b940c600f23fa26a67fd1732f7610528fd95298909",
      "r2Key": "docs/c0fb1a4309519139808296b940c600f23fa26a67fd1732f7610528fd95298909",
      "size": 35,
      "createdAt": "2026-10-27T13:22:37.459Z",
      "isCurrent": true,
      "html": "<html><body><p>v3</p></body></html>"
    }
  ],
  "comments": [
    {
      "id": "e7cb98b7-c5e3-4048-8590-e7c1b1dea787",
      "parentId": null,
      "selector": "h1",
      "elementText": "Pricing",
      "authorId": "e970d2fd-66e4-4fa0-bac2-144f81995e32",
      "body": "Make the headline blue",
      "createdAt": "2026-10-27T13:22:38.297Z",
      "resolvedAt": null,
      "resolvedBy": null,
      "versionId": "f2d1c6e2-6960-488b-a198-6d4f33ab1841"
    }
  ]
}
```

### Export data as a ZIP {#exportData}

`POST /api/exports`

MCP tool: [`export_data`](https://ollav.app/docs/mcp#export_data)

Returns a signed download link, valid 15 minutes, to a ZIP streamed on demand. scope `account`: your profile, memberships, owned documents with every version, your comments and reactions (an API key: its own workspace only, partial: true). scope `workspace`: everything in the workspace (owner only). manifest.json in the ZIP lists every item. Needs the read scope; limited to a few exports per hour (429).

**Request body** (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `scope` | `account` \| `workspace` |  |  |
| `workspaceId` | string |  | Default: the key's workspace. |

**Responses**

| Status | Meaning |
|---|---|
| 201 | The download link. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X POST "https://app.ollav.app/api/exports" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent" \
  -H "Content-Type: application/json" \
  -d '{"scope":"workspace"}'
```

Response (201):

```json
{
  "scope": "workspace",
  "workspaceId": "0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90",
  "downloadUrl": "https://app.ollav.app/api/exports/download?token=eyJ...",
  "expiresAt": 1793108258236,
  "partial": false
}
```

### Download an export {#downloadExport}

`GET /api/exports/download`

No API key: the signed link is the credential.

The `downloadUrl` returned by POST /api/exports. The signed token is the credential (no API key needed); access is re-checked when the download starts. Streams application/zip. Expired or invalid tokens get 404: request a new export.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `token` | query | string | yes | The signed token from downloadUrl. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | The ZIP (Content-Disposition attachment). |
| 400 | [BadRequest](#response-bad-request) |
| 404 | [NotFound](#response-not-found) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/exports/download?token=eyJ1aWQiOiJlOTcw..."
```

## Workspaces {#tag-workspaces}

Workspaces own documents. An API key is pinned to one workspace; managing workspaces (create, invite, remove) needs a signed-in browser session.

### List workspaces {#listWorkspaces}

`GET /api/workspaces`

The workspaces the caller belongs to (an API key: its user's memberships) and which is current; for an API key the current one is always the key's own. `billingNotice` is set when the current workspace's payment failed or it is over its plan's limits.

**Responses**

| Status | Meaning |
|---|---|
| 200 | Workspaces. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/workspaces" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
{
  "currentId": "0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90",
  "workspaces": [
    {
      "id": "0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90",
      "name": "Acme",
      "personal": false,
      "role": "owner"
    }
  ],
  "billingNotice": null
}
```

### List a workspace's members {#listWorkspaceMembers}

`GET /api/workspaces/{id}/members`

Members with their roles (owner > admin > member > guest) and the pending invites the caller may see. Guests and non-members get 404. Inviting and removing members needs the web UI.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | A workspace id, from GET /api/workspaces or GET /api/me. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Members and pending invites. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 404 | [NotFound](#response-not-found) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/workspaces/0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90/members" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
{
  "workspaceId": "0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90",
  "role": "owner",
  "members": [
    {
      "userId": "e970d2fd-66e4-4fa0-bac2-144f81995e32",
      "email": "ada@example.com",
      "name": "Ada",
      "role": "owner",
      "joinedAt": 1793107356443
    }
  ],
  "invites": []
}
```

## Billing {#tag-billing}

Read-only plan, usage and limits for a workspace. Plan changes happen in the web UI through Stripe Checkout and the Customer Portal.

### Get a workspace's plan, usage and limits {#getWorkspaceBilling}

`GET /api/workspaces/{id}/billing`

The workspace's plan, subscription, usage and limits (null = no limit), and which limits it is over. A workspace over a limit is read-only: reads work, writes that grow it answer 402. When billing isn't configured, `enabled` is false and there are no limits. Plan changes happen in the web UI (https://app.ollav.app/pricing). Members of the workspace; needs the read scope.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | A workspace id, from GET /api/workspaces or GET /api/me. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Billing overview. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/workspaces/0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90/billing" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
{
  "workspaceId": "0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90",
  "enabled": true,
  "role": "owner",
  "canManage": true,
  "plan": "free",
  "subscribedPlan": "free",
  "inGrace": false,
  "graceEndsAt": null,
  "lapsed": false,
  "subscription": null,
  "limits": {
    "documents": 3,
    "members": 1,
    "storageBytes": 52428800,
    "versionRetentionDays": 30,
    "apiCallsPerDay": 100
  },
  "usage": {
    "documents": 1,
    "members": 1,
    "storageBytes": 257,
    "apiCallsToday": 12
  },
  "overLimits": [],
  "readOnly": false,
  "pricingUrl": "https://app.ollav.app/pricing"
}
```

## Account {#tag-account}

Who the API key belongs to.

### Who am I {#getMe}

`GET /api/me`

The user the API key belongs to and the workspace it acts in. A cheap way to check that a key works.

**Responses**

| Status | Meaning |
|---|---|
| 200 | The caller. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/me" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
{
  "user": {
    "id": "e970d2fd-66e4-4fa0-bac2-144f81995e32",
    "email": "ada@example.com",
    "name": "Ada"
  },
  "workspace": {
    "id": "0f3c2a8e-1b7d-4c1e-9a52-6d1f0e4b7a90",
    "name": "Acme",
    "role": "owner"
  },
  "livemode": true
}
```

## API keys {#tag-api-keys}

Keys are created and revoked in the web UI (https://app.ollav.app/keys). The API lists them by prefix only; a key's secret is shown once, at creation.

### List API keys {#listApiKeys}

`GET /api/keys`

The caller's API keys in the current workspace, by prefix only (a key is shown in full once, when created). Create and revoke keys at https://app.ollav.app/keys.

**Responses**

| Status | Meaning |
|---|---|
| 200 | Keys, newest first. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl "https://app.ollav.app/api/keys" \
  -H "Authorization: Bearer $OLLAV_API_KEY"
```

Response (200):

```json
{
  "keys": [
    {
      "id": "00d97554-4eb5-4d98-b0da-b88d78d6f88e",
      "keyPrefix": "ol_live_mSos",
      "name": "Claude Code",
      "scopes": [
        "upload",
        "read",
        "comment"
      ],
      "createdAt": 1793107356443,
      "lastUsedAt": 1793107360365,
      "revokedAt": null,
      "apiVersion": "2026-11-01",
      "mode": "live"
    }
  ]
}
```

### Revoke an API key {#revokeApiKey}

`DELETE /api/keys/{id}`

Revokes one of the caller's API keys in the current workspace, at once and for good; requests with it then answer 401. A key can revoke itself, e.g. when an agent is done with it. Unknown ids and other people's keys get the same 404. Creating keys needs the web UI (https://app.ollav.app/keys).

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | The key's id, from GET /api/keys. |

**Responses**

| Status | Meaning |
|---|---|
| 200 | Revoked. |
| 400 | [BadRequest](#response-bad-request) |
| 401 | [Unauthorized](#response-unauthorized) |
| 402 | [PlanLimit](#response-plan-limit) |
| 403 | [Forbidden](#response-forbidden) |
| 404 | [NotFound](#response-not-found) |
| 409 | [Conflict](#response-conflict) |
| 429 | [RateLimited](#response-rate-limited) |
| 500 | [InternalError](#response-internal-error) |

```bash
curl -X DELETE "https://app.ollav.app/api/keys/00d97554-4eb5-4d98-b0da-b88d78d6f88e" \
  -H "Authorization: Bearer $OLLAV_API_KEY" \
  -H "X-Ollav-Client: agent"
```

Response (200):

```json
{
  "ok": true
}
```

## Error responses {#error-responses}

The error responses operations share. Each is the JSON error object described in [Basics](#basics); match on `code`, and see [the errors page](https://ollav.app/docs/errors) for every code's cause and fix.

### BadRequest {#response-bad-request}

The request is invalid; error.param names the field and error.hint the fix. Codes: BAD_JSON, BAD_REQUEST, VALIDATION_ERROR, MISSING_HTML, MISSING_FILE, MISSING_SLUG, EMPTY_BODY, EMPTY, NOT_HTML, INVALID_VISIBILITY, UNSUPPORTED_TYPE, UNSUPPORTED_CONTENT_TYPE, TOO_MANY_REACTIONS, CONFIRMATION_REQUIRED, INVALID_API_VERSION (an unknown Ollav-Version) and IDEMPOTENCY_KEY_INVALID.

### Unauthorized {#response-unauthorized}

No valid API key (AUTH_REQUIRED). The key is missing, wrong or revoked, or its user left the key's workspace.

### PlanLimit {#response-plan-limit}

The workspace's plan doesn't allow this (PLAN_LIMIT), it is over its limits and read-only (PLAN_READ_ONLY), or the key's workspace used its daily API calls. Tell the user; don't retry.

### Forbidden {#response-forbidden}

Not allowed: the key lacks a scope (SCOPE_REQUIRED), the X-Ollav-Client header is missing (CSRF_REQUIRED), a browser Origin is foreign (ORIGIN_FORBIDDEN), the caller's role is too low (ROLE_REQUIRED), or the action needs a browser session (FORBIDDEN).

### NotFound {#response-not-found}

Not found (NOT_FOUND), or archived (ARCHIVED). Missing, forbidden and other-workspace resources all return the identical 404 (apart from request_id).

### Conflict {#response-conflict}

Clashes with the current state (CONFLICT, e.g. the comment already has an image), or an Idempotency-Key problem: reused for a different request (IDEMPOTENCY_KEY_REUSED) or still in use by a running request (IDEMPOTENCY_KEY_IN_USE).

### PayloadTooLarge {#response-payload-too-large}

Over the size limit (TOO_LARGE): 15 MB per HTML document, 5 MB per image.

### RateLimited {#response-rate-limited}

Too many requests (RATE_LIMITED): over 30 publishes or 120 comments an hour per account (looser per IP), too many exports, or a test key (ol_test_) over its 60 requests a minute. error.retry_after and the Retry-After header say how many seconds to wait; don't retry in a loop.

### Gone {#response-gone}

The document was taken down for breaking the Terms of Service (DOCUMENT_REMOVED). Don't retry.

### InternalError {#response-internal-error}

Something failed on our side (INTERNAL_ERROR, type api_error). Retry once with the same Idempotency-Key; if it persists, report error.request_id.

## Machine-readable {#machine-readable}

- [OpenAPI 3.1](https://ollav.app/openapi.json): the source of this page
- [This page as Markdown](https://ollav.app/docs/api.md)
- [llms.txt](https://ollav.app/llms.txt): the Ollav docs index for LLMs

---

Page: https://ollav.app/docs/errors (updated 2026-10-27)

# Errors

Every `/api` error has the same JSON shape and a matching HTTP status. Match on `code`: codes are stable and are the closed list on this page. `type` groups them for coarse handling. `hint` says what to do next, written for an agent to act on. `request_id` is also in the `Request-Id` header of every response; quote it when reporting a problem.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "INVALID_VISIBILITY",
    "message": "visibility must be one of: workspace, link, public",
    "param": "visibility",
    "hint": "visibility must be 'workspace' (default), 'link' or 'public'. Only use 'public' if the user asked to share outside the company.",
    "doc_url": "https://ollav.app/docs/errors#INVALID_VISIBILITY",
    "request_id": "req_6f1c2a9b0d4e8f7a1b2c3d4e"
  }
}
```

| Field | Meaning |
|---|---|
| `type` | One of the 7 types below |
| `code` | What went wrong, machine-readable and stable |
| `message` | What went wrong, for people and models |
| `param` | The field or header at fault, when there is one |
| `hint` | What to do next |
| `doc_url` | This page, at the code's anchor |
| `request_id` | The request, for support (also the `Request-Id` header) |
| `docs` | Older link to the agent quickstart's error section, kept for existing clients |

Plan-limit errors (402) also carry `limit` and `plan`. MCP tool errors carry the same `code` and `doc_url` in the tool result.

## Retrying safely {#retrying}

Send an `Idempotency-Key` header (any unique string, e.g. a UUID) on every POST, PATCH and DELETE. If a request times out or fails with an `api_error` or `rate_limit_error`, retry it with the same key and body: it runs at most once, and a retry of a finished request returns the first response with `Idempotent-Replayed: true`. An error response doesn't use the key up: fix the request, or wait, and retry with the same key. Keys last 24 hours. Don't retry `invalid_request_error`, `authentication_error`, `permission_error` or `not_found_error` unchanged: they fail the same way again.

## Types {#types}

| Type | Meaning |
|---|---|
| [`invalid_request_error`](#invalid_request_error) | The request is wrong: a missing or invalid field, header or body. Fix the request; retrying it unchanged fails again. |
| [`authentication_error`](#authentication_error) | No valid credential. Check the API key. |
| [`permission_error`](#permission_error) | The caller may not do this: a scope, role, plan limit or a browser-session-only action. Tell the user; don't retry. |
| [`not_found_error`](#not_found_error) | No such resource for this caller. Missing and forbidden look the same, on purpose. |
| [`rate_limit_error`](#rate_limit_error) | Too many requests. Wait, then retry once. |
| [`idempotency_error`](#idempotency_error) | An Idempotency-Key problem: invalid, reused for a different request, or still in use. |
| [`api_error`](#api_error) | Something failed on Ollav's side. Retry once with the same Idempotency-Key; quote request_id if it persists. |

## invalid_request_error {#invalid_request_error}

The request is wrong: a missing or invalid field, header or body. Fix the request; retrying it unchanged fails again.

### `CSRF_REQUIRED` {#CSRF_REQUIRED}

HTTP 403 · param `X-Ollav-Client`

**Cause.** A state-changing request (POST, PATCH, DELETE) arrived without the X-Ollav-Client header.

**Fix.** Add the header 'X-Ollav-Client: agent' to every POST, PATCH and DELETE request, then retry.

### `LOGIN_CODE_INVALID` {#LOGIN_CODE_INVALID}

HTTP 400 · param `code`

**Cause.** The sign-in code is wrong, expired (codes last 15 minutes), already used, replaced by a newer email, or spent by 5 wrong tries. These look the same on purpose.

**Fix.** Check the code in the latest sign-in email. If it still fails, send a new code from https://app.ollav.app/signin.

### `BAD_JSON` {#BAD_JSON}

HTTP 400

**Cause.** The body isn't valid JSON.

**Fix.** The request body isn't valid JSON. Send Content-Type: application/json with a JSON object.

### `BAD_REQUEST` {#BAD_REQUEST}

HTTP 400

**Cause.** The request is malformed; the message says how.

**Fix.** The request is malformed. Check the body against https://ollav.app/openapi.json.

### `VALIDATION_ERROR` {#VALIDATION_ERROR}

HTTP 400

**Cause.** A field has an invalid value; the message and error.param name it.

**Fix.** A field has an invalid value; the message names it. Valid shapes are in https://ollav.app/openapi.json.

### `MISSING_HTML` {#MISSING_HTML}

HTTP 400 · param `html`

**Cause.** A JSON upload has no 'html' field.

**Fix.** JSON uploads need an 'html' string field: {"html": "<!DOCTYPE html>..."}. For files on disk use -F file=@page.html instead.

### `MISSING_FILE` {#MISSING_FILE}

HTTP 400 · param `file`

**Cause.** A multipart upload has no 'file' field.

**Fix.** Multipart uploads need the file in a field named 'file': -F file=@page.html.

### `MISSING_SLUG` {#MISSING_SLUG}

HTTP 400 · param `slug`

**Cause.** The document slug is missing.

**Fix.** Pass the document slug as ?slug=... (from the upload response or list_documents).

### `EMPTY_BODY` {#EMPTY_BODY}

HTTP 400 · param `html`

**Cause.** The HTML is empty.

**Fix.** The HTML was empty. Send the file with -F file=@page.html, a JSON body {"html": "..."}, or a text/html body.

### `EMPTY` {#EMPTY}

HTTP 400 · param `file`

**Cause.** The uploaded file is empty.

**Fix.** The upload was empty. Send a non-empty file.

### `NOT_HTML` {#NOT_HTML}

HTTP 400 · param `html`

**Cause.** The content doesn't look like HTML.

**Fix.** Send an HTML document (it should contain tags such as <html>, <body> or <div>). Upload a .html file with -F file=@page.html, a JSON body {"html": "..."}, or a text/html body.

### `INVALID_VISIBILITY` {#INVALID_VISIBILITY}

HTTP 400 · param `visibility`

**Cause.** visibility isn't workspace, link or public.

**Fix.** visibility must be 'workspace' (default), 'link' or 'public'. Only use 'public' if the user asked to share outside the company.

### `INVALID_EMAIL` {#INVALID_EMAIL}

HTTP 400 · param `email`

**Cause.** The email address isn't valid.

**Fix.** Send a valid email address.

### `UNSUPPORTED_TYPE` {#UNSUPPORTED_TYPE}

HTTP 400 · param `file`

**Cause.** The image isn't PNG, JPEG, WebP or GIF (checked by content; SVG is refused).

**Fix.** Comment images must be PNG, JPEG, WebP or GIF (SVG is refused), up to 5 MB.

### `UNSUPPORTED_CONTENT_TYPE` {#UNSUPPORTED_CONTENT_TYPE}

HTTP 400 · param `Content-Type`

**Cause.** The upload's Content-Type isn't multipart/form-data, application/json or text/html.

**Fix.** Use multipart/form-data (-F file=@page.html), application/json ({"html": ...}) or text/html.

### `TOO_LARGE` {#TOO_LARGE}

HTTP 413

**Cause.** Over the size limit: 15 MB per HTML document, 5 MB per image.

**Fix.** Ollav hosts one HTML file up to 15 MB. Shrink it: convert inlined PNG screenshots to WebP, downscale images wider than about 2000px, or load large media from absolute https:// URLs. Then upload again.

### `TOO_MANY_FILES` {#TOO_MANY_FILES}

HTTP 400 · param `file`

**Cause.** A multipart upload had more than one file. Each upload is one self-contained HTML file.

**Fix.** Send exactly one file in the 'file' field (-F file=@page.html). Inline the other assets into the HTML, or upload each page as its own document.

### `TOO_MANY_REACTIONS` {#TOO_MANY_REACTIONS}

HTTP 400 · param `reaction`

**Cause.** The comment already has 20 different reactions.

**Fix.** React with an emoji the comment already has, or leave it.

### `CONFIRMATION_REQUIRED` {#CONFIRMATION_REQUIRED}

HTTP 400 · param `confirm`

**Cause.** A deletion wasn't confirmed by typing the name.

**Fix.** Deletions need a signed-in session in the web UI and typing the name to confirm; an API key can't do them.

### `CONFLICT` {#CONFLICT}

HTTP 409

**Cause.** The request clashes with the current state; the message says how (e.g. the comment already has an image).

**Fix.** The thing already exists or the request clashes with the current state; the message says which. Don't retry unchanged.

### `SOLE_OWNER` {#SOLE_OWNER}

HTTP 409

**Cause.** The account is the only owner of a workspace other people use.

**Fix.** Transfer ownership first (POST /api/workspaces/{id}/transfer in the web UI), then delete the account.

### `CONSUMER_DOMAIN` {#CONSUMER_DOMAIN}

HTTP 400 · param `domain`

**Cause.** Public email providers (gmail.com and the like) can't be claimed as a workspace domain.

**Fix.** Claim your organisation's own domain instead.

### `TOO_MANY_MEMBERS` {#TOO_MANY_MEMBERS}

HTTP 409

**Cause.** The chosen plan is for fewer members than the workspace has.

**Fix.** Choose a plan that fits the workspace's members (Team is billed per member).

### `ALREADY_SUBSCRIBED` {#ALREADY_SUBSCRIBED}

HTTP 409

**Cause.** The workspace already has a subscription.

**Fix.** Change plans from Manage billing in the web UI instead of starting a new checkout.

### `NO_SUBSCRIPTION` {#NO_SUBSCRIPTION}

HTTP 409

**Cause.** The workspace has no billing account yet.

**Fix.** Upgrade first; the billing portal exists once there is a subscription.

### `METHOD_NOT_ALLOWED` {#METHOD_NOT_ALLOWED}

HTTP 405

**Cause.** Wrong HTTP method for this path.

**Fix.** Wrong HTTP method for this path. See https://ollav.app/openapi.json.

### `INVALID_API_VERSION` {#INVALID_API_VERSION}

HTTP 400 · param `Ollav-Version`

**Cause.** The Ollav-Version header names no API version.

**Fix.** Send one of the versions listed at https://ollav.app/docs/changelog in Ollav-Version, or leave the header out to use your key's pinned version.

## authentication_error {#authentication_error}

No valid credential. Check the API key.

### `AUTH_REQUIRED` {#AUTH_REQUIRED}

HTTP 401 · param `Authorization`

**Cause.** No valid credential: the API key is missing, wrong or revoked, or its user left the key's workspace.

**Fix.** Send the API key as 'Authorization: Bearer ol_live_...' (or ol_test_...). If you did, the key is wrong, revoked (rotating a key revokes the old one), or its user left the key's workspace: ask the user for a new key from https://app.ollav.app/keys.

### `ONBOARDING_EXPIRED` {#ONBOARDING_EXPIRED}

HTTP 401

**Cause.** The sign-up step timed out (it lasts 30 minutes).

**Fix.** Sign in again at https://app.ollav.app/signin to finish setting up the account.

### `SIGNATURE_INVALID` {#SIGNATURE_INVALID}

HTTP 400

**Cause.** A Stripe webhook's signature didn't verify.

**Fix.** Only Stripe calls this endpoint. Check STRIPE_WEBHOOK_SECRET matches the endpoint in the Stripe dashboard.

## permission_error {#permission_error}

The caller may not do this: a scope, role, plan limit or a browser-session-only action. Tell the user; don't retry.

### `SCOPE_REQUIRED` {#SCOPE_REQUIRED}

HTTP 403

**Cause.** The API key doesn't have the scope this endpoint needs (upload, read or comment).

**Fix.** This API key lacks a required scope. Ask the user to create a key with upload, read and comment at https://app.ollav.app/keys.

### `ORIGIN_FORBIDDEN` {#ORIGIN_FORBIDDEN}

HTTP 403 · param `Origin`

**Cause.** A browser sent the request from a foreign Origin.

**Fix.** Server-side clients should send no Origin header (curl and agents don't by default). Browsers may only call the API from https://app.ollav.app.

### `ROLE_REQUIRED` {#ROLE_REQUIRED}

HTTP 403

**Cause.** The caller's role in the workspace (owner > admin > member > guest) doesn't allow this.

**Fix.** The user's role in this workspace doesn't allow this. Tell the user rather than retrying; a workspace admin can change roles.

### `FORBIDDEN` {#FORBIDDEN}

HTTP 403

**Cause.** This caller may not do this; the message says why (often: it needs a signed-in browser session, not an API key).

**Fix.** This caller isn't allowed to do that; the message says why. Tell the user rather than retrying.

### `NOT_ALLOWED` {#NOT_ALLOWED}

HTTP 403

**Cause.** Sign-up is invite-only for this address.

**Fix.** Ask an existing Ollav member to invite this email address.

### `NO_WORKSPACE` {#NO_WORKSPACE}

HTTP 409

**Cause.** The account isn't a member of any workspace yet.

**Fix.** This account has no current workspace. The user should sign in at https://app.ollav.app once to finish setup.

### `TERMS_REQUIRED` {#TERMS_REQUIRED}

HTTP 400

**Cause.** The current Terms and Privacy Policy haven't been accepted.

**Fix.** The user must accept the current terms by signing in at https://app.ollav.app.

### `PLAN_LIMIT` {#PLAN_LIMIT}

HTTP 402

**Cause.** The workspace's plan doesn't allow this: a document, member, storage or daily API-call limit. error.limit says which.

**Fix.** This workspace has reached a limit of its plan; the message and 'limit' say which. Tell the user and don't retry.

### `PLAN_READ_ONLY` {#PLAN_READ_ONLY}

HTTP 402

**Cause.** The workspace is over its plan's limits, so it is read-only until it upgrades or makes room.

**Fix.** This workspace is over its plan's limits and is read-only: reading still works, adding doesn't. Tell the user and don't retry.

### `PLAN_REQUIRED` {#PLAN_REQUIRED}

HTTP 403

**Cause.** The feature (e.g. domain auto-join) isn't on the workspace's plan.

**Fix.** Tell the user this needs a plan that includes it; see https://app.ollav.app/pricing.

### `ACCOUNT_SUSPENDED` {#ACCOUNT_SUSPENDED}

HTTP 403

**Cause.** The account was suspended by Ollav for breaking the Terms of Service: sign-in, its API keys and MCP connections are all refused.

**Fix.** This account is suspended. Stop and tell the user; retrying or using another of its keys won't work.

## not_found_error {#not_found_error}

No such resource for this caller. Missing and forbidden look the same, on purpose.

### `NOT_FOUND` {#NOT_FOUND}

HTTP 404

**Cause.** No such resource for this caller. Missing, forbidden and other-workspace resources all look the same.

**Fix.** Check the slug or id. Slugs come from the upload response or list_documents (GET /api/dashboard). An API key only sees its own workspace, so documents elsewhere also return 404, and test and live are separate: an ol_test_ key sees only its own test documents (deleted 30 days after upload), a live key never sees them.

### `ARCHIVED` {#ARCHIVED}

HTTP 404

**Cause.** The document is archived (manually or because it expired).

**Fix.** The document is archived. Restore it with POST /api/documents/{slug}/unarchive (upload scope), or share a new one.

### `VERSION_NOT_FOUND` {#VERSION_NOT_FOUND}

HTTP 404

**Cause.** The version id doesn't belong to this document.

**Fix.** That version id doesn't belong to this document. List versions with GET /api/documents/{slug}/versions.

### `DOCUMENT_REMOVED` {#DOCUMENT_REMOVED}

HTTP 410

**Cause.** The document was taken down by Ollav for breaking the Terms of Service. Its page answers 410 and it takes no new versions.

**Fix.** This document was taken down and can't be published to or restored through the API. Tell the user; don't retry.

### `NO_VERSION` {#NO_VERSION}

HTTP 404

**Cause.** The document has no current version.

**Fix.** The document has no current version. Publish one with POST /api/documents/{slug}/versions.

## rate_limit_error {#rate_limit_error}

Too many requests. Wait, then retry once.

### `RATE_LIMITED` {#RATE_LIMITED}

HTTP 429

**Cause.** Too many requests of this kind in the window: more than 30 publishes or 120 comments an hour per account (looser limits apply per IP address), more than 10 abuse reports an hour per IP, too many exports, or more than 60 requests a minute with one test (ol_test_) key.

**Fix.** Too many requests. Wait error.retry_after seconds (also the Retry-After header; the message says it in words), then retry once with the same Idempotency-Key; don't retry in a loop. A test key allows 60 requests a minute.

### `TOO_MANY_REQUESTS` {#TOO_MANY_REQUESTS}

HTTP 429

**Cause.** Too many requests of this kind in a short window.

**Fix.** Too many requests. Wait before retrying and don't retry in a loop.

### `SIGNIN_RATE_LIMITED` {#SIGNIN_RATE_LIMITED}

HTTP 429

**Cause.** Too many sign-in emails or codes: more than 5 emails to one address, 20 emails from one network, or 30 code tries from one network in an hour.

**Fix.** Wait an hour before asking for another sign-in email (Retry-After says how long, in seconds), or sign in with Google.

## idempotency_error {#idempotency_error}

An Idempotency-Key problem: invalid, reused for a different request, or still in use.

### `IDEMPOTENCY_KEY_INVALID` {#IDEMPOTENCY_KEY_INVALID}

HTTP 400 · param `Idempotency-Key`

**Cause.** The Idempotency-Key header is empty, longer than 255 characters, or has characters outside printable ASCII.

**Fix.** Send 1-255 printable ASCII characters in Idempotency-Key, e.g. a UUID: Idempotency-Key: 5f0c3b1e-....

### `IDEMPOTENCY_KEY_REUSED` {#IDEMPOTENCY_KEY_REUSED}

HTTP 409 · param `Idempotency-Key`

**Cause.** This Idempotency-Key was already used in the last 24 hours with a different method, path or body.

**Fix.** Use a new Idempotency-Key for a new request. Reuse a key only to retry the identical request.

### `IDEMPOTENCY_KEY_IN_USE` {#IDEMPOTENCY_KEY_IN_USE}

HTTP 409 · param `Idempotency-Key`

**Cause.** A request with this Idempotency-Key is still being processed.

**Fix.** Wait a second and retry with the same key and body; you will get the first request's result.

## api_error {#api_error}

Something failed on Ollav's side. Retry once with the same Idempotency-Key; quote request_id if it persists.

### `R2_MISSING` {#R2_MISSING}

HTTP 404

**Cause.** The document's stored file is missing from storage.

**Fix.** Publish the document again (POST /api/documents/{slug}/versions). If it keeps happening, tell the user and include the request id.

### `INTERNAL_ERROR` {#INTERNAL_ERROR}

HTTP 500

**Cause.** Something went wrong on Ollav's side.

**Fix.** Retry once after a few seconds with the same Idempotency-Key. If it keeps failing, tell the user and include error.request_id.

### `PARSE_ERROR` {#PARSE_ERROR}

HTTP 502

**Cause.** The MCP server got a non-JSON response from the REST layer.

**Fix.** Retry once. If it keeps failing, tell the user and include the request id.

### `PROCESSING_FAILED` {#PROCESSING_FAILED}

HTTP 500

**Cause.** A Stripe webhook event couldn't be processed; Stripe retries it.

**Fix.** Nothing to do: Stripe retries the event.

### `STRIPE_ERROR` {#STRIPE_ERROR}

HTTP 502

**Cause.** The payment provider couldn't be reached.

**Fix.** Try again in a minute.

### `BILLING_CANCEL_FAILED` {#BILLING_CANCEL_FAILED}

HTTP 502

**Cause.** The subscription couldn't be cancelled before deleting, so nothing was deleted.

**Fix.** Try again in a minute; if it persists, cancel the plan from Manage billing first.

### `BILLING_NOT_CONFIGURED` {#BILLING_NOT_CONFIGURED}

HTTP 503

**Cause.** Billing isn't set up on this server.

**Fix.** Nothing to buy here: this server has no plans or limits.

### `EMAIL_SEND_FAILED` {#EMAIL_SEND_FAILED}

HTTP 502

**Cause.** The sign-in email couldn't be sent: the email provider refused it or couldn't be reached.

**Fix.** Try again in a minute, or sign in with Google.

### `EMAIL_NOT_CONFIGURED` {#EMAIL_NOT_CONFIGURED}

HTTP 503

**Cause.** Email sign-in isn't set up on this server.

**Fix.** Sign in with Google instead.

### `GOOGLE_NOT_CONFIGURED` {#GOOGLE_NOT_CONFIGURED}

HTTP 404

**Cause.** Google sign-in isn't set up on this server.

**Fix.** Use another sign-in method.

---

Page: https://ollav.app/docs/changelog (updated 2026-11-01)

# Changelog

Changes to the Ollav REST API, MCP server and docs, newest first. Feeds: [Atom](https://ollav.app/docs/changelog.atom), [RSS](https://ollav.app/docs/changelog.rss).

## API versions {#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.

| Version | Change | Notes |
|---|---|---|
| `2026-11-01` | POST /api/comments returns breadcrumbs as an array, like GET /api/comments | Latest: new API keys are pinned to it |
| `2026-10-01` | Baseline | The API before versioning; keys created before 2026-10-27 |

## 2026-11-01: POST /api/comments returns breadcrumbs as an array {#2026-11-01-post-apicomments-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 {#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](https://ollav.app/docs/errors).

## 2026-10-28: Email sign-in codes: LOGIN_CODE_INVALID and SIGNIN_RATE_LIMITED {#2026-10-28-email-sign-in-codes-logincodeinvalid-and-signinratelimited}

**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](https://ollav.app/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 {#2026-10-27-mcp-docs-a-rest-api-reference-two-quickstarts-and-typed-errors-on-every-mcp-error}

**Added**

New: [/docs/mcp](https://ollav.app/docs/mcp) (connecting each client, auth options, checking the connection, every tool with its inputs, outputs, annotations and an example, and troubleshooting), [/docs/api](https://ollav.app/docs/api) (every REST endpoint with a curl example, generated from the OpenAPI spec) and two quickstarts: [curl](https://ollav.app/docs/quickstart/curl) and [MCP](https://ollav.app/docs/quickstart/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 {#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 {#2026-10-27-test-mode-oltest-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](https://app.ollav.app/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 {#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 {#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 {#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](https://ollav.app/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 {#2026-10-27-openapi-spec-covers-every-public-endpoint}

**Added**

[/openapi.json](https://ollav.app/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`.

---

# Ollav API — Agent Reference

When to use Ollav: a user asks to share, preview, get feedback on or review an
HTML file, prototype, mockup or generated page. Publish it, give them the url,
read the comments back, publish a new version at the same url.
Quickstart for every MCP client: https://ollav.app/docs/agents

Ollav hosts HTML documents (prototypes, articles) at stable URLs and enables
element-anchored threaded comments. Humans use the web UI; agents use this REST API.

## Base URL

  https://app.ollav.app
  (Served HTML lives at: https://content.ollav.app/p/{slug})

## Authentication

All API endpoints accept an API key via the Authorization header:

  Authorization: Bearer ol_test_<key>

API keys have scopes: upload, read, comment. Create keys at /keys (web UI,
session required). Keys are shown once at creation and stored as SHA-256 hashes.

Keys come in two modes. ol_live_... keys work on the workspace's real data.
ol_test_... keys work in the key owner's own TEST sandbox of that workspace:
they can't see live documents (and live keys can't see test ones), nothing
counts towards the plan (each test key may make 60 requests a minute), test
documents are marked TEST and deleted 30 days after upload. GET /api/me returns "livemode": false for a test key, and
uploads return "livemode". The examples here use a test key; switch to a live
key to share with the team. Keys made before test mode start sk_live_ and are
live keys.

Each key belongs to ONE workspace — the one that was current when it was made.
Everything it uploads lands there, list endpoints show only that workspace,
and every other workspace's documents answer 404 (even ones the key's user can
reach from the browser). If its user leaves the workspace, the key stops working.

## Workspaces and roles

Documents, comments, attachments, snapshots and API keys all belong to a
workspace. Every user has a personal workspace and can create more (/workspace).
Roles: owner > admin > member > guest.
  guest   view, comment on and react to the documents shared with them — nothing else
  member  + every document in the workspace; upload documents and versions
  admin   + invite and remove members; manage any document in the workspace
  owner   + invite and remove admins
Comments are always members-only, whatever a document's visibility (a guest counts
only on the documents shared with them).

Sign-up: SIGNUP_MODE=open lets any Google account or magic-link email sign up; the
default (invite-only) needs an invite, a shareable invite link or a verified domain.
New accounts agree to the Terms and Privacy Policy on /welcome before their first
session, and again whenever either version changes.

Workspace endpoints (session sign-in; API keys only read their own workspace):
  GET    /api/workspaces                         your workspaces and the current one
  POST   /api/workspaces                         { "name" } — create; you become owner
  POST   /api/workspaces/current                 { "workspaceId" } — switch
  GET    /api/workspaces/{id}/members            members (+ pending invites for admins)
  POST   /api/workspaces/{id}/invites            { "email", "role"?, "expiresInDays"? } — single use,
                                                 only for that email; or { "link": true, "role"?,
                                                 "maxUses"? = 25, "expiresInDays"? = 14 }
                                                 → { "inviteUrl", "emailed" } — copy the link
                                                 whenever emailed is false
  DELETE /api/workspaces/{id}/invites/{inviteId} revoke an invite
  POST   /api/documents/{slug}/share             { "email" } or { "link": true, "maxUses"? } —
                                                 share one document with outside reviewers
                                                 (they become guests of just that document)
  GET    /api/documents/{slug}/share             its guests and live share links
  DELETE /api/documents/{slug}/guests/{userId}   stop sharing with a guest
  GET|POST /api/workspaces/{id}/domains          claimed email domains (plan feature, admins);
  POST   /api/workspaces/{id}/domains/{did}/verify  checks _ollav-challenge.{domain} TXT
  DELETE /api/workspaces/{id}/members/{userId}   remove a member (or yourself, to leave)

All state-changing endpoints also require:

  X-Ollav-Client: agent

This header is the CSRF guard. Always include it.

## Endpoints

### Upload a document

  POST /api/documents
  Scopes required: upload
  Content-Type: application/json (or multipart/form-data, or text/html)

  JSON body:
    { "html": "<html>...</html>", "title": "My Doc" }

  visibility: "workspace" (default) — members of the key's workspace only
              "link"      — anyone signed in to Ollav who has the URL (members comment)
              "public"    — PUBLIC: anyone with the URL, no sign-in, INCLUDING people
                            outside the company. The slug is unguessable, but there is
                            no access check. Only use for deliberate external sharing.
              ("authed", the pre-workspace default, is accepted as "workspace".)

  Response 201:
    { "url": "https://content.ollav.app/p/{slug}", "slug": "...", "documentId": "...",
      "versionId": "...", "hash": "...", "deduped": false, "versioned": false }

  Example (small inline document):
    curl -X POST https://app.ollav.app/api/documents \
      -H "Authorization: Bearer ol_test_..." \
      -H "X-Ollav-Client: agent" \
      -H "Content-Type: application/json" \
      -d '{"html":"<html><body>Hello</body></html>","title":"Test"}'

  Example (a file on disk — ALWAYS use this for built apps, see "Uploading a
  built app" below; curl reads the file, so an agent spends ZERO tokens on it):
    curl -X POST https://app.ollav.app/api/documents \
      -H "Authorization: Bearer ol_test_..." \
      -H "X-Ollav-Client: agent" \
      -F "file=@dist/index.html"

### List your documents

  GET /api/documents
  Scopes required: read

  Response 200: [ {...document, "url": "..."} ]  (a bare array; non-archived docs, newest first)

  Example:
    curl https://app.ollav.app/api/documents \
      -H "Authorization: Bearer ol_test_..." \
      -H "X-Ollav-Client: agent"

### Get a single document

  GET /api/documents/{slug}
  Scopes required: read

  Response 200: document object with versions array

### Add a new version

  POST /api/documents/{slug}/versions
  Scopes required: upload
  Content-Type: application/json

  Body: { "html": "...", "title": "optional" }

  Response 201: { "slug": "...", "versionId": "...", "hash": "...", "deduped": false }

  Example (file on disk — preferred when iterating on a build):
    curl -X POST https://app.ollav.app/api/documents/{slug}/versions \
      -H "Authorization: Bearer ol_test_..." \
      -H "X-Ollav-Client: agent" \
      -F "file=@dist/index.html"

  Example (small inline document):
    curl -X POST https://app.ollav.app/api/documents/{slug}/versions \
      -H "Authorization: Bearer ol_test_..." \
      -H "X-Ollav-Client: agent" \
      -H "Content-Type: application/json" \
      -d '{"html":"<html><body>Updated</body></html>"}'

### List versions

  GET /api/documents/{slug}/versions
  Scopes required: read

  Response 200: { "document": {...}, "versions": [...] }

### Post a comment

  POST /api/comments
  Scopes required: comment
  Content-Type: application/json

  Body (top-level):
    { "slug": "...", "body": "Great prototype!", "selector": "h1",
      "rect": {"x":0,"y":0,"w":100,"h":40}, "elementText": "Page title",
      "reproduceNote": "Click 'Launch simulation' first",  // optional, ≤300 chars
      "breadcrumbs": [{"selector":"button#launch","text":"Launch simulation"}],  // optional, ≤8 items
      "markEmoji": "💡"  // optional: show this emoji on the page instead of the numbered pin
    }

  Emoji mark with no text (a reaction pinned to an element):
    { "slug": "...", "selector": "h1", "rect": {...}, "markEmoji": "❤️" }

  Body (reply):
    { "slug": "...", "body": "Agreed!", "parentId": "<comment-id>" }

  reproduceNote: optional hint for reviewers on how to reproduce the UI state.
  breadcrumbs: optional array of {selector, text} interaction steps. Top-level only.
  Both fields are silently ignored for replies.

  Response 201: comment object (includes reproduceNote, breadcrumbs parsed)

  Example (top-level with reproduce info):
    curl -X POST https://app.ollav.app/api/comments \
      -H "Authorization: Bearer ol_test_..." \
      -H "X-Ollav-Client: agent" \
      -H "Content-Type: application/json" \
      -d '{"slug":"abc123","body":"Looks good","selector":"body","rect":{"x":0,"y":0,"w":1,"h":1},"reproduceNote":"Open modal first"}'

### Attach an image to a comment

  POST /api/comments/{id}/attachments
  Scopes required: comment
  Content-Type: multipart/form-data (field 'file') or a raw image body

  One image per TOP-LEVEL comment (replies cannot have attachments). Image type is
  validated by magic bytes (png/jpeg/webp/gif — SVG rejected); max 5 MB. Optional
  'width'/'height' form fields are layout hints. Stored content-addressed in R2 and
  served from the content origin: open for public docs, otherwise only to
  current members of the document's workspace.

  Response 201: { "id": "...", "url": "https://content.ollav.app/a/{id}[?vt=…]",
                  "mime": "image/png", "width": 1024, "height": 768, "size": 20481 }

  For non-public docs the url carries a short-lived ?vt token naming you; for public docs it is open.

### List comments

  GET /api/comments?slug={slug}
  Scopes required: read

  Each top-level comment includes "attachment": {url, mime, width, height} | null.

  Response 200:
    { "slug": "...", "currentVersionId": "...", "count": N, "unresolvedCount": N,
      "comments": [ { ...comment, "reproduceNote": "..." | null,
                       "breadcrumbs": [{selector,text}] | null,
                       "replies": [...] } ] }

### Read feedback for iteration (agent loop)

  GET /api/review?slug={slug}
  Scopes required: read

  An agent-shaped digest of feedback, leaner and more actionable than GET /api/comments.
  Query params:
    status  open (default) | resolved | all
    since   ISO 8601 or epoch-ms; return only threads with NEW activity after this.
            Pass the response's "cursor" back here next time for idempotent polling.
    format  json (default) | markdown — markdown returns a readable summary
            (text/markdown) of the same threads, ready to paste into a prompt.
            The JSON response always carries it too, as "markdown".

  Response 200:
    { "slug": "...", "title": "...", "url": "https://content.ollav.app/p/{slug}",
      "currentVersionId": "...", "filter": {"status":"open","since":null},
      "totalThreads": N, "openThreads": N, "returned": N,
      "cursor": "<iso>" | null,        // pass as ?since= next call
      "generatedAt": "<iso>",
      "note": "anchor.selector is rendered DOM; prefer quote/reproduceNote for source",
      "threads": [
        { "id": "...", "status": "open", "onCurrentVersion": true, "versionId": "...",
          "author": {"email":"...","name":"..."}, "createdAt": "<iso>", "lastActivityAt": "<iso>",
          "comment": "the feedback text ("" for an emoji-only mark)", "markEmoji": "💡"|null,
          "attachment": {"url":"…/a/{id}","mime":"image/png","width":N,"height":N} | null,
          "anchor": { "quote": "<element text — find THIS in your source>",
                      "reproduceNote": "..."|null, "breadcrumbs": [...]|null,
                      "selector": "<rendered-DOM selector>" },
          "replies": [ {"author":{...},"body":"...","createdAt":"<iso>"} ] } ] }

  onCurrentVersion:false means the thread was placed on an earlier build — its anchor
  may no longer exist in the current version.

### Resolve a comment

  POST /api/comments/{id}/resolve
  Scopes required: comment

### Unresolve a comment

  POST /api/comments/{id}/unresolve
  Scopes required: comment

### React to a comment

  POST /api/comments/{id}/reactions
  Scopes required: comment
  Body: { "reaction": "👍", "on": true }   (on:false removes it)
  Any single emoji. The default bar is 👍 ❤️ 🎉 👀 ✅; the old names "+1", "eyes",
  "check" and "heart" still work. At most 20 different reactions per comment.

### Delete a comment

  DELETE /api/comments/{id}
  Scopes required: comment

  Allowed for the comment's own author or the document owner. Top-level comments
  also delete all their replies. Returns { "deleted": true } on success.
  Returns 404 for unknown id or unauthorized callers (no existence leak).

### Dashboard (aggregate)

  GET /api/dashboard
  Scopes required: read

  Response 200: { "documents": [ { ...doc, versionCount, commentCount, unresolvedCount } ] }

### Archive a document

  POST /api/documents/{slug}/archive
  Scopes required: upload

  Archived documents return HTTP 410. Reversible via /unarchive.

### Unarchive a document

  POST /api/documents/{slug}/unarchive
  Scopes required: upload

### Update visibility

  PATCH /api/documents/{slug}
  Scopes required: upload
  Body: { "visibility": "workspace" | "link" | "public" }

  Switching to "public" makes the document PUBLIC — anyone with the URL, no
  sign-in, including people outside the company. Do this only when the person
  you are working for has asked for external sharing, and tell them you did.

  Example (deliberate external share):
    curl -X PATCH https://app.ollav.app/api/documents/{slug} \
      -H "Authorization: Bearer ol_test_..." \
      -H "X-Ollav-Client: agent" \
      -H "Content-Type: application/json" \
      -d '{"visibility":"public"}'

### Set/extend expiry

  POST /api/documents/{slug}/expiry
  Scopes required: upload
  Body: { "action": "extend" }           — adds 90 days from now
        { "action": "permanent" }         — removes expiry
        { "action": "custom", "expiresAt": <unix-ms> }

### Export document data

  GET /api/documents/{slug}/export
  Scopes required: read

  Returns full JSON bundle: document metadata + all versions (HTML inlined)
  + all comments/threads.

### Export your data (ZIP) — MCP: export_data

  POST /api/exports
  Scopes required: read
  Body: { "scope": "account" }     — your profile, memberships, the documents you
                                     own with every version, your comments and
                                     reactions (an API key: its workspace only)
        { "scope": "workspace" }   — everything in the key's workspace (owner only)
  Returns: { "downloadUrl": "...", "expiresAt": <unix-ms> }
  GET the downloadUrl (no auth header needed, valid 15 minutes) for a ZIP;
  manifest.json inside lists every item and file.

  Deleting a document, a workspace or an account needs a signed-in session in
  the web UI (an API key can't), and asks you to type its name.

## UPLOADING A BUILT APP (React/Vue/etc.) — read this before generating HTML

A bundled single-file app is megabytes. HOW it reaches Ollav decides whether that
costs nothing or costs a fortune:

  BAD   agent regenerates/pastes the bundle as an "html" string (JSON body, or the
        MCP share_html tool). Tool args are MODEL OUTPUT — every character is
        generated tokens. A 6MB build is slow, expensive, and frequently exceeds the
        model's per-response output limit, so it cannot be produced at all.
  GOOD  the BUNDLER writes one self-contained file to disk, then curl uploads that
        file. curl reads it from disk, so the agent spends ZERO tokens on content.

  # 1. Build one self-contained file (any bundler: vite-plugin-singlefile, webpack, …)
  npm run build          # -> dist/index.html with CSS/JS/assets inlined

  # 2. Upload the FILE (new document)
  curl -X POST https://app.ollav.app/api/documents \
    -H "Authorization: Bearer $OLLAV_API_KEY" -H "X-Ollav-Client: agent" \
    -F "file=@dist/index.html"

  # 3. Iterating? New version at the SAME url, comments preserved
  curl -X POST https://app.ollav.app/api/documents/$SLUG/versions \
    -H "Authorization: Bearer $OLLAV_API_KEY" -H "X-Ollav-Client: agent" \
    -F "file=@dist/index.html"

Raw-body form works too: -H "Content-Type: text/html" --data-binary @dist/index.html

EXCEPTION — no shell or no network egress (claude.ai / Cowork sandboxes): the MCP
tools are the only channel there, so a large build genuinely cannot be uploaded by
the agent. Build it, then upload the file by hand at https://app.ollav.app.

## LIMITATIONS

  - One self-contained HTML file per upload, maximum 15 MB.
  - Relative asset paths (src="assets/app.js", href="styles.css", src="img/logo.png") WILL NOT
    load — there is no multi-file hosting. Use absolute URLs (https://…), data: URIs, or inline
    the assets. Tools like vite-plugin-singlefile can bundle a project into one inlined file.
  - No server-side code — static serving only. Client-side JS calling external CORS-friendly
    APIs works fine.
  - SPA history routing: /p/{slug}/* sub-paths all serve the same document, so deep links and
    reloads work. The app's BrowserRouter determines whether the exact deep route is restored
    (set basename appropriately in your Vite app).
  - The upload and new-version endpoints return an advisory warnings[] array in the response
    body when relative asset references or a <base href> tag are detected. Uploads are never
    blocked — warnings are informational only.

## Error shape

  { "error": { "type": "invalid_request_error", "code": "ERROR_CODE",
               "message": "Human-readable message", "param": "field (when one is at fault)",
               "hint": "What to do next", "doc_url": "https://ollav.app/docs/errors#ERROR_CODE",
               "request_id": "req_...", "docs": "https://ollav.app/docs/agents#errors" } }

  Match on code (stable; every code is on https://ollav.app/docs/errors). Read hint before
  retrying. type is one of invalid_request_error, authentication_error, permission_error,
  not_found_error, rate_limit_error, idempotency_error, api_error. Every response has a
  Request-Id header (= error.request_id): quote it when reporting a problem.

  Common codes: AUTH_REQUIRED (401), SCOPE_REQUIRED (403), NOT_FOUND (404),
  CSRF_REQUIRED (403), VALIDATION_ERROR (400), TOO_LARGE (413),
  PLAN_LIMIT / PLAN_READ_ONLY (402), IDEMPOTENCY_KEY_REUSED (409)

## Safe retries (Idempotency-Key)

  Send Idempotency-Key: <unique string, e.g. a UUID> on any POST, PATCH or DELETE. A retry
  with the same key and the same request returns the first response (header
  Idempotent-Replayed: true) instead of acting twice. Same key, different request: 409
  IDEMPOTENCY_KEY_REUSED. Still running: 409 IDEMPOTENCY_KEY_IN_USE. Keys last 24 hours,
  per API key. MCP tools that change something take an idempotency_key argument.

## API versions (Ollav-Version)

  Breaking changes ship as dated versions. A request runs at the Ollav-Version header's
  version, else at the version the API key was pinned to when created (GET /api/keys →
  apiVersion). Responses carry the version used in an Ollav-Version header. Versions and
  changes: https://ollav.app/docs/changelog (Atom: https://ollav.app/docs/changelog.atom).

## Plans and limits (402)

  A workspace's plan (Free, Pro, Team — https://app.ollav.app/pricing) limits documents, members,
  storage, version history and API calls per day (UTC; every API-key request, REST or MCP,
  counts one). A write that would cross a limit returns 402:

  { "error": { "code": "PLAN_LIMIT", "message": "...", "limit": "documents" | "members" |
    "storageBytes" | "apiCallsPerDay", "plan": "free", "upgradeUrl": "...", "pricingUrl": "..." } }

  PLAN_READ_ONLY (402): the workspace is already over a limit (after a downgrade or a failed
  payment). Reading, exporting, archiving and deleting still work; uploads, versions, comments
  and reactions don't until the workspace is back within its limits. Don't retry a 402: tell
  the user. (REST bodies carry upgradeUrl for the web UI; MCP tool results state the limit only.)
  GET /api/workspaces/{id}/billing returns the plan, limits and usage.

## Quickstart (agent headless flow)

  # 1. Upload
  SLUG=$(curl -s -X POST https://app.ollav.app/api/documents \
    -H "Authorization: Bearer $KEY" -H "X-Ollav-Client: agent" \
    -H "Content-Type: application/json" \
    -d '{"html":"<html><body>v1</body></html>"}' | jq -r .slug)

  # 2. Comment
  curl -X POST https://app.ollav.app/api/comments \
    -H "Authorization: Bearer $KEY" -H "X-Ollav-Client: agent" \
    -H "Content-Type: application/json" \
    -d "{"slug":"$SLUG","body":"Feedback here","selector":"body","rect":{"x":0,"y":0,"w":1,"h":1}}"

  # 3. New version
  curl -X POST https://app.ollav.app/api/documents/$SLUG/versions \
    -H "Authorization: Bearer $KEY" -H "X-Ollav-Client: agent" \
    -H "Content-Type: application/json" \
    -d '{"html":"<html><body>v2</body></html>"}'

  # 4. Read feedback
  curl https://app.ollav.app/api/comments?slug=$SLUG \
    -H "Authorization: Bearer $KEY" -H "X-Ollav-Client: agent"

## Feedback loop (iterate on comments)

The intended cycle for acting on human feedback with an agent:

  1. READ    GET /api/review?slug=$SLUG            → open threads + a "cursor"
  2. EDIT    (regenerate the HTML from the feedback; use anchor.quote /
             anchor.reproduceNote to find each element in your SOURCE — the
             selector is rendered-DOM, not JSX)
  3. UPDATE  POST /api/documents/$SLUG/versions    → new build at the SAME url
  4. CLOSE   POST /api/comments/$ID/resolve         (optionally POST /api/comments
             with parentId to reply "fixed in v3 — …")
  5. POLL    GET /api/review?slug=$SLUG&since=$CURSOR  → only NEW activity

Because `since` is the high-water cursor from the previous call, step 5 is
idempotent — re-running it returns nothing until a new comment or reply lands.
This maps cleanly onto a polling driver (e.g. a scheduled task or Claude Code's
/loop): re-run get_review on an interval, and only act when `returned` > 0.
No always-on server is required — the agent is woken or polls, it does not sit
on a socket. (A push/webhook trigger is not offered yet; polling covers it.)

  # Read only what changed since your last build
  curl "https://app.ollav.app/api/review?slug=$SLUG&since=$CURSOR" \
    -H "Authorization: Bearer $KEY" -H "X-Ollav-Client: agent"

## MCP connector

Ollav exposes a native MCP (Model Context Protocol) endpoint for claude.ai, Cowork
sandboxes, and Claude Code — clients that cannot make direct egress POSTs but whose
MCP traffic routes through Anthropic.

Transport: Streamable HTTP (MCP spec 2025-03-26), stateless, JSON responses.

### claude.ai / Cowork setup

  Settings → Connectors → Add custom connector
  URL: https://app.ollav.app/mcp/ol_test_YOURKEY

  IMPORTANT: the URL contains your API key — treat it as a secret. Revoke it at /keys
  if it is ever exposed. The path-key form exists because claude.ai connectors cannot
  set custom HTTP headers.

### Claude Code

  claude mcp add --transport http ollav https://app.ollav.app/mcp \
    --header "Authorization: Bearer ol_test_..."

  Or interactively: /mcp add

### Available MCP tools

  share_html        — host HTML at a stable URL; returns the shareable URL (alias: upload_document)
  publish_new_version — update content at the same URL, keeps comments (alias: new_version)
  list_documents    — dashboard aggregate (version + comment counts)
  get_document      — metadata + version history for one document
  get_comments      — threaded comments with selector anchors and isCurrentVersion flags
  get_review        — agent-shaped feedback digest (open threads, source-findable anchors, polling cursor)
  add_comment       — pin an element-anchored comment (or reply to one)
  resolve_comment   — resolve or unresolve a comment thread
  react_to_comment  — add or remove an emoji reaction (👍 ❤️ 🎉 👀 ✅ or any emoji) on a comment
  delete_comment    — delete a comment and its replies (author or doc owner only)
  export_data       — signed link to a ZIP of your data (GDPR export)