---
title: "Pitch three story films for a product (free)."
method: POST
path: "/story-projects/{projectId}/story-films"
tags: ["Story Films"]
---

# Pitch three story films for a product (free).

`POST /story-projects/{projectId}/story-films`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/story-projects/{projectId}/story-films`
- Auth: HTTP bearer

PITCH three short films from the product's feature map, free and queued. A story film pitch is three short films about people, built from the project's feature map: each one names who is in it, what is at stake outside the product, and the one real recorded moment of the product the story turns on, the three come ranked with the reason for each, and any idea that was impossible for this product is said plainly, with why. A strict body `{ notes?, seconds? }` (at most 2000 characters of the caller's own words — what matters, the audience, what to lead with — and how long the films run, 30 to 60 seconds, which the film the round writes by itself is written to; an unknown key is 400 `validation_failed` naming it). A story project is refused (a story film is built from shipped product features), and a product project not ready for one is 409 `product_video_not_ready` in the readiness step's own sentence, with `details.next` the verb that does it (a story film starts from the project's existing recordings, and with none its moments record in the app, so it waits on the app being connected and signed in to and on one shipped feature to build from) — nothing is queued. Answers 202 `{ projectId, queued, note }` at once; GET this path until the ranked three land (minutes: the queued worker runs the pitch pass, then the judge). NOT metered and NOT confirmed. Requires `Idempotency-Key`. Scope: `story:write`.

## Headers

- `Idempotency-Key` string, required

## Request body

- PitchProductStoriesRequest: The pitch request: the caller's own notes, and how long the films run. A story film pitch is three short films about people, built from the project's feature map: each one names who is in it, what is at stake outside the product, and the one real recorded moment of the product the story turns on, the three come ranked with the reason for each, and any idea that was impossible for this product is said plainly, with why. A strict body — an unknown key is 400 `validation_failed` naming it.
  - `notes` string: Free notes for the pitch — what matters, the audience, what to lead with (at most 2000 characters; trimmed before it is stored).
  - `seconds` integer: How long the films run, whole seconds: the pitches are shaped for it and the recommended film the round writes by itself is written to it. Absent: the usual 30-45.

## Response `200`

The pitch was replayed from its idempotency record (the same queued answer).

- ProductStoryPitchQueued: A pitch started: the round is queued against this project and nothing was charged. The ranked three arrive as GET the same path reads them.
  - `projectId` string, required
  - `queued` true, required: Always true: the job was sent.
  - `note` string, required: What happens next, in one paragraph to read out: the candidates, then the judge, then the ranked three.

## Other responses

- `202`: The pitch queued: read the ranked three off GET when they land.
- `400`: Request payload failed validation. The error message names the offending field.
- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `404`: The named project or source does not exist or is owned by another account.
- `409`: `product_video_not_ready`: the project is not ready for a story film yet (no shipped feature with a ready recording to start from, and the app not connected or signed in to; or no shipped feature). `message` is the readiness step to do first and `details.next` its verb. Nothing was queued.
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/4534f5d25540?raw)