Publish a tale with taleseal

A tale is the page your AI hands over when the work is done: a designed document of typed blocks (words, tables, charts, diagrams, code, screenshots) drafted at a private link, revised in plain words on that same versioned link, then published and sent. The reader opens the link and reads; they never need an account. It is the deliverable layer of AI work: where the output lands, gets shared, and stays updatable.

You do not build the page. Your AI chooses the blocks and the words; the renderer owns every pixel, and the account's brand (set once by a human in the dashboard) is applied automatically. The page lives at taleseal.com/t/<id>.

Four properties define the flow:

• Draft at the final URL. draft creates the tale at its real address with a DRAFT banner; only publishing removes it. A human reviews the draft in the browser before any reader sees it.
• Revise in place. A published tale keeps a stable link. Revising stores a new draft behind it; the reader keeps seeing the last published revision until you publish again.
• Edited by block id, not by resending. After the first draft, your AI edits one block at a time under optimistic concurrency, reading a compact outline between edits, never re-sending the whole document.
• Retraction destroys everything. The body and every revision are erased; the URL answers 410 Gone forever. There is no undo.

Four surfaces, one document

Pick the surface that fits how your AI runs. All four compose the same tale and funnel through the same validation and editing rules, so they cannot drift.

The full block vocabulary, the draft-review-publish flow, and worked examples for every surface live in one place:

• The tale reference: the nineteen block kinds, the envelope, the CLI/SDK/MCP/HTTP calls, and the rules that make a page worth opening.
• Component gallery: every block kind rendered live by the real renderer, beside the JSON that produced it.

Authentication

Publishing under an account needs a tk_… API key (dashboard → API keys; sign up at taleseal.com/signup). The quickest path on a developer machine:

npx -y taleseal@latest login   # opens the browser, signs you up if needed, stores the key

For CI, servers and the SDK, set it as an environment variable instead:

export TALESEAL_API_KEY=tk_your_key_here

On the wire every keyed write carries Authorization: Bearer tk_…. A write may also send x-taleseal-client: <name>/<version> to attribute itself. Pick any name; it is optional, and a request naming nothing still goes through.

No key at all? Publish anonymously

The one exception to the draft → review → publish flow: POST /v1/tales/anonymous (CLI: draft with no key set anywhere, or --anon; SDK: anonymous: true) needs no account and no key, and takes no Authorization header at all (sending one is a 400). The page is published the moment the POST lands, live at its final /t/<id> URL. In exchange:

• Immutable. No revise, publish, retract or block ops, and no image blocks (422), no MCP, no proof layer.
• Visibly unclaimed. No brand or logo, an "Unverified" sender, outbound links rendered as plain text, a generic unfurl, and a banner naming the deadline.
• Deleted after 24 hours, unless a human opens the once-shown claimUrl from the response and signs in (free) to keep the page. Claiming transfers ownership of the already-live page and restores its links; it does not publish anything.
• Tightly bounded. A few creates per IP per minute, under a global cap on live unclaimed pages (503 at capacity).

Relay the claimUrl to your human immediately: it appears once, in that response, and never again.

A word on privacy

A tale is anonymous by unguessable id: every page sends noindex, is never listed, and its body is never logged. Anyone holding the link can read it, so strip test identifiers and customer PII before publishing, and reach for retract if a secret ever ships. The CLI runs a client-side redaction and exposure check before anything leaves the machine.

Machine-readable resources

• Append .md to any page under /integrate for raw markdown, e.g. taleseal.com/integrate/tales.md.
• The same URLs answer Accept: text/markdown with raw markdown.
• taleseal.com/llms.txt indexes everything here.

Integration overview · llms.txt · panic path: npx -y taleseal@latest retract <id> (or DELETE /v1/tales/<id>)