Documents API guide

Setup

Run uses your FluidDocs session (credentials: include); if you are not signed in it sends you to sign in and back here. Scripts, servers and CI use an API token instead (Authorization: Bearer lit_live_…). This page loads yours and puts it in every curl snippet. Every endpoint accepts either.

1Create a document

One endpoint creates every document type. Send the type and a description of what you want; the document exists as soon as the call returns (run.projectId), and AI fills it in the background. The response is a run, which you poll until it is done.

Send an Idempotency-Key header so a retried request (a timeout, a crashed worker) never creates a second document: the same key returns the same run with 200.

Check the run

Poll every couple of seconds until run.status is done, error or cancelled. run.currentStep names the stage in progress, and run.result carries what the stages report so far (a deck's slideCount counts up as slides are saved). Prefer a push? GET …/stream sends the same run as server-sent events.

while :; do
  RUN=$(curl -s "$BASE/api/v1/workflows/runs/$RUN_ID" -H "Authorization: Bearer $TOKEN")
  STATUS=$(echo "$RUN" | jq -r .run.status)
  case "$STATUS" in done|error|cancelled) break;; esac
  sleep 2
done

curl -N '$BASE/api/v1/workflows/runs/$RUN_ID/stream' -H 'Authorization: Bearer $TOKEN'

2Embed the editor

Put the document inside your own product with one <iframe> pointing at /p/_iframe/:projectId/?embed=native. This is a native embed: the document runs its own editing UI (a text document's toolbar and A4 pages, a spreadsheet's grid, a deck's slide bar), with no FluidDocs app around it. Editing, undo/redo and saving are always there; ?features= adds Edit with AI (edit-ai) and Export PDF (export). Changes made through the API show up in it live.

3Update it with AI

The builder chat edits a document from a plain-language request: the same agent as Edit with AI in the editor. Send the projectId and a message; you get a jobId back at once, then poll the job until it is done. Watch the editor above: Run reloads it when the job finishes.

curl -s '$BASE/api/v1/jobs/$JOB_ID/result' -H 'Authorization: Bearer $TOKEN'
curl -N '$BASE/api/v1/jobs/$JOB_ID/stream?afterSeq=-1' -H 'Authorization: Bearer $TOKEN'

4Publish & share

A new document is private, and only you can open it. Sharing it takes three calls: commit the draft so it becomes the live version, give the document a public address (a slug), and choose who may open that address.

4.1 Commit the draft

4.2 Publish at a slug

4.3 Choose who can open it

unlisted is the usual choice for sharing: anyone with the returned shareUrl can open the document, it isn't listed or indexed, and switching away from unlisted turns the link off at once. public opens the plain url to everyone.

4.4 Read back the links

5Download a PDF

A PDF export is a job, like the AI edit in step 3: start it, poll it until it is done, then download its file. No AI runs and it costs no credits. You export the version you can edit: the draft, with any changes not yet committed. Someone who can only read the document exports the published one.

Text documents print on A4 sheets, page by page as in the editor; pages and spreadsheets print the way Chrome prints them. Decks have their own route, /jobs/export-deck-pdf, with one 1440×810 page per slide; the guide picks it when your document is a deck. It is the same export as the editor's Export PDF button (the export embed feature).

curl -s '$BASE/api/v1/jobs/$PDF_JOB_ID' -H 'Authorization: Bearer $TOKEN' | jq .status
curl -s '$BASE/api/v1/jobs/$PDF_JOB_ID/artifact' -H 'Authorization: Bearer $TOKEN' -o document.pdf

That's the whole loop. From here, repeat steps 3 and 4.1 for each change: the slug and the share link stay the same and show the newest committed version.

Reference

The details behind the steps above, and the calls the guide didn't need. The snippets use the ids from your run of the guide. Base path: /api/v1. Every endpoint accepts a session or Authorization: Bearer lit_live_….

Creation runs

Document types & inputs

Every type takes description (3–2000 characters), name (kept as the document's name; otherwise it is named from the plan), folderId, and blank: true (or the description "Empty doc") for the type's empty document, with no AI.

Deck input:

Read, rename, delete

Remove the document this guide created:

Drafts & other ways to edit

Examples for each are in the REST API docs: write a file, partial updates, agent task.

Visibility & permissions

• Password: unlisted documents can ask for a password — { "visibility": "unlisted", "requirePassword": true, "password": "…" } (6–128 characters). Setting a new one locks every visitor out until they enter it.
• Email gate: requireEmail: true asks visitors of an unlisted document for their email first.
• New share link: switch to private and back to unlisted; the old link stops working.
• Unpublish: DELETE /docs/projects/:id/publish removes the slug. Visibility is unchanged.
• Fine-grained permissions (Pro): POST /docs/projects/:id/set-perms { org, others }, each a sum of LIST=1, WRITE=2, READ=4. For example org: 6 lets your organization read and edit.

Embedding options

Two ways to embed a document. The guide uses the first.

• Where it can be framed: only allowed sites can put the editor in an iframe (FluidDocs itself, localhost, and partner domains). Ask us to add yours. A read-only view of a published document can go anywhere: frame its url.
• Sign-in: the viewer signs in to FluidDocs from the embed's Log in button (it opens a new tab), then reloads. Safari blocks the session in cross-site iframes, and Chrome keeps it per site.
• Viewers without a FluidDocs account: your server can mint a short-lived token that lets the embed act as the document's owner for that document only: POST /docs/projects/:id/delegate-ownership returns an embedUrl with ?del=lit_del_… (24 hours; revoke with …/delegate-ownership/revoke).
• Reacting to changes on your side: the iframe doesn't post save or publish events. Read GET /docs/projects/:id (hasPendingDraft, url) from your server.

MCP tools

The FluidDocs MCP server exposes the same calls to agents:

Errors