# Sleeper Hit Studio

> A story-creation and production workspace for developing, writing, performing, packaging, and publishing narrative work. Start from an initial premise, notes, research, or an existing screenplay. An existing screenplay is not required.

## No Sleeper Hit account yet?

Without an account you can:
- Search opted-in creator profiles, project summaries, and creator-approved public assets through the public MCP server (https://sleeperhit.studio/api/mcp) or the public discovery API (https://sleeperhit.studio/api/public/v1), which needs no MCP client.
- Read every published contract: the capability manifest, OpenAPI spec, docs site, llms.txt, and the CLI and MCP tool maps.
- Open public share links (table reads, pitch decks, trailers) a creator has already published.

An account is required to:
- Create story projects, attach source material, and develop a project Series Bible.
- Plan, generate, and revise screenplay installments, table reads, pitch decks, and trailers.
- Spend Studio Credits on generation, rendering, casting, scoring, and finalization.
- Publish durable releases to the first-party RSS feed and connected destinations.

Anyone 18 or older can sign up at https://sleeperhit.studio/signup?utm_source=assistant&utm_medium=mcp&utm_campaign=mcp, 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 for a user. Hand the human the link that matches them, then stop:
- Business and brand storytelling (Companies, agencies, and brand or marketing teams producing narrative work.) — https://sleeperhit.studio/signup?intent=business&utm_source=assistant&utm_medium=mcp&utm_campaign=mcp
- Independent creator (Solo creators and small studios publishing their own shows, podcasts, and short-form video.) — https://sleeperhit.studio/signup?intent=creator&utm_source=assistant&utm_medium=mcp&utm_campaign=mcp
- Screenwriter (Screenwriters developing scripts, pilots, features, and pitch material.) — https://sleeperhit.studio/signup?intent=writer&utm_source=assistant&utm_medium=mcp&utm_campaign=mcp

## What it makes

Sleeper Hit Studio is for writers, producers, and small studios making narrative audio and video. From a premise, a screenplay, or a folder of sources it develops a project Series Bible, plans a season, writes and performs episodes, makes live table reads, and publishes a first-party show feed; the same project is packaged as pitch decks, trailers, and product videos. Every spend is quoted in Studio Credits before it is charged.

Agents do the same work for a signed-in user over the authenticated MCP connector (or the Story API and CLI): develop and read a project, plan an episode, create a table read, poll a job, refine the result, and ask the human at every publish boundary.

## Connect in one step

### If you are an agent connecting a user to Sleeper Hit

You cannot complete the app's browser OAuth from inside a chat or a sandboxed shell: the browser cannot reach your sandbox's callback, so your user approves and no token arrives. Do not run that browser login yourself, and do not retry it. A device sign-in needs no callback and does finish inside a sandbox: `sleeperhit login --no-browser` in the CLI prints a code and a URL for your user to approve in their own browser, then polls and saves the key, so it works when your user can approve while you keep running. With no CLI to run, those are two plain calls you make yourself, neither needing a key: `POST https://sleeperhit.studio/api/auth/device/code` with `{"client_id":"sleeperhit-cli","scope":"story:read credits:read artifact:read story:write source:write source:read"}` answers a `user_code` and a `verification_uri` to hand your user, and polling `POST https://sleeperhit.studio/api/v1/device/credential` with its `device_code` every `interval` seconds returns the key. Name the scopes you will use in `scope`, as that call does: a request that sends only `client_id` is approved as a read-only key (every read, no write), so your first create is refused `insufficient_scope`. That `scope` names the calls that read, create and generate, and spends nothing, so the calls that finish or publish are refused on it: `refine`, `finalize`, sharing a table read, casting a voice or a portrait and the other finish calls need `artifact:publish`, and a show's setup, its episodes and its releases need `publishing:read`, `publishing:write` and `publishing:publish`. Name every scope your journey will reach in the same `scope` string — the approval page lists each one before your user approves, and `GET /api/v1/capabilities` names them all. A sandbox cannot reconnect a browser OAuth connector or open the Developers page, so the way back from that refusal is a NEW device sign-in naming the missing scope, never a retry of the call that was refused: `GET /api/v1/account/credential` reads back what the key you hold carries. Otherwise ask your user to do the one-time sign-in in their app:

- **Codex:** They run `codex mcp login sleeperhit` in their own terminal, outside the agent sandbox, approve in the browser, then start a new Codex session so the tools load.
- **Claude Code:** They run `/mcp`, choose sleeperhit, then Authenticate.
- **ChatGPT:** They choose Connect on the app, then Authorize.

After that the app renews access by itself. The app loads its tool list when a session starts, so if the tools don't appear, ask your user to start a new session.

If your user can't do a browser sign-in, they can create an API key at https://sleeperhit.studio/dashboard/developers (Dashboard → Developers), set it as SLEEPERHIT_API_KEY and add it as a bearer token: `codex mcp add sleeperhit --url https://sleeperhit.studio/mcp --bearer-token-env-var SLEEPERHIT_API_KEY`. Never ask your user to paste a key into the chat.

Claude Code takes the same key as a header: `claude mcp add --transport http sleeperhit https://sleeperhit.studio/mcp --header "Authorization: Bearer $SLEEPERHIT_API_KEY"`. Every client's setup: https://sleeperhit.studio/mcp#api-key

Verify with the `whoami` tool (or `sleeperhit whoami` in a terminal). It answers `source: "oauth"`, or `source: "api_key"` with the key's scopes. A key for the flow below needs `story:read` and `credits:read` — the guidance and the balance every agent reads first — plus `artifact:read` for the job and artifact reads that follow, `story:write` with `source:write` to create and generate, and `source:read` to poll a URL or PDF source until it is ready.

### MCP endpoints

- **Authenticated creation and production:** `https://sleeperhit.studio/mcp` — OAuth-protected Streamable HTTP. This is the preferred remote connector for Codex and other supported MCP clients.
- **Public discovery:** `https://sleeperhit.studio/api/mcp` — unauthenticated and read-only. It exposes only opted-in creator profiles and creator-approved public assets.
- **The same public data over plain HTTP, no MCP client:** `https://sleeperhit.studio/api/public/v1` — unauthenticated, read-only REST. It is the index that names every public endpoint (writer profiles, their projects, and their approved assets), and it answers 200 with no account, so an agent that cannot speak MCP can still search. Send a `User-Agent` that names your agent and how to reach it: the edge refuses Python's default `Python-urllib/3.x` header, and serves every other one.
- Do not use `/api/mcp` or `/api/public/v1` for private projects or generation; they intentionally have no creation tools.

### Codex remote OAuth

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

- `codex mcp add` registers the server. `codex mcp login` starts OAuth and opens or directs the user to browser authorization. The user runs it in their own terminal, outside any agent sandbox.
- Complete authorization in the browser. Authentication success and tool-roster refresh are separate events: Codex loads a server's tools when a session starts, so start a new Codex session if Sleeper Hit tools do not appear.
- Inspect configuration with `codex mcp get sleeperhit --json` or `codex mcp list --json`.
- After connection, call `whoami`, `get_agent_guidance`, and `get_credits` before committing credits.

### Authenticated workflow groups

- **Orientation and account:** Confirm the connected identity and load live backend guidance before choosing a workflow. Start with `whoami` → `get_capabilities` → `get_agent_guidance`.
- **Credits and usage:** Check the available Studio Credit balance before any generation or rendering work. Start with `get_credits`.
- **Your data: download it, or delete the account:** Only when the writer asks: build "Download my data" and hand them the link; or show what deleting removes and the credit balance, schedule the deletion, or cancel it. Start with `get_account_export` → `get_account_deletion`.
- **Connected products (business):** For a business organization: connect the systems the team works in — Notion and Linear can be connected today, and list_integrations names every product this account can connect. Choose what each brings in, feed a project's seasons from them, and review what they find. Read-only connections; nothing joins a season until someone keeps it. Start with `list_integrations` → `get_integration_walkthrough`.
- **Projects and source material:** Create or resume a project and ground it in notes, URLs, PDFs, research, or an existing script. Start with `list_projects` → `create_project`.
- **Product videos from app recordings:** Make videos of a software product: a product Bible, product coverage, recordings (captures) of the app following a tour per feature, then a video made from the captures alone. Start with `get_project` → `get_series_bible` → `list_app_captures`.
- **Strategy: watches, opportunities, pursuits and contacts:** The writer's career strategy outside any project: recurring watches that find opportunities, pursuits with action items, and contacts. Start with `list_opportunity_watches` → `list_opportunities` → `list_pursuits`.
- **Research notes: what an episode knows:** An episode's research notes (the Notes tab's Research page): list them, search their words, read one with its body, and start, edit or delete one. Start with `list_research_notes` → `search_research_notes`.
- **Series Bible and development:** Establish canon, format, characters, world, episode architecture, and foundational coverage. Start with `get_series_bible` → `get_mood_board` → `get_cast_canon`.
- **Planning and screenwriting:** Create a reviewable plan, generate an installment, inspect real pages, and revise the same artifact — and read the writer's notices (a show episode held or failed, a renewal or auto top-up that failed, a refunded payment, a login that stopped signing in) with list_notifications and mark_notifications_read, or GET and POST /api/v1/notifications. Start with `create_plan` → `get_plan`.
- **Pitch deck rendering:** Approve a pitch deck plan into a priced 480p render, review and choose takes chapter by chapter, then finish the deck at 720p (or 1080p) and export it. Start with `get_pitch_deck_chapters` → `quote_approve_pitch_deck_plan` → `approve_pitch_deck_plan`.
- **Trailer rendering:** Approve a trailer plan into a priced 480p render, review and choose takes, then finish the cut at 720p (or 1080p) and export it. Start with `get_trailer_beats` → `quote_approve_trailer_plan` → `approve_trailer_plan`.
- **Table reads and audio:** Cast, perform, score, add effects, and create durable audio from a screenplay-backed table read. Start with `get_cast` → `get_table_read_script`.
- **Video rendering:** Direct theater motion and render a durable video from a reviewed artifact. Start with `get_artifact` → `direct_theater_motion_beat`.
- **Coverage and revision:** Read existing coverage first, request analysis when needed, and revise before final packaging. Start with `get_coverage` → `get_brand_coverage`.
- **Seasons and automation:** Operate controlled multi-installment season workflows. Start with `list_season_runs`.
- **Shows:** Set up and run a show: a podcast that makes its own episodes from what its sources give (a feed, a topic in the news, Hacker News, a site, a repository), on its schedule, within spending caps the user agrees, after a preview the user hears, each episode credited in its show notes. Or read one an outside app makes under its standing approval. The user owns the show, its episodes and its feed. Start with `create_project` → `save_series_bible` → `get_show` → `set_up_show` → `check_show_sources` → `quote_make_show_episode` → `make_show_episode` → `set_show_state`.
- **Publishing and analytics:** Prepare destinations and releases, then publish only after the user approves the exact externally visible action. Start with `list_publishing_series` → `list_publishing_releases`.

