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 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:

Copyhttps://sleeperhit.studio/mcp

Codex setup:

Copycodex mcp add sleeperhit --url https://sleeperhit.studio/mcp
codex mcp login sleeperhit

The login command opens or directs the user to browser authorization. Finish authorization there, return to Codex, and reopen or refresh the active task if the authenticated tool catalog is not visible yet. Authentication success and catalog refresh are separate events.

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 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 may 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 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, 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 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.

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:write scope 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

Machine-readable discovery surfaces

These are served by the API itself and should be fetched fresh, not copied:

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.

Account access is waitlist-gated: there is no self-serve signup, and an agent cannot create an account on a user's behalf. Hand the human the link that matches them, then stop.

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 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:

Copycurl -s https://sleeperhit.studio/api/v1/credits \
  -H "Authorization: Bearer $SLEEPERHIT_API_KEY"