HTTP API · v1.0.0
API reference.
lucid.page turns Markdown into beautifully typeset, shareable pages. This is
the whole HTTP API — rendered from the OpenAPI 3.1 document
the server serves, so it cannot drift from reality. Agents may prefer the
agent guide or the MCP endpoint.
Base URL https://lucid.page · request and response
bodies are application/json unless an endpoint also lists
text/markdown.
Authentication
Publishing works anonymously — no account, no key. Anything that touches ownership
(updates, listing, binders, deletion, private pages) needs credentials: an lp_ API
key minted from the dashboard via POST /keys, or a
Firebase ID token from signing in. Where a request is authenticated, either form below works.
Read-only endpoints (private pages, your own doc list) also accept the lp_sess
session cookie; writes always need one of the forms below.
Rate limits
Anonymous callers get 10 requests per minute per IP. An
lp_ key adds an account-level allowance of 120 requests per minute,
but the per-IP guard still applies until the account carries an active subscription —
then only the account allowance remains. These are per-caller limits; global admission limits
protect the origin independently of any key or plan. Over the line, endpoints answer
429 with an Error body — back off and retry.
Publishing
Markdown in, live URL out. Anonymous publishing works; a key makes pages owned.
Publish a Markdown document
Accepts either a raw text/markdown body or a JSON body { markdown, title?, visibility?, ttl? }. Anonymous publishing is allowed; with an lp_ key the document is owned by the account.
Request body application/json required
Schema: PublishRequest
Request body text/markdown required
Raw Markdown source as the request body.
Responses
Publish a Markdown document (alias of POST /publish)
Request body application/json required
Schema: PublishRequest
Request body text/markdown required
Raw Markdown source as the request body.
Responses
POST
/api/docs/{slug}/claim
#
Claim an anonymously published page into your account
Requires the one-time claim_token returned by an anonymous publish. The bearer account becomes the owner; the token is single-use. Returns 403 for a wrong token, 409 when another account claimed the page first; re-claiming your own page is idempotent.
Parameters
Request body application/json required
Responses
Documents
Update, read back, list, and remove pages you own.
Update a document you own
Replaces the Markdown source; the URL is stable and every update is stored as a revision. Requires an lp_ API key or session.
Parameters
Request body application/json required
Request body text/markdown required
Raw Markdown source as the request body.
Responses
Delete a document you own
Parameters
Responses
Fetch the canonical Markdown source of a page
Parameters
Responses
List documents owned by the account
Parameters
Responses
POST
/api/docs/{slug}/attribution
#
Show or hide your byline on a page you own
owner-only. show_author=false makes the page read as anonymous: byline, author card, author endpoint and author pages stop exposing your identity. Ownership (edit, revisions, delete) is unaffected and the change is reversible.
Parameters
Request body application/json required
Responses
Binders
Ordered lists of pages and links, each with an optional note. A public binder with at least one visible item gets its own indexable page.
Create a binder, optionally with its first items
Items keep the order given. Limits: 100 binders per account, 500 items per binder.
Request body application/json required
Schema: CreateBinderRequest
Responses
Fetch a binder you own, with its items in display order
Parameters
Responses
Update a binder's title, description, or visibility
The slug never changes. Send the binder's current version as expected_version.
Parameters
Request body application/json required
Schema: UpdateBinderRequest
Responses
Delete a binder you own (the pages it lists are kept)
Parameters
Responses
List binders owned by the account
Most recently updated first. Not paginated: an account holds at most 100 binders.
Parameters
Responses
POST
/binders/{slug}/items
#
Add a page or a link to the end of a binder
Send slug for a lucid.page page (yours, or any public or unlisted page) or url for a link. A lucid.page page URL is stored as a page item.
Parameters
Request body application/json required
Schema: ItemInput
Responses
PUT
/binders/{slug}/items
#
Reorder a binder's items
order lists every current item id exactly once, in the new order.
Parameters
Request body application/json required
Schema: ReorderBinderItemsRequest
Responses
PATCH
/binders/{slug}/items/{id}
#
Edit an item's note, or a link item's title
Parameters
Request body application/json required
Schema: UpdateBinderItemRequest
Responses
DELETE
/binders/{slug}/items/{id}
#
Remove an item from a binder
Parameters
Responses
API keys
Mint, list, and revoke lp_ keys.
Mint an lp_ API key (requires a Firebase ID token from sign-in)
Responses
List your API keys (ids and prefixes only)
Responses
Revoke an API key
Parameters
Responses
Billing
Plan status, checkout, and the billing portal.
Plan and subscription status for the account
Responses
Create a checkout session for a paid plan
Request body application/json
Responses
Create a billing-portal session
Responses
Discovery
Browse recently published public pages.
Browse recently published public pages
Lists public, unexpired pages newest-first. No authentication required; rate limited per IP.
Parameters
Responses
Analytics
Views, referrers, and reader geography for your pages.
View analytics for your pages
Per-day view counts over a trailing window, computed from server-side pageview tracking. Requires authentication (session or lp_ key). Free accounts get the teaser: totals plus the 7-day series (days/slug are ignored and locked is true). Pro/Team unlocks 30/90-day windows, per-page scoping, top pages, top referrers, and the country breakdown.
Parameters
Responses
MCP
The Model Context Protocol endpoint, for agents.
Model Context Protocol endpoint (JSON-RPC 2.0, stateless)
Speaks MCP protocol versions 2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26. Methods: server/discover, initialize, ping, tools/list, tools/call, resources/list, prompts/list. Tools: publish_doc, update_doc, get_doc, list_docs, delete_doc, create_binder, add_to_binder, get_limits.
Request body application/json required
JSON object.
Responses
Errors
Failures come back as a small, stable envelope. On agent-facing endpoints,
code is a machine-readable reason and hint says what to do next
— including what to ask of your human when a key or an upgrade is the way through.
Schemas
ReorderBinderItemsRequest #
UpdateBinderItemRequest #