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

```text
https://sleeperhit.studio/mcp
```

Codex setup:

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

```bash
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](../integrations/mcp-clients.md).

---

## 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. `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 the [artifact endpoints](api-reference.md#artifacts).
- **Recast voice** — change one character voice in place without changing the artifact revision or share URLs. See the [artifact endpoints](api-reference.md#artifacts).
- **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](api-reference.md#artifacts).
- **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](api-reference.md#artifacts).

---

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

| Page | What it covers |
|---|---|
| [quickstart.md](quickstart.md) | End-to-end walkthrough: API key to playable table read URL, with curl and Node snippets |
| [concepts.md](concepts.md) | Projects, sources, plans, jobs, artifacts, credits, share tokens, modes, digest |
| [api-reference.md](api-reference.md) | Every endpoint: method, path, scope, request body, response shape, errors |
| [recipes.md](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](https://sleeperhit.studio/terms) and [Privacy Policy](https://sleeperhit.studio/privacy). 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](concepts.md#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:

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