Collections

A standing publication in, published posts out, on a cadence.

The content engine as a primitive. A collection sources, writes, gates and publishes a post each run. A Phantomstory is a collection Letterstory hosts as its own publication.

Unit: Collection
A run produces: one post: sourced, written, gated, published and, when hosted, the site rebuilt
In the app: /letterbases
API reference: All collections tools

Try it

run_collection over REST: POST /api/collection/ingest/{collection_id}. Needs an API key with collection:write.

curl -X POST https://app.letterstory.com/api/collection/ingest/<collection_id> \
  -H "x-integrations-key: ls_..." \
  -H "content-type: application/json" \
  -d '{
  "topic": "...",
  "topic_id": "...",
  "suggestion_id": "...",
  "source_urls": [],
  "must_include": [],
  "research_depth": "...",
  "kernel_id": "...",
  "verify": false,
  "shred": false,
  "mention_degree": "...",
  "approval_mode": "...",
  "publish": false,
  "rebuild": false,
  "schedule_for": "..."
}'

1. Constraints: what you configure

The endpoint's config file

nameidentitycontentcadencepublishingtargetsmeasurement

Per call

topictopic_idsource_urlsmust_includeresearch_depthkernel_idshredapproval_modepublishschedule_for

The whole collection is one config file: identity, content, cadence and publishing. A phantom is a profile of it, not a separate path. Topic context resolves company → offering → collection, each layer storing only its overrides.

2. Mechanism: what always happens

1Source a topic: the one you gave, a spoke of the topic map, or the next open spoke.
2Write through Auto-Pen: an arena run, a kernel run, then links, visuals, metadata and an optional shred.
3Gate by the approval mode, then publish to the platform, your connected CMS, or as advisory only, and mark the spoke covered.
4Rebuild the site when Letterstory hosts it. A 90-minute writing deadline and retry with backoff are always on.

3. Intelligence: who picks values

You, directly

An API key or a person pressing Write now picks the topic and overrides anything per run.

Letterstory, for you

Letterstory's planner decides which spoke to write and when; onboarding seeds the identity, topic map, cadence and first posts.

4. Verification: did it hold

Check	Reads back	Rule
`sourced`	`research_depth`	Research ran and was sourced.
`written`	`kernel_id`	The kernel run settled with its own checks.
`independent`	`identity.brand_subject`	An independent collection never names the client.
`linked`	`mechanism`	At least one internal link resolved.
`illustrated`	`content.cover`	A cover is present, unless none was asked for.
`published`	`publish`	The publish outcome exists.
`covered`	`mechanism`	The spoke is marked covered by this post.
`rebuilt`	`publishing.rebuild`	The site was redeployed (hosted only).

Report-only; a skip is never read as a pass.

Surfaces

Same call over MCP (tools/call) and REST.

Job	MCP tool	REST
Run	`run_collection`	`POST /api/collection/ingest/{collection_id}`
Poll a run	`get_collection_run`	`GET /api/collection/ingest/{collection_id}/runs/{run_id}`
	`list_collection_runs`	`POST /api/integrations/tools/list_collection_runs`
Steer	`approve_collection_run`	`POST /api/collection/ingest/{collection_id}/runs/{run_id}/approve`
	`cancel_collection_run`	`POST /api/integrations/tools/cancel_collection_run`
Collection config	`get_collection_config`	`POST /api/integrations/tools/get_collection_config`
	`set_collection_config`	`POST /api/integrations/tools/set_collection_config`
Context	`get_collection_context`	`POST /api/integrations/tools/get_collection_context`
	`set_collection_context`	`POST /api/integrations/tools/set_collection_context`
	`set_collection_offerings`	`POST /api/integrations/tools/set_collection_offerings`
	`list_offerings`	`POST /api/integrations/tools/list_offerings`
	`create_offering`	`POST /api/integrations/tools/create_offering`
	`update_offering`	`POST /api/integrations/tools/update_offering`
Hosting	`list_phantoms`	`POST /api/integrations/tools/list_phantoms`
	`create_phantom`	`POST /api/integrations/tools/create_phantom`
	`get_phantom_config`	`POST /api/integrations/tools/get_phantom_config`
	`set_phantom_config`	`POST /api/integrations/tools/set_phantom_config`
Balance	`get_phantom_balance`	`POST /api/integrations/tools/get_phantom_balance`

CLI: letterstory collection run --topic …

Runs aren't metered individually. Your plan sets how many hosted sites run at once and posts per week; a direct run spends that week's cadence.

Other primitives

Kernels Shredders Enhance Seers Arenas Openers