Getting Started API

Setup

The Run buttons call the API using your signed-in FluidDocs session (credentials: include). If you are not signed in, Run sends you through sign-up / sign-in and returns you here. For scripts, CLI, and CI you use an API token instead. Tokens start with lit_live_; this page loads yours automatically (from the same cache the dashboard uses via Get Token, or by minting one via POST /api/v1/tokens) and drops it into every curl snippet.

Verify token

Create and update documents

Use the builder chat to create any HTML document from the dashboard, run a dedicated deck-build job when you need a presentation deck, copy and personalize existing documents, or have the agent tweak a document on your behalf. Each step below returns a projectId you can reuse in the next one.

Document creation

The unified builder is POST /api/v1/jobs/chat. Omit projectId (or pass "dashboard") to run in dashboard context — the same agent as the dashboard AI assistant. Describe the site or page you want; the agent writes files and deploys a new private document. Poll until status is done; the result includes the new projectId.

{ "message": "Create a landing page for …" }

curl -s '$BASE/api/v1/jobs/JOB_ID/result' -H 'Authorization: Bearer $TOKEN'

Deck from scratch

Describe the deck you want and we spin up a document plus a background build job. Pass autoconfirm: true for fully automated API flows (skips the interactive outline step). You can also attach branding files (logos, screenshots, PDFs) as base64 in the attachments array. The build agent reads them from its workspace and weaves them into the deck. Up to 5 files, 10 MB each.

{
  "attachments": [{
    "name": "logo.png",
    "type": "image",
    "mimeType": "image/png",
    "data": "<base64 bytes>"
  }]
}

curl -s '$BASE/api/v1/jobs/JOB_ID/result' -H 'Authorization: Bearer $TOKEN'

Templates

Org templates are reusable documents shared with everyone in your organization. After you create a document, mark it as a template so teammates can copy it from the gallery. To start from an existing template, list org templates and copy one into your workspace.

Mark as template

Turn any document you can edit into an org template. Visibility is set to org automatically.

List org templates

Copy

Copy duplicates any document you can access—your own documents, org-shared documents, public or unlisted documents, and templates. The source does not need to be a template. Optionally pass a prompt to launch an AI job that personalizes the copy for your use case (consumes credits). Without a prompt, you get an instant static duplicate.

Update with builder chat

Same agent as the dashboard builder: multi-turn, full write access. Point it at your projectId and describe the change. Run polls GET /jobs/:jobId/result when the job completes.

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

Update with agent task (one-shot)

Fire a single agent run with the builder toolset (read and write files). Handy for scripted edits: pass a clear prompt and poll for the result.

Upload your own documents

Already have HTML from Figma, Cursor, or your favorite editor? Upload it here and patch it with the REST API. Zip deploy bootstraps a document; draft, commit, and partial-update endpoints let you refine without re-uploading the whole file.

Zip deploy

Create a new document or replace an entire document from a base64-encoded zip. Returns projectId.

Create a new document

Redeploy an existing document

Replace all files by passing existingProjectId instead of name.

Write a file

The primary update method. Send the raw file body for any document path. Defaults to index.html; use ?path= for CSS, JS, etc. Add ?autocommit=true to publish immediately.

Commit draft

When autocommit is off, changes sit in the draft working copy until you commit. Commit promotes all draft files to live.

Partial updates

When you don't need to replace a whole file, use targeted edits: line-number patches, find/replace on raw bytes, or node ops on the DOM tree.

Line-number patch

Apply surgical edits to the stored draft HTML by line number. Line numbers are 0-based and refer to the document exactly as stored (split on newlines). This is the same compact patch format LLM agents use for scripted edits.

5[op:'replace']  <h1>Hello World</h1>
6[op:'insert-after']  <p>New paragraph</p>
10-12[op:'delete']

5-8[op:'replace']<<<
  <section class="hero">
    <h1>Replaced block</h1>
  </section>
>>>

Find/replace & append

Replace a substring or append bytes inside an existing file. Content is base64-encoded in JSON (max 200 KB).

Patch (find & replace)

Both find and replace are required and must be base64-encoded UTF-8 strings.

{
  "path": "index.html",
  "find": "Hello from the API",
  "replace": "Hi from patch"
}

Append to a file

Node ops

Target individual DOM nodes by stable ID. Read the draft to discover data-fe-id values, then apply ops via POST .../ops/apply. Enables ops mode on first call (stamps IDs on editable elements). No baseSeq or baseContentVersion required: the server rebases ops automatically. Prefer /ops/apply over POST .../ops for scripts and agents.

