Seers

A source to watch in, what's new and relevant out.

A seer watches a source and reports what's new and relevant, deduplicated and ready to become headlines or drafts.

Unit: Seer
A run produces: new events, each with a relevance verdict
In the app: /seers
API reference: All seers tools

Try it

run_seer over REST: POST /api/integrations/tools/run_seer. Needs an API key with seer:write.

curl -X POST https://app.letterstory.com/api/integrations/tools/run_seer \
  -H "x-integrations-key: ls_..." \
  -H "content-type: application/json" \
  -d '{
  "seer_id": "..."
}'

1. Constraints: what you configure

The endpoint's config file

nameprovidercollection_idmodeenabledpoll_interval_minutesconfig

Per call

dry_runproduceasync

The seer is its own config file: there is no separate endpoint. config carries the source (query, focus) and relevance (priority_topics, stances, avoid_topics).

2. Mechanism: what always happens

1Scan the source since the seer's cursor: GitHub, Notion, a spec URL, or the live web for news and regulation changes.
2Deduplicate on title fingerprints, story keys and a semantic near-miss check, so the same story never comes back twice.
3Judge relevance: a lexical scorer always runs, and a model grounded in your positioning decides auto, suggest-only or dismiss.
4Record the events and move the cursor forward. A provider failure is recorded as a failure, never as zero events.

3. Intelligence: who picks values

You, directly

An API key or a person pressing Run now controls everything, per seer and per call.

Letterstory, for you

Letterstory's scheduled heartbeat decides only when to poll. It never changes what the seer is watching for.

4. Verification: did it hold

Check	Reads back	Rule
`sourced`	`mechanism`	Every event has a URL.
`judged`	`config.relevance`	Every event has a relevance verdict.
`deduped`	`mechanism`	No repeats within the run.
`cursor_advanced`	`mechanism`	The watermark moved forward.
`produced`	`mode`	Each event has the artifact its verdict and mode call for.

Report-only; a failed poll reads back as skipped on all five.

Surfaces

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

Job	MCP tool	REST
Run	`run_seer`	`POST /api/integrations/tools/run_seer`
Poll a run	`get_seer_run`	`POST /api/integrations/tools/get_seer_run`
	`list_seer_runs`	`POST /api/integrations/tools/list_seer_runs`
Seers	`list_seers`	`POST /api/integrations/tools/list_seers`
	`get_seer`	`POST /api/integrations/tools/get_seer`
	`create_seer`	`POST /api/integrations/tools/create_seer`
	`update_seer`	`POST /api/integrations/tools/update_seer`
	`delete_seer`	`POST /api/integrations/tools/delete_seer`
Events	`list_seer_events`	`POST /api/integrations/tools/list_seer_events`
Sources	`list_seer_providers`	`POST /api/integrations/tools/list_seer_providers`
Balance	`get_seer_run_balance`	`POST /api/integrations/tools/get_seer_run_balance`

CLI: letterstory seers run <id>

Direct runs draw seer run credits; only completed runs count, failed ones are free. Scheduled polls are never billed.

Other primitives

Kernels Shredders Enhance Arenas Collections Openers