The Story API is the authenticated surface that lets agents and enterprise systems build stories programmatically. Submit sources, get back a source-grounded narrative plan, approve it, run a job, and receive shareable deliverables — starting with live audio table reads and pitch decks, with storyboards, trailers, and production videos coming next.
This directory is the canonical reference for agent and developer integrations.
Preferred agent connection: remote MCP
For Codex and other remote MCP clients, prefer the OAuth-protected creation connector:
https://sleeperhit.studio/mcp
Codex setup:
codex mcp add sleeperhit --url https://sleeperhit.studio/mcp codex mcp login sleeperhit
The user runs the login command in their own terminal; it opens or directs them to browser authorization. Finish authorization there, then start a new Codex session: Codex loads a server's tools when a session starts, so the session that signed in may not see the authenticated tool catalog. Authentication success and catalog refresh are separate events.
If you are an agent connecting a user to Sleeper Hit, you cannot complete the sign-in from inside a chat or a sandboxed shell: the browser cannot reach your sandbox's callback. Ask your user to sign in from their app; don't run the login yourself, and don't retry it. In Codex they run codex mcp login sleeperhit in their own terminal, outside the agent sandbox, then start a new Codex session; in Claude Code, /mcp → sleeperhit → Authenticate; in ChatGPT, Connect, then Authorize. If they can't do a browser sign-in, they create an API key at https://sleeperhit.studio/dashboard/api (Dashboard → Developers) and add it as a bearer token; never ask them to paste it into the chat. Then verify with whoami:
codex mcp add sleeperhit --url https://sleeperhit.studio/mcp --bearer-token-env-var SLEEPERHIT_API_KEY
The separate https://sleeperhit.studio/api/mcp endpoint is intentionally unauthenticated and read-only. It exposes only opted-in creator profiles and creator-approved public assets; it cannot access private projects or create story artifacts.
After authentication, begin with whoami, get_agent_guidance, and get_credits. The guidance response includes workflow-oriented tool groups, prerequisites, cost posture, polling expectations, and recommended next calls. See the MCP client setup guide.
Mental model
Every integration follows the same loop:
Sources --> Plan --> Approve --> Job --> Artifact --> (Refine ⟳) --> Finalize
(URL/PDF/text) (async gen) (human or auto) (async gen) (manifest URLs) (in-place revision) (durable MP3/MP4)
Every stage is individually pollable, idempotent on re-submission with the same Idempotency-Key, and inspectable after failure. The artifact id and share URLs are stable across refines — embed once, revise as many times as needed.
Key principle: Always fetch GET /api/v1/capabilities at the start of any new run. The manifest lists which artifact types are live (available) versus planned, which source types are accepted, and where the other doc surfaces live. Cache for at most one minute.
What is live today
- Identity, auth, credits, discovery — fully production-stable.
- Source ingestion — inline text and markdown (synchronous); URL and PDF (async, polled via pg-boss workers).
- Source digest — structured digest of each source (summary, thesis, claims, evidence, gaps, rights notes).
- StoryPlan generation — async plan from sources, with structured Zod-validated output and a deterministic Studio Credit quote.
autoApprovemay skip the hold for eligible non-table artifacts; table-read plans always require exact human review and approval. - Story jobs — credit-reserving artifact generation queue against an approved plan.
- Table read artifact — live shareable theater and audio players. Returns three ready-to-open player URLs, plus refine, recast, coverage, adaptive soundtrack, sound effects, and finalize capabilities.
- Pitch deck artifact — live video + PDF packaging generated from an approved plan and a completed table read so it can reuse canonical script text, avatars, and voices.
- Refine — POST a free-form instruction to revise the screenplay/cast or re-ground the plan against sources, producing a new revision of the same artifact without changing its id or share URLs. See the artifact endpoints.
- Recast voice — change one character voice in place without changing the artifact revision or share URLs. See the artifact endpoints.
- Coverage, soundtrack, and sound effects — generate script coverage, add or tune the adaptive soundtrack, and manage timed SFX cues against the same live table read. See the artifact endpoints.
- Finalize — Durably render an MP3 from a completed Pipecat/Daily recording (6 credits) or an MP4 (Remotion export, 12 credits) tied to the existing share. See the artifact endpoints.
Planned follow-ons
- Live scrubber on share players — a timeline scrubber on the theater and audio-only players. Currently players start live reads from the beginning.
- Webhooks — signed delivery of job and artifact lifecycle events. The
webhook:writescope exists on keys today; the delivery endpoint is not yet wired. - Additional artifact adapters — storyboard image packs, trailers, and production videos.
Pages in this directory
| Page | What it covers |
|---|---|
| quickstart.md | End-to-end walkthrough: API key to playable table read URL, with curl and Node snippets |
| concepts.md | Projects, sources, plans, jobs, artifacts, credits, share tokens, modes, digest |
| api-reference.md | Every endpoint: method, path, scope, request body, response shape, errors |
| recipes.md | Task-oriented patterns: RSS to podcast, PDF to documentary read, embed the fullscreen theater, refine a read, add music/SFX, trigger the MP4 render |
| CLI docs | https://docs.sleeperhit.studio/cli and /docs/cli-commands.json |
| MCP docs | https://docs.sleeperhit.studio/mcp and /docs/mcp-tools.json |
Machine-readable discovery surfaces
These are served by the API itself and should be fetched fresh, not copied:
| Surface | URL | Purpose |
|---|---|---|
| Human docs site | https://docs.sleeperhit.studio/ | Crawlable docs for agents and developers |
| Agent docs index | https://docs.sleeperhit.studio/agent-index.json | Page, section, operation, UI, CLI, and MCP map |
| Docs search index | https://docs.sleeperhit.studio/docs/search-index.json | Lightweight searchable corpus |
| Four-surface contract | https://docs.sleeperhit.studio/docs/surface-contract.json | Generated UI / Story API / CLI / MCP contract snapshot |
| CLI command map | https://docs.sleeperhit.studio/docs/cli-commands.json | Structured CLI command list |
| MCP tool map | https://docs.sleeperhit.studio/docs/mcp-tools.json | Structured MCP tool/resource list |
| Capability manifest | GET https://sleeperhit.studio/capabilities.json | Authoritative versioned map of every MCP / Story API / CLI capability, with the auth requirement and scopes per capability. Unauthenticated — read this first |
| Live feature manifest | GET /api/v1/capabilities | Live available vs planned feature availability (needs story:read) |
| OpenAPI 3.1 spec | GET /api/v1/openapi.json | Full machine-readable contract, stable operation IDs |
| Example recipes | GET /api/v1/examples | curl + Node snippets for every live flow |
| Short agent map | /llms.txt | One-page map for agents that read llms.txt |
| Long agent guide | /llms-full.txt | Full prose integration guide for agents |
No Sleeper Hit account yet?
Everything above needs an account. Without one an agent can still read https://sleeperhit.studio/capabilities.json, every docs surface, the public discovery API at /api/public/v1, and the read-only public MCP endpoint at /api/mcp — but it cannot create projects, generate anything, spend credits, or publish.
Anyone 18 or older can sign up at https://sleeperhit.studio/signup, where they confirm their age and accept the Terms of Service and Privacy Policy. An agent cannot create an account or accept the Terms on a user's behalf. Hand the human the link that matches them, then stop.
| Intent | Who it is for | Link |
|---|---|---|
| Business and brand storytelling | Companies, agencies, and brand or marketing teams producing narrative work | https://sleeperhit.studio/signup?intent=business |
| Independent creator | Solo creators and small studios publishing their own shows, podcasts, and short-form video | https://sleeperhit.studio/signup?intent=creator |
| Screenwriter | Screenwriters developing scripts, pilots, features, and pitch material | https://sleeperhit.studio/signup?intent=writer |
The same routing is machine-readable in capabilities.json (access), in GET /api/mcp, in the public MCP server's initialize instructions, and from its get_access_info tool.
Authentication quick reference
Keys live at https://sleeperhit.studio/dashboard/api. Every request must carry:
Authorization: Bearer sh_<18-hex-prefix>_<64-hex-secret>
Tokens are shown once at creation and never displayed again. Store in your secret manager.
Default scopes on a new key: story:read, credits:read. To drive the full create-plan-job-artifact loop you need story:write, source:write, and artifact:read added by the account owner. To refine, recast, finalize, render MP4s, music, or sound-effect cues, you also need artifact:publish.
For the full scope table see Scopes.
Pricing note
Studio Credits are the single shared meter. Every plan carries a deterministic quote (line items + total) before any credits are spent. Credits are reserved when a job is created (POST /story-jobs) and settled when artifacts become shareable. If the reservation fails you get 402 insufficient_credits with details.required and details.available so you can surface the shortfall before retrying.
Check balance at any time:
curl -s https://sleeperhit.studio/api/v1/credits \ -H "Authorization: Bearer $SLEEPERHIT_API_KEY"