Read draft

Fetch the current draft HTML before crafting ops. Once a document enters ops mode, every editable HTML element carries a stable data-fe-id attribute (for example fe-3, fe-12). Use these IDs in ops to update individual nodes without rewriting the whole file.

OPS apply

Apply one or more editor ops against the server's canonical DOM tree. The request body is simply { "ops": [ ... ] }.

List documents

Look up projectIds for the files you just uploaded. Publishing and visibility are covered in Permissions & visibility.

List all documents

Get one document

Permissions & visibility

Deploy creates a private, unpublished project. The owner can always open it via /app/preview/:projectId. Making it reachable for others is two separate steps — publish a slug, then choose who can open the URL.

Set visibility

Change who can access the document. Switching to unlisted creates (or keeps) a shareToken and returns shareUrl. Switching away from unlisted clears the token — old share links stop working immediately.

Unlisted share link

Distribute the full shareUrl from set-visibility or GET /docs/projects/:id — including the ?t= query param. Sharing only the bare path returns 403. Unlisted responses also send X-Robots-Tag: noindex.

Publish a slug

Assign a public path for the document. Until this succeeds, there is no slug URL — only the owner preview. Slugs must be unique per account prefix (super-admin pages live at /<slug>; everyone else at /p/<slug>).

Unpublish

Clear the published slug. The document stays in your library; visitors lose the public path. Visibility is unchanged — set private separately if you also want to revoke share access.

Analytics

Track how people use your documents, push your own events, and pull the data back through the API. Page opens are recorded automatically when someone loads a published or unlisted URL (owners are excluded). You can also push custom events yourself.

Push events

Best-effort tracking endpoint. Returns 202 immediately. Use any eventType string (built-ins: resource_visit, cta_click, cta_email_capture), an optional subType label, and flat extra primitives.

Query events

General-purpose query for activity you pushed (or that the viewer tracked). Returns full extra payloads, pagination, and a dataRange for the filtered result set.

Query visit stats

Aggregated main-page visit totals for a document (section / custom events are excluded from these counts).

Query visitors

Recent unique sessions for a document, with geo and optional email when captured.

Query viewer chats

List Ask-AI conversations from document viewers (not builder chat). Same auth as the rest of the docs API. Use GET /viewer-chats/:jobId for a full transcript.

Other AI endpoints

Beyond document creation and updates, FluidDocs exposes a few more AI surfaces: a read-only one-shot agent for extraction and analysis, plus visitor chat on published pages (with optional grounded RAG).

One-shot agent (read-only)

Fire-and-forget agent for scripts and automation. With readOnly: true the agent gets the viewer toolset only (list, read, grep). It sees your owner draft but cannot write files. Perfect for extracting metadata or summarizing content.

curl -s '$BASE/api/v1/jobs/JOB_ID/result' -H 'Authorization: Bearer $TOKEN'

Enable viewer chat

Viewer chat is disabled by default on new documents. Turn it on programmatically before visitors can use the chat widget on a published page. You can also configure labels, suggested questions, and other options in the dashboard Libraries panel.

Viewer chat (visitor Q&A)

Public endpoint on published documents (no API token). Visitors get a session cookie (_lt_sid). The agent is read-only and cannot edit the document. The document must be published and viewer chat must be enabled (see above).

Ungrounded (default)

Without indexing, the agent answers from the live page HTML and read-only file tools. Good for quick Q&A on what visitors can already see. Try it below before setting up grounded mode.

curl -s '$BASE/p/_view/PROJECT_ID/jobs/JOB_ID/result'

Grounded viewer chat

Grounded mode uses a vector index of your document files so visitor questions are answered with retrieval-augmented generation (RAG) instead of only browsing files at question time. The flow is: enable viewer chat, publish, index content, turn on groundedAnswers, then visitors can query via the same chat endpoint.

Indexing

Indexing uploads document files to an OpenAI vector store and records vectorStoreId on the document. Run an index job after deploys or major content changes so grounded answers stay in sync. While indexing runs, the server sets indexingJobId on viewer-chat settings; when complete it stores lastIndexedAt and clears the in-flight job id.

After a successful index, enable grounded answers on the same document:

PATCH /api/v1/docs/projects/:projectId
{ "libs": { "viewer-chat-settings": { "enabled": true, "groundedAnswers": true } } }

With groundedAnswers: true and a completed index, use the same POST /p/_view/:projectId/jobs/chat endpoint above. Answers are RAG-backed from your vector store.