> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useshareable.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Pages
> Create, list, retrieve, update, and delete pages.
All endpoints require an `Authorization: Bearer sm_…` header and live under `https://useshareable.com/api/v1`.
## The page object
Unique page ID.
URL slug. The page is served at `/p/{slug}`.
Full public URL.
Display title.
`link`, `people`, `private`, `password`, or `email_gate`. See [access levels](/publishing-and-access).
Your permission on the page (`owner` for pages you created via the API).
Invited emails (when `access` is `people`).
The invite list as `{ email, role }` objects (role is `view`). Kept in sync with `allowed_emails`.
The page password, for you to share (only on single-page responses — create, get, update, publish — when `access` is `password`; omitted from the list).
The page's accent color (e.g. `indigo`).
How the page was created (e.g. `mcp`, `upload`).
Whether search engines may index the page. Default `false`.
`single` for a one-file page, or `bundle` for a multi-page deck.
For a `bundle`, the file served at the deck root (e.g. `index.html`).
Number of HTML files (always `1` for a `single` page).
Whether a published version is live.
Whether the draft differs from the published version.
ISO timestamp of last publish.
Total recorded views.
If set, the link stops working after this ISO 8601 datetime.
If set, the link closes after this many views.
View-only: for a PDF/image, the download button is hidden and the file is shown inline only.
Whether the owner is emailed each time the page is opened.
Whether viewers can comment on the page.
Whether commenters must confirm an email first (`false` = anonymous).
**Pro.** Collect email-verified client sign-off — designated approvers Approve / Request changes on the page. Set `approver_emails` too.
The designated approver emails (used with `collect_approvals`).
`owner` (default — decisions private to you) or `shared` (approvers see each other's decisions).
Add a one-question poll to the page. Set `poll_question` + `poll_options` too.
The poll question.
The poll options (2–12).
Poll identity: `true` = verified email (one per person); `false` = anonymous (one per device).
Who sees results: `public` (default), `vote` (after voting), or `owner` (only you).
Show who voted for what (only with `poll_require_email`).
If set, the poll stops accepting votes after this ISO 8601 datetime.
For `people` access, whether invitees must sign in (vs the account-free email-confirm path).
For `people` access, whether blocked viewers can request access.
For `email_gate` access, whether personal email domains are blocked.
For `email_gate` access, the email domains allowed in (empty = any email).
Owner-set link-preview (unfurl) title, or `null` to fall back to the page's own OG tags.
Owner-set link-preview (unfurl) description, or `null` to fall back to the page's own OG tags.
***
## Create a page
POST /api/v1/pages
Pass **`html`** (or `html_base64` / `html_url`) for a single page, **`files`** for a multi-page
deck, or **`file_base64`** for a PDF or image — one of these per request.
Complete, self-contained HTML document (all assets inlined). For a single page, provide this
**or** `html_base64` **or** `html_url`. Up to your plan's per-file cap (Free 5 MB, Pro 50 MB,
Team 100 MB).
The single page's HTML, base64-encoded. base64 is ASCII, so it can't be mangled in transit —
use it to send HTML inline without risking emoji/Unicode (ZWJ) corruption. The server decodes it.
Still inline, so the request body cap applies (\~3–4 MB) — for larger HTML use `html_url`.
The HTML must be valid UTF-8 and non-empty, or you get a **`400`**.
A public `https` URL the server fetches the single page's HTML from, instead of inlining it —
so large HTML never passes through the model's token stream. Same SSRF protections as `file_url`
(private/internal/loopback/metadata hosts blocked, redirects re-checked per hop); up to your
plan's per-file cap.
Optional. Hex SHA-256 of the HTML **bytes**. The server hashes what it receives (from `html`,
`html_base64`, or `html_url`) and returns **`422`** on mismatch — a byte-perfect integrity guarantee.
Array of `{ path, html }` for a multi-page deck. Link between pages with relative
(`team.html`) or root-relative (`/team.html`) paths. Limits: up to 60 files, 2 MB per file,
12 MB per deck (HTML + assets combined).
For a deck: non-HTML files its pages reference with relative paths — images
(PNG/JPG/WebP/GIF/SVG/ICO), CSS, JS, fonts (WOFF/WOFF2/TTF/OTF), JSON. Array of
`{ path, data_base64 }`, e.g. `{ "path": "images/logo.png", "data_base64": "iVBOR…" }`.
Up to 60 assets, 5 MB each, within the 12 MB deck total. Assets are served behind the same
access controls as the deck's pages.
A **PDF or image** (PNG/JPG/WebP/GIF), shown inline. Base64-encoded; pass `filename` (and optionally
`mime`). The file must fit your plan's per-file cap (Free 5 MB, Pro 50 MB, Team 100 MB), and inlining
base64 also adds \~33% to the request body — for larger files prefer `file_url`. SVG, Office docs, and
spreadsheets aren't supported — export to PDF first.
A public `https` URL to fetch a **PDF or image** from instead of inlining it (up to your plan's
per-file cap — Free 5 MB, Pro 50 MB, Team 100 MB). Private, internal, loopback, and cloud-metadata
hosts are blocked, and redirects are re-checked per hop.
Original filename for a `file_base64`/`file_url` upload, e.g. `report.pdf` — sets the
title/download and the file type. Inferred from the URL when omitted with `file_url`.
For a deck, which file is the landing page. Defaults to `index.html`, else the shallowest file.
Display title.
`link`, `people`, `private`, `password`, or `email_gate`.
Emails allowed to view when `access` is `people`.
Password to protect the page when `access` is `password`. If omitted, one is generated and returned in the response.
When `false`, saves a private draft without going live.
Allow search-engine indexing.
Every field below is optional — omit them all for a simple share. They can also be set later via [update](#update-a-page).
[Link control](/guides/link-controls) — ISO 8601 datetime after which the link stops working (e.g. `2026-07-01T17:00:00Z`).
[Link control](/guides/link-controls) — close the link after this many views.
[Link control](/guides/link-controls) — view-only: hide the download button on a PDF/image and force inline viewing.
Email you each time the page is opened.
Link-preview (unfurl) title shown when the link is pasted in iMessage/Slack/social. Wins over the page's own OG tags; null/omitted falls back to them.
Link-preview (unfurl) description. Wins over the page's own OG tags.
Show a comments widget; everyone who can see the page sees the thread.
Comments identity. `false` (default) = anonymous: anyone can comment with no account (a display name is optional). `true` = each commenter confirms a one-time email link first; their email stays private.
For `people` access, require invitees to sign in instead of the email-confirm path.
For `people` access, let a viewer who isn't invited request access.
For `email_gate` access, block personal email domains (gmail, etc.).
For `email_gate` access, only allow these email domains, e.g. `["acme.com"]`.
**Pro.** Collect email-verified client sign-off — designated approvers Approve / Request changes on the page. Set `approver_emails` too.
The designated approver emails (used with `collect_approvals`), e.g. `["client@acme.com"]`.
`owner` (decisions private to you) or `shared` (approvers see each other's decisions).
Add a one-question poll to the page. Set `poll_question` + `poll_options` too.
The poll question.
The poll options (2–12), e.g. `["Look A","Look B"]`.
Poll identity: `true` = verified email (one per person); `false` = anonymous (one per device).
Who sees results: `public`, `vote` (after voting), or `owner` (only you).
Show who voted for what (only with `poll_require_email`).
ISO 8601 datetime after which the poll stops accepting votes.
A free account that enables a Pro setting (e.g. `collect_approvals`) gets a **`402`** with an explanatory message; the page isn't created. Titles are unique per account — a duplicate returns **`409`**.
```bash theme={null}
curl -X POST https://useshareable.com/api/v1/pages \
-H "Authorization: Bearer sm_your_key" \
-H "Content-Type: application/json" \
-d '{ "html": "Hi
", "title": "Demo", "access": "link" }'
```
Returns the [page object](#the-page-object) with status `201`.
```bash Expiring, view-limited link theme={null}
curl -X POST https://useshareable.com/api/v1/pages \
-H "Authorization: Bearer sm_your_key" \
-H "Content-Type: application/json" \
-d '{ "html": "Q3 board update
", "access": "password",
"expires_at": "2026-07-01T17:00:00Z", "max_views": 50 }'
```
```bash Multi-page deck theme={null}
curl -X POST https://useshareable.com/api/v1/pages \
-H "Authorization: Bearer sm_your_key" \
-H "Content-Type: application/json" \
-d '{
"title": "Acme deck",
"entry": "index.html",
"files": [
{ "path": "index.html", "html": "![](\"logo.png\")
Team" },
{ "path": "team.html", "html": "Team
" }
],
"assets": [
{ "path": "logo.png", "data_base64": "iVBORw0KGgo…" }
]
}'
```
The deck is served at `/p/{slug}` (the entry file) and each file — assets included — at
`/p/{slug}/{path}`.
***
## List pages
GET /api/v1/pages
Returns an array of the authenticated account's pages, most recently edited first (same order as the dashboard).
How many pages to return (1–200). Defaults to 100.
Skip this many results for paging through a large account.
The response includes a `next_offset` field — an integer to pass as the next `offset` when more
pages remain, or `null` when you've reached the end.
```bash theme={null}
curl "https://useshareable.com/api/v1/pages?limit=50&offset=0" \
-H "Authorization: Bearer sm_your_key"
```
***
## Retrieve a page
GET /api/v1/pages/{id}
```bash theme={null}
curl https://useshareable.com/api/v1/pages/PAGE_ID \
-H "Authorization: Bearer sm_your_key"
```
***
## Retrieve a page's HTML
GET /api/v1/pages/{id}/html
Returns the page's **current HTML** — the editable working copy, identical to what's live
unless there are unpublished changes. Read this to patch a page surgically instead of
rebuilding it from scratch.
For a single page the response is `{ kind: "single", html, has_unpublished_changes }`; for a
deck it's `{ kind: "bundle", entry, files: [{ path, html }], has_unpublished_changes }`. A
PDF/image artifact has no HTML and returns **`400`**.
```bash theme={null}
curl https://useshareable.com/api/v1/pages/PAGE_ID/html \
-H "Authorization: Bearer sm_your_key"
```
***
## Update a page
PATCH /api/v1/pages/{id}
Updating the HTML or `files` changes the **draft** only — call [publish](/api-reference/publishing) to push it live.
New HTML (saved as draft). Single pages only — not decks. Or send it byte-faithfully with `html_base64` / `html_url`. Up to your plan's per-file cap (Free 5 MB, Pro 50 MB, Team 100 MB). Read the current HTML first with [`GET /pages/{id}/html`](#retrieve-a-pages-html) to patch it in place.
New HTML as base64 (ASCII-safe — avoids emoji/Unicode corruption). Decoded server-side and saved as draft.
A public `https` URL the server fetches the new HTML from (SSRF-guarded), so large HTML skips the token stream. Saved as draft.
Optional hex SHA-256 of the HTML bytes; **`422`** on mismatch.
For a deck, the **full** new set of `{ path, html }` files (saved as draft). Files not included are
removed; same limits as create (60 files, 2 MB each, 12 MB total). Optionally pass `entry` to set the landing page.
For a deck, re-point the landing page to an existing file path.
`link`, `people`, `private`, `password`, or `email_gate`.
Set/replace the password (when `access` is `password`).
[Link control](/guides/link-controls) — expiry datetime, or `null` to remove it.
[Link control](/guides/link-controls) — view cap, or `null` to remove it.
[Link control](/guides/link-controls) — view-only for a PDF/image.
Email you each time the page is opened.
When `access` is `people`, let a viewer who isn't invited request access — you approve or deny by email or in the app. See [access levels](/publishing-and-access).
Show a comments widget on the page; everyone sees the thread. Anonymous by default — pair with `comments_require_email: true` to require a verified email. You moderate (hide/delete) from the Share dialog.
Comments identity. `false` (default) = anonymous (no account needed; display name optional). `true` = commenters confirm a one-time email link first; their email stays private.
For `people` access, require invitees to sign in.
For `email_gate` access, block personal email domains.
For `email_gate` access, the allowed email domains, e.g. `["acme.com"]`.
Link-preview (unfurl) title. Wins over the page's own OG tags; `null` clears it.
Link-preview (unfurl) description. Wins over the page's own OG tags; `null` clears it.
Email you each time the page is opened.
**Pro.** Collect email-verified client sign-off. Set `approver_emails` too.
The designated approver emails (used with `collect_approvals`).
`owner` or `shared`.
Add a one-question poll. Set `poll_question` + `poll_options` too.
The poll question.
The poll options (2–12).
Poll identity: verified email vs anonymous.
Who sees results: `public`, `vote`, or `owner`.
Show who voted for what (only with `poll_require_email`).
ISO 8601 datetime after which the poll closes, or `null` to remove.
Same error responses as create: enabling a Pro setting on a free account returns **`402`**, and a
duplicate title returns **`409`**.
```bash theme={null}
curl -X PATCH https://useshareable.com/api/v1/pages/PAGE_ID \
-H "Authorization: Bearer sm_your_key" \
-H "Content-Type: application/json" \
-d '{ "access": "private" }'
```
```bash Add an expiration + view-only theme={null}
curl -X PATCH https://useshareable.com/api/v1/pages/PAGE_ID \
-H "Authorization: Bearer sm_your_key" \
-H "Content-Type: application/json" \
-d '{ "expires_at": "2026-07-01T17:00:00Z", "download_disabled": true }'
```
***
## Delete a page
DELETE /api/v1/pages/{id}
Permanently deletes the page. Returns status `204`.
```bash theme={null}
curl -X DELETE https://useshareable.com/api/v1/pages/PAGE_ID \
-H "Authorization: Bearer sm_your_key"
```
***
## Versions
A version is saved automatically on each **publish** and each **edit** (deduplicated by content).
Named versions are kept forever; older unnamed ones are pruned.
### List versions
GET /api/v1/pages/{id}/versions
Returns `{ version_no, source, label, size_bytes, created_at }[]`, newest first. `source` is
`publish`, `edit`, or `restore`.
### Get a version
GET /api/v1/pages/{id}/versions/{version_no}
Returns the version's metadata plus its **full** content — `html` for a single page, or `files` + `entry` for a deck. (The MCP `get_version` tool previews long content by default; pass `full: true` there for the whole thing. To read the *current* page's HTML rather than a past version, use [`GET /pages/{id}/html`](#retrieve-a-pages-html).)
### Restore a version
POST /api/v1/pages/{id}/versions/{version_no}/restore
When `true`, also publish the restored content live. Otherwise it's restored to the draft only.
Restoring appends a new `restore` version. Returns the updated [page object](#the-page-object).
```bash theme={null}
curl -X POST https://useshareable.com/api/v1/pages/PAGE_ID/versions/3/restore \
-H "Authorization: Bearer sm_your_key" \
-H "Content-Type: application/json" \
-d '{ "publish": true }'
```
### Name a version
PATCH /api/v1/pages/{id}/versions/{version_no}
A name for the version (named versions are never pruned). `null` clears it.