## Discovery

- [Agent integration guide](https://docs.sleeperhit.studio/llms-full.txt): the full manual — auth, idempotency, rate limits, error recovery, every live endpoint with its scopes and conventions, the StoryPlan contract, and what is and is not live. Read the endpoint you are about to call.
- [Capability manifest](https://sleeperhit.studio/capabilities.json): authoritative versioned map of every MCP / Story API / CLI capability with its auth requirement and scopes. No account needed to read it.
- [OpenAPI 3.1 spec](https://docs.sleeperhit.studio/api/v1/openapi.json): full machine-readable contract — operation IDs, schemas, security, error model.
- [Live feature availability](https://docs.sleeperhit.studio/api/v1/capabilities): which artifacts, sources, and docs surfaces are live right now. Needs no key.
- [Agent guidance](https://docs.sleeperhit.studio/api/v1/agent-guidance): backend-managed workflow guidance for Story API, CLI, and MCP agents, with the structured development-flow warnings. The MCP server instructions and the workflow router arrive with the connection, so they are not repeated here. Needs an API key. Read this before creating or refining table reads.
- [Examples](https://docs.sleeperhit.studio/api/v1/examples): cURL + Node recipes for the happy path, error recovery, and idempotent POSTs.
- [Docs site](https://docs.sleeperhit.studio/docs): crawlable human docs plus API / CLI / MCP maps.
- [Public discovery API](https://docs.sleeperhit.studio/api/public/v1): the no-account REST index of the public writer, project, asset and show endpoints; read it with no key and no MCP client.
- [Agent docs index](https://docs.sleeperhit.studio/agent-index.json): page, section, operation, UI, CLI, and MCP discovery index for agents.
- [Four-surface contract](https://docs.sleeperhit.studio/docs/surface-contract.json): generated UI / Story API / CLI / MCP contract snapshot.

## Authentication

- Remote MCP clients should prefer OAuth at `/mcp`, run by the client app. An agent asks its user to sign in from their app and never runs the login itself (see "If you are an agent connecting a user to Sleeper Hit"); a user who can't do a browser sign-in sends a Sleeper Hit API key to `/mcp` as the bearer token instead.
- Create production API keys at https://docs.sleeperhit.studio/dashboard/developers. Tokens are shown once.
- Send `Authorization: Bearer sh_<prefix>_<secret>` on every request that reads or writes an account.
- These answer with no key at all (and the same to a bad one), so an agent with none starts here:
- `GET https://docs.sleeperhit.studio/api/v1/capabilities` — The live feature manifest.
- `GET https://docs.sleeperhit.studio/api/v1/examples` — Worked request examples, the auth header format and the error codes.
- `POST https://docs.sleeperhit.studio/api/auth/device/code` — Start a device sign-in: the code your user approves and the device code to poll with.
- `POST https://docs.sleeperhit.studio/api/v1/device/credential` — Exchange an approved device code for an API key.
- `GET https://docs.sleeperhit.studio/api/v1/publishing-feeds/{seriesSlug}.xml` — A show's public RSS feed.
- `GET https://docs.sleeperhit.studio/api/v1/publishing-feeds/{seriesSlug}/episodes/{releaseId}.mp3` — One published episode's audio file.
- `GET https://docs.sleeperhit.studio/api/v1/cli/sleeperhit-cli.tgz` — The published CLI tarball, the address the install command names (a counted install).
- `GET https://docs.sleeperhit.studio/api/public/v1` — The public discovery index of opted-in writers and shows.
- `GET https://docs.sleeperhit.studio/api/public/v1/shows` — Published shows, with their own site and podcast feed.
- `GET https://docs.sleeperhit.studio/api/public/v1/writers` — Search public writer profiles by name, genre, format or specialty.
- `GET https://docs.sleeperhit.studio/api/public/v1/writers/{writerSlug}` — One public writer profile, with their public projects and assets.
- `GET https://docs.sleeperhit.studio/api/public/v1/writers/{writerSlug}/projects` — A public writer's public projects.
- `GET https://docs.sleeperhit.studio/api/public/v1/writers/{writerSlug}/projects/{projectSlug}` — One of a public writer's public projects.
- `GET https://docs.sleeperhit.studio/api/public/v1/writers/{writerSlug}/assets` — Every public asset a writer approved.
- `GET https://docs.sleeperhit.studio/api/public/v1/writers/{writerSlug}/projects/{projectSlug}/assets` — The public assets of one of a writer's public projects.
- Keys are scoped, on one of two access levels the Developers page offers: it opens on **Read-only** (every read the API has) and **Full access** is the one press that widens it. A key's scopes cannot be edited after creation, so widening a key means making a new key.
- The scope ids: `story:read`, `story:write`, `source:read`, `source:write`, `artifact:read`, `artifact:publish`, `publishing:read`, `publishing:write`, `publishing:publish`, `publishing:connect`, `publishing:analytics`, `app:connect`, `capture:read`, `credits:read`, `account:read`, `account:write`.
- Provider keys (e.g. OpenAI) are managed separately by Sleeper Hit and are not exposed to API customers.

## Endpoint reference

Every endpoint, its scope and its conventions are in the [agent integration guide](https://docs.sleeperhit.studio/llms-full.txt#endpoint-reference): read the one you are about to call. [The capability manifest](https://sleeperhit.studio/capabilities.json) is the authoritative list of what exists at all.

Status: production-stable identity, auth, credits, discovery, source ingestion, project Series Bibles, conversational season runs, StoryPlans, story jobs (including signed completion callbacks), live table reads, pitch decks, and post-creation artifact mutations. Remaining artifact adapters ship in follow-on phases. Always read `/api/v1/capabilities` before integrating a flow.