---
title: "List a product project's story films."
method: GET
path: "/story-projects/{projectId}/story-films"
tags: ["Story Films"]
---

# List a product project's story films.

`GET /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

The ranked three with each pitch's reason and its full audit — every candidate's concept, register, judge verdict, score and written rank — plus `modelUsed`, `generatedAt`, `updatedAt`, and `note` when none have been pitched yet (right after a pitch an empty list, until the queued job lands). A read: it never pitches, decides or writes. Scope: `story:read`.

## Response `200`

The ranked story films and the audit that explains them.

- ProductStoriesListResponse: A project's story films: the ranked pitches with the audit that explains them, and nothing else.
  - `projectId` string, required
  - `pitches` ProductStoryFilm[], required: The ranked three, best first (empty until a queued pitch lands).
    - `rank` integer, required: Place in the ranked three.
    - `reason` string, required: The judge's sentence for this place — what caught it there.
    - `story` object, required: The story film as stored: its id, projectId, status (`pitched` → `scripted`), concept and register, the intent it is gated by (its product turn, its logline and the human act the feeling rides on), the stake outside the product, the product fictionalization, cast, seed, the beat sheet and the capture requests. 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.
  - `candidates` object[], required: Every candidate the round kept, with its concept, register and pitch, its judge verdict (the vetoes and rule hits), scored, and written rank — the audit that explains why the others are not in the three.
  - `modelUsed` string, nullable, required: Who wrote the round (providers/model); null when none has run.
  - `generatedAt` string, nullable, required: When the initial pitched round was generated; null when none has run.
  - `updatedAt` string, nullable, required: When it changed as a whole; null when none is stored.
  - `note` string, nullable, required: How many are stored (post-judge), or that none have been pitched yet.

## Other responses

- `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.
- `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)