Write a post to a phantom from a topic
One call takes a topic through research, writing, enhance, publish, and site rebuild. Prefer a spoke from the topic map so the map stays honest.
run_collection is the full pipeline in one call: draft a title from the topic, research it, write it with the collection's kernel, run the collection's passes, publish, and rebuild the site. It is the same call for a phantom and for a client blog: a phantom is a collection whose site we host, so the rebuild step is the only difference, and on a collection with no site it simply reports itself skipped.
Pick the topic from the map when you can
Every phantom has a topic map. list_topics returns its open spokes with ids. Running from a topic_id binds the post to that spoke, so the map marks it covered and the cadence never queues it again. A free-text topic works too, but it isn't bound to the map, so it's refused when the collection already has that post. A suggestion_id writes a headline from the collection's own pool (list_suggestions). Pass at most one of the three; pass none and the run takes the next open spoke by the same ranking the cadence uses.
"Write the 'Google News inclusion criteria' spoke." → run_collection { collection_id, topic_id }
"Write about what a payroll switch really costs." → run_collection { collection_id, topic: "…" }
CLI:
letterstory collection run --collection <id> --topic "…"
letterstory collection run --collection <id> --spoke <topic-id> --kernel <kernel-id>
letterstory collection run --collection <id> --headline <suggestion-id>
letterstory collection run-status <run-id>
HTTP: POST /api/collection/ingest/{public_id} with the run options as the body. The collection's public_id comes from list_collections. You get 202 with a run_id and a poll_url.
What you can set per run
Everything below defaults to the collection's own configuration (KB-604); set a field only to override it for this one post.
| Field | What it chooses |
|---|---|
topic / topic_id / suggestion_id | What to write. At most one; none means the next open spoke. |
source_urls | Up to 20 pages research reads first |
must_include | Up to 40 sections the outline must cover, on top of the template's |
research_depth | barebones or fleshed_out |
kernel_id | The writing voice for this post |
verify | Run the adversarial fact-check on the outline |
shred | Shred the composed prose |
mention_degree | off, subtle or woven. Forced off on a phantom, whatever you send |
approval_mode | autopilot, review_window, or manual for this run |
publish | false leaves the written draft; the run stops at ready, by design |
rebuild | Hosted only: false skips the site rebuild |
schedule_for | An ISO timestamp to publish at instead of now |
Cover style and visuals are collection settings rather than per-run ones: change them on the collection's file (KB-604) and every run follows.
Stages
scheduled → sourcing → writing → ready → publishing → published, with failed, skipped and cancelled as the ways it can end early. The whole thing takes 20 to 60 minutes, almost all of it in writing. Poll get_collection_run; the response carries the article_id as soon as the draft exists, then the published version and the rebuilt site at the end, plus five steps you can read one by one: source, write, review, publish, rebuild.
Every finished run also carries a verification block: whether it was sourced, written, kept independent of your brand, internally linked, illustrated, published, its spoke marked covered, and the site rebuilt. A check that did not apply reads skipped, never as a pass.
The approval gate
approval_mode decides what happens when the draft is ready. manual parks the run at ready until a person answers it (approve_collection_run, or the Control Room). review_window publishes after a hold. autopilot goes straight through. cancel_collection_run stops a run that is still in flight and puts its spoke back on the map.
Cadence, not credits
A phantom is bought as a site that keeps running, so its posts are not metered one by one. What a direct run spends is that week's cadence budget: the collection's posts per week, capped by your organization's cadence cap (six by default). A run past the budget is refused with a 429 rather than queued silently, so the API can add a post today but cannot blow past the plan. get_phantom_balance shows both numbers.
It publishes
This path marks the post published and rebuilds the site. If you want to read before it goes live, either pass publish: false, set approval_mode: "manual" and answer the gate yourself, or use the draft tools instead: ingest_article → run_arena → run_kernel (with article_id) → run_enhance_pass (KB-503), and publish yourself.
If the collection has no live site, the rebuild step reads skipped; the post is still published inside Letterstory.
Held posts
If the accuracy check holds the draft, the run finishes with the post unpublished and the site unchanged. Release it from Seers → Headlines → Held for review (KB-306).