Sleeper Hit Studio — B2B Story API: Agent Documentation

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, with pitch decks, storyboards, trailers, and production videos coming next.

This directory is the canonical reference for agent and developer integrations.

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 LLM 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. autoApprove skips the human-in-the-loop hold.
Story jobs — credit-reserving artifact generation queue against an approved plan.
Table read artifact — the first live artifact adapter. Returns three ready-to-open player URLs, plus refine, recast, coverage, adaptive music, sound effects, and finalize capabilities.
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 api-reference.md#post-artifactsartifactidrefine.
Recast voice — change one character voice in place without changing the artifact revision or share URLs. See api-reference.md#post-artifactsartifactidvoice.
Coverage, music, and sound effects — generate script coverage, add or tune adaptive music, and manage timed SFX cues against the same live table read. See api-reference.md#post-artifactsartifactidsfx.
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 api-reference.md#post-artifactsartifactidfinalize.

What is coming soon

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:write scope exists on keys today; the delivery endpoint is not yet wired.
Additional artifact adapters — pitch deck (video + PDF), 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, CLI, and MCP map
Docs search index	`https://docs.sleeperhit.studio/docs/search-index.json`	Lightweight searchable corpus
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 /api/v1/capabilities`	Live feature availability — read this first
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

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 api-reference.md#authentication-and-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"