REST API (v1)

Most teams publish through the dashboard or MCP tools. The REST API is for scripts, CI, and non-MCP integrations.

Base URL: https://unfurl.pub
Auth: Create a key at Dashboard → API keys, then send X-Api-Key: oodoc_… or Authorization: Bearer oodoc_… on every request.

Endpoints

Method	Path	Purpose
`POST`	`/api/v1/publish`	Publish HTML (create or full replace). Returns `document_id`, `version_id`, `share_url`.
`POST`	`/api/v1/documents/:id/edit`	Search/replace on current HTML; new version, same link.
`GET`	`/api/v1/documents`	List documents. Optional `?slug=` (exact) or `?q=` (title search).
`GET`	`/api/v1/documents/:id`	Metadata + versions. `?include_html=true`; `?version=current\|all\|<uuid>` (default `current`).
`PATCH`	`/api/v1/documents/:id`	Update `title` and/or `description` only.
`DELETE`	`/api/v1/documents/:id`	Delete document permanently (`204`).
`GET`	`/api/v1/me`	Workspace, plan, entitlements, document count.
`GET`	`/api/v1/documents/:id/feedback`	Viewer feedback list.
`POST`	`/api/v1/documents/:id/feedback/:fid/resolve`	Mark a feedback item resolved. Body: optional `{ "note": "…" }`.

MCP maps to these routes: publish_document, edit_document, get_document, update_document, delete_document, list_documents, find_document, get_workspace_info, list_feedback, resolve_feedback.

Publish body (`POST /api/v1/publish`)

Field	Type	Required	Description
`title`	string	Yes	1–500 characters
`html`	string	Yes	Full HTML, up to 4 MB (UTF-8 bytes)
`document_id`	uuid	No	Append a version to an existing document (full HTML replace)
`note`	string	No	Version note, up to 2000 characters

Success (200):

{
  "document_id": "…",
  "version_id": "…",
  "share_url": "https://unfurl.pub/d/…"
}

Edit body (`POST /api/v1/documents/:id/edit`)

Field	Type	Required	Description
`edits`	array	Yes	1–100 items
`edits[].old_string`	string	Yes	Exact current HTML snippet
`edits[].new_string`	string	Yes	Replacement; `""` deletes
`edits[].replace_all`	boolean	No	Replace every match
`note`	string	No	Version note

Matching is literal. The batch is atomic. Success (200) includes share_url and a summary. Common errors: 422 edit_not_found / edit_ambiguous / no_change; 413 if the result exceeds 4 MB. Full semantics: edit_document.

`GET /api/v1/me`

Success (200): { "workspace": { "id", "name", "brand_name", "brand_tagline", "plan", "document_count", "entitlements" } }.

Limits and rate limits

HTML size: 4 MB per document (publish, edit, and dashboard upload). Inlined base64 images are the usual way to blow this — host images at a URL instead.
Free plan: 5 documents, 1 API key. Pro removes those caps. See Plans and billing.
Writes: publish and edit are rate-limited per API key (default 60 requests per 60 seconds). If you are throttled, wait and retry.
Passphrase unlock and viewer feedback submits are also rate-limited per IP / token.

​REST API (v1)

​Endpoints

​Publish body (POST /api/v1/publish)

​Edit body (POST /api/v1/documents/:id/edit)

​GET /api/v1/me

​Limits and rate limits

MCP overview

edit_document

REST API (v1)

Endpoints

Publish body (`POST /api/v1/publish`)

Edit body (`POST /api/v1/documents/:id/edit`)

`GET /api/v1/me`

Limits and rate limits