# 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](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](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](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](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](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, 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](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:

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