Capabilities
Every capability an API key can carry, what it lets a key do, and the two that spend money.
Generated from the app (capabilities), so always current.
An API key carries a set of capabilities. A tool call with a key that lacks the capability it needs returns 403. Grant the smallest set that does the job; to change a key's scopes, revoke it and create a new one.
The API reference shows which capability each tool needs. The table is generated from the app's own capability list, so it is always current.
| Capability | Lets a key | Details |
|---|---|---|
article:read | Read articles | List and fetch articles, collections, and published posts. |
article:write | Write articles | Create, update, and permanently delete draft articles, and run Auto-Pen (research, writing kernel, Enhance) over one. |
article:publish | Publish articles | Publish or unpublish an article's current content as its live version. |
connector:read | Read connector targets and publish status | See where a post could be published and whether a publish worked. Reading only — publishing itself needs connector:publish. |
connector:publish | Publish to connectors (Webflow / Framer / Google Docs / Contentful) | Publish an article out to an external CMS connector (Webflow, Framer, Google Docs, or Contentful). |
flow_run:create | Start flow runs | Start a flow against an article. |
flow_run:read | Read flow run status | Poll the status and stage results of a flow run. |
flow_run:resolve | Resolve flow run reviews | Apply a stage's suggestions past its awaiting_review checkpoint (accepting the AI's picks or an explicit suggestion_id list) and advance the run to the next stage. |
webhook:read | Read the configured webhook | See the webhook destination this organization has configured. Reading only — changing it needs webhook:manage. |
webhook:manage | Manage webhooks | Read and set the webhook destination for article.published and article.finished events. |
provisioning:read | Read positioning & competitors | Read editorial positioning, competitors, and onboarding progress. |
provisioning:write | Set positioning & add competitors | Set positioning, add competitors, advance onboarding, and import a sitemap. |
collection:read | Read collections & runs | List collections, read a collection's one-file configuration and its topic map, and poll collection runs (get_collection_run / list_collection_runs). |
collection:write | Run collections (create / configure / run / approve) | Create, configure and delete collections; open runs on them (run_collection — one published post, metered on the collection's weekly cadence); approve or cancel runs; queue topics. Also moves articles between collections. Includes defining custom_fields: each one's generation_prompt is free text sent straight to the model and written into every future post, so this capability can shape content generation, not just toggle settings. |
phantom:read | Read phantoms (Phantomstory) | List the org's hosted phantom sites, poll provisioning, read a phantom's configuration and diagnostics, check domain availability, and read Search Console and GEO performance across them. |
phantom:write | Manage phantoms (create / configure / rebuild / delete) | Create a hosted phantom site (metered on the org's phantom credits — sites live at once), configure it, rebuild it, pause it, tear it down, and attach a domain you already own. |
phantom:domain | Buy custom domains for phantoms | Buy a new domain for a phantom: a separate, explicitly-granted scope since it spends real money (the price must be under $30, and an organization can hold at most 2 custom domains). |
insight:read | Read performance insights | Read Search Console performance for the org's published posts: per-site and per-post clicks, impressions, CTR, and position, with previous-period comparison and top posts. |
phantom_access:read | Read phantom page access | See who is reading the caller's phantom sites: recent AI-agent/crawler requests and confirmed visits (what's hitting the fleet right now), per-assistant totals, and the page-access panel's rollups over a period. |
kernel:read | Read writing kernels, endpoints & runs | List the kernel catalog and the org's kernel endpoints, read an endpoint's configuration, poll a run (standalone or article-bound), and read the kernel-run balance. |
kernel:write | Run writing kernels | Write with a kernel through one of the org's kernel endpoints (run_kernel — prose comes back to you, metered in kernel runs), or into an article (run_kernel with article_id — locks the article until the output is written back). Also creates, configures and deletes kernel endpoints. |
geo:read | Read GEO tracking (AI-assistant visibility) | Read GEO opportunities, tracked topics, native-tracker settings, and run batches. |
geo:write | Manage GEO tracking | Add, rename, pause/resume, or delete tracked GEO topics, update native-tracker settings, trigger a native-tracker run, and sync a connected GEO provider's opportunities. |
ranking_target:read | Read ranking targets | List the org's ranking targets and their cluster/collection bindings. |
ranking_target:write | Manage ranking targets | Add a ranking target, or edit its phrase, framing, or status. |
social_profile:read | Read social posting profiles | List the org's social posting personas. |
social_profile:write | Manage social posting profiles | Create, update, or delete a social posting persona. |
curate:read | Read Curate content strategy | Read topic clusters, suggested headlines, and the client content inventory. |
curate:write | Manage Curate content strategy | Create, rename, prioritise, merge and remove clusters and assign articles to them, generate or queue suggested headlines, infer competitor/client-content keywords, and remove or permanently exclude discovered SEO keywords. |
insight:write | Backfill performance history | Trigger a one-time full-history Search Console import for the org. |
account:read | Read account & org settings | List the org's API keys (metadata only, never secrets), read organization profile, list members/seats, list pending invites, and read AI-usage/credit-gate status (credits used, threshold, and the per-action breakdown). |
account:write | Manage account access (revoke keys / invite members) | Revoke an API key (never the calling key itself) or create a pending member invite. No key-minting and no billing changes: those are separate, more sensitive scopes. |
review:read | Read article reviewers | List an article's org-member and guest reviewers, their verdicts, and the aggregate approval summary, the same gate publish_article checks. |
review:write | Manage article reviewers | Add or remove an org-member reviewer on an article, and revoke a guest reviewer's access (soft-revoke; their comments are preserved). Never invites a new guest reviewer: that sends a real email and can hand back a live PIN, so it's a separate, not-yet-built scope. |
story:read | Read The Story (editorial momentum feed) | Read the deterministic 'Needs you' action deck (topics ready + pipeline queues), recent publishing wins, and still-actionable publish failures (failed CMS pushes and enhancement runs). |
strategy:read | Read publishing cadence | Read the org-wide publishing-cadence roll-up (one entry per collection) and a single collection's pace against its target over its rolling 7- or 30-day window. Also lists a collection's pending strategy suggestions with their auto-apply countdown. |
strategy:write | Decide strategy suggestions | Approve, dismiss, or snooze a collection's pending strategy suggestions (verdicts and proposals) — the same levers the web queue pulls. |
measure:read | Read measurement probes & AI visibility | List a collection's AI-answer probes with their rotation lifecycle (retiring, earning, protected), and read the AI Visibility Bank — the named / cited / breakthrough evidence behind Measure's AI-answer numbers. |
measure:write | Control measurement probes | Pause/resume, keep (protect from rotation), edit, or add AI-answer probes — the same controls as the Measure → Probes tab. |
brand:read | Read brand assets & context files | List the org's uploaded context files (name, size, mime, upload date), never the extracted text. |
brand:write | Manage brand assets (logo / font / context files) | Mint a signed upload URL for a new org logo or custom font (the caller PUTs the bytes directly to storage), and remove an existing logo, font, or context file. |
canvas:read | Read Canvas types & visuals | List and fetch the org's Canvas types (style templates) and canvas_visuals instances, and list available image models. |
canvas:write | Manage Canvas types & compositions | Create or update a Canvas type, arrange a semi-structured composition, and re-classify a sticker. Excludes deletes and the image-spending generate endpoints (separate, more sensitive scopes). |
visual:read | Read visuals | List and fetch table/venn visuals, org- or article-scoped. |
visual:write | Manage visuals | Create or update a table/venn visual, and generate a table or Venn diagram structure from article content (usage-gated). |
arena:read | Read arena runs | List arenas and poll their runs: phase-by-phase progress, the sources the cluster gathered and read, the competing directions it proposed, the outline, the stat ledger, the paper trail, and the verification read-back. |
arena:write | Run arenas | Run an arena (an adversarial cluster of research agents) on a topic — standalone, or hosted into a post — answer its direction gate, cancel a run in flight, and create or configure arenas. Direct runs spend the org's arena-run balance. |
seer:read | Read Seers (event-driven signals) | List and fetch seers with their activity, detected events (with dedup aliases and relevance verdicts), the seer-sourced headlines feed, held drafts, the provider catalog, and GitHub/Notion connection status. |
seer:write | Manage & run Seers | Create, update, or delete a seer, trigger an on-demand poll+produce run (usage-gated: production spends model budget), dismiss detected events, release or discard held drafts, and store a GitHub token or a Notion internal-integration token. |
template:read | Read content templates | List and fetch the org's content templates (compose structures shared by seers and collections). |
template:write | Manage content templates | Create, update, or delete a content template. |
shredder:read | Read shredder endpoints & telemetry | List the org's shredder endpoints and their shred-run telemetry. |
shredder:write | Manage shredder endpoints & run shreds | Create and delete shredder endpoints, and run prose through one. Shredding rewrites each sentence across multiple LLM providers to diversify, leaving structure (headings, lists, tables) untouched, and logs the call to telemetry. |
lede:read | Read lede endpoints & telemetry | List the org's lede endpoints and their lede-run telemetry, read an endpoint's configuration, and read the lede balance. |
lede:write | Manage lede endpoints & run ledes | Create, configure and delete lede endpoints, and run a prospect through one. A lede run enriches the person's company and returns scored opening lines for cold email, and logs the call to telemetry. |
lede:library:read | Read the org's lede library | List the org's opening-line library: the pre-built lines and any the org has authored, each with its wording variants, trigger, strictness dial and enabled state. |
lede:library:write | Edit the org's lede library | Create, edit, enable, disable and delete opening lines in the org's lede library, and run an AI 'rewrite in my voice' pass over them. Edits change which lines the org's lede runs can pick and how they read; triggers stay validated so a line can never assert something the engine did not observe. |
landing:read | Read landing pages | List and read the org's landing pages (a URL plus context that collections can auto-mention). |
landing:write | Manage landing pages | Create, update, or delete a landing page (a URL plus context). Collections with auto-mention enabled weave relevant landing pages into articles as they're written. |
vendor:read | Read Letterprove vendor data | Read this org's Letterprove vendor account: link status, customers, proof/attestation summaries, and install status. |
vendor:write | Manage Letterprove vendor account | Create or update this org's Letterprove vendor account: link a vendor, manage customers and consent, rotate the collector key, verify the domain. |
feedback:write | Submit product feedback | Submit feedback about Letterstory itself -- a bug, something missing, something unclear, a feature request, or praise. |
mailer:read | Read mailers & mail domain status | Read the mail status of a domain you own (provisioning stage, DNS/verification state) and the mailers on it, including each mailer's warmup progress and daily send limit. |
mailer:provision | Launch new mailers (buy domain, set up email, warm up) | The one-shot Mailers launch: price a domain, buy or adopt the shared domain, provision a mailserver on it, create the mailers, and enroll them in warmup. This can SPEND money (registering a net-new domain). Also sets where that money is spent: the org's own Vercel key and team, and the WHOIS registrant for purchases on it. A separate, explicitly-granted scope. |
mailer:manage | Manage mailers (forwarding, warmup, suppressions) | Manage existing mailers: set reply forwarding, start or pause warmup, and maintain the org's email suppression (do-not-send) list. |
sequence:read | Read sequences & the review queue | List and read the org's email sequences (flow, attached mailers, enrollment and per-step counts, who replied) and the Dispatch review queue of emails waiting for a decision. Reading only: nothing is sent. Pocket Dispatch links (no-login URLs that can approve sends) are admin-only to list, mint or revoke — see sequence:write. |
sequence:write | Run sequences (create, enroll, approve sends) | Create and edit sequences, activate, pause or archive them, enroll recipients or a prospect list, stop an enrollment, edit, approve, skip or delete queued emails in the review queue, and list, mint or revoke Pocket Dispatch links (no-login URLs that can approve sends; listing never returns their tokens). This MAILS REAL PEOPLE from the org's mailers: enrolling into an active sequence and approving a review item both send email. Sequence Frontrunner steps also start the org's Frontrunner (LinkedIn) agents for recipients, and a key minted by an org admin can connect or disconnect the org's Frontrunner workspace (stores its API key). |
prospect:read | Read prospects & prospect lists | List and read the org's prospect lists and the prospects in them (contact details, company, enrichment, worked-state). Prospect records are personal data about third parties. |
prospect:write | Source & edit prospects | Create prospect lists, import a CSV, edit a prospect, and SPEND on sourcing: fill a list from a plain-language description (paid data providers) and enrich prospects with funding and competitors (model calls). Does not send email; enrolling a list into a sequence needs sequence:write. |
composition:read | Read primitive compositions | List and fetch the org's primitive compositions (named bundles of a writing kernel, shredder, content template and optional seer) and resolve one into the sections create_phantom takes. |
composition:write | Manage primitive compositions | Create, update, or delete a primitive composition. |
evals:read | Read content evals | Read the live content scoreboard for your posts (per-stage measures, failing posts with evidence), list your org's regression cases, and poll a suite run. |
evals:write | Capture eval cases & run the suite | Freeze one of your posts' pipeline records as a regression case (a measure that must pass once the bug is fixed) and run the record-only suite over your org's cases. Never publishes or edits a post. |
audit:read | Read site audits | List the org's site audits and read a finished audit's report: crawled pages, SEO issues with how-to-fix guidance, and Lighthouse results. |
audit:write | Run & delete site audits | Start a site audit (crawls the target site, optionally rendering JavaScript and running Lighthouse) and delete audits. Crawling reaches out to third-party sites identified as Letterstory's crawler. |
org_config:read | Export org config | Read the org's whole configuration as one JSON bundle (export_org_config): settings, primitives and data, keyed by name. Config only — no runs, history or credentials. What each setting means and how it is edited (describe_org_config_fields). Also shows which GitHub repo the org's config is synced from (get_org_config_source). |
org_config:write | Apply org config | Apply an org config bundle (apply_org_config): create and update the org's settings, context, collections, phantoms, primitives and their files, outreach and measure by name — changes that send, spend or destroy only when allowed and confirmed — and delete records missing from the bundle only when pruning. Also connect, sync and disconnect the GitHub repo the org's config is kept in (connect/sync/disconnect_org_config_source). |
visitors:read | Read Visitors | Read this org's Visitors sites: the script and its install checks, which AI agents and crawlers read each site, and the visitors identified on it. |
visitors:write | Manage Visitors | Add a Visitors site, switch its modules, check that its script is on the site, and turn visitor identification on or off. |
repo:read | Read repo changes | List the repos the Letterstory GitHub App can reach, and list and poll repo-change runs: phase, spend, the files changed and the PR they opened. |
repo:write | Request repo changes | Start a repo-change run (Claude Code edits a checkout of one of your repos in a sandbox from your instructions and opens a pull request through the Letterstory GitHub App) and cancel one. Spends model credit; never merges. |
site:read | Read the site map | List mapped sites, walk the site tree one folder at a time with rollups, read a page's facts and bindings, and list observations, families and proposals. |
site:write | Map and act on the site | Map a host from its sitemap, run observation passes (Jev), dismiss observations, track or dismiss page families, and create, accept or dismiss proposals. |