Projects

List projects

GET https://api.scenema.ai/v1/projects lists every project in the workspace, newest first, with page and perPage (up to 100). It includes projects made in the Scenema app, by the Director and through the API.

{
  "items": [
    {
      "id": "proj_4559d9dd5dc8d53",
      "name": "Why the sky is blue",
      "kind": "video",
      "aspectRatio": "9:16",
      "thumbnailUrl": "https://cdn.scenema.ai/thumbs/proj_4559d9dd5dc8d53.webp",
      "durationMs": 58000,
      "working": false,
      "createdAt": "2026-11-06T18:12:00.000Z",
      "updatedAt": "2026-11-06T18:40:00.000Z",
      "studioUrl": "https://scenema.ai/app/studio/proj_4559d9dd5dc8d53"
    }
  ],
  "total": 1,
  "page": 1,
  "perPage": 20
}

Field	Meaning
`kind`	`video`, or `audio` for a narration only project.
`aspectRatio`	The frame shape, such as `16:9` or `9:16`. Null for audio.
`thumbnailUrl`	A still of the project, when it has one. The link expires; list again for a fresh one.
`durationMs`	The length of its recorded narration. Chapters with no audio yet count as 0.
`working`	True while something is being made for it: narration, images, clips or an export.
`studioUrl`	The project in the Scenema studio on the web.

Get a project

GET https://api.scenema.ai/v1/projects/{id} returns the project’s chapters and shots. An app reads it to show a shot strip: each shot’s image and clip, and where they stand.

{
  "id": "proj_4559d9dd5dc8d53",
  "name": "Why the sky is blue",
  "kind": "video",
  "aspectRatio": "9:16",
  "status": "processing",
  "chapters": [
    {
      "id": "scene_5f0a3b",
      "number": 1,
      "name": "Light through the air",
      "stage": "ready",
      "narration": { "url": "https://cdn.scenema.ai/a/1.mp3", "durationMs": 58000, "approved": true },
      "durationMs": 58000,
      "shots": [
        {
          "id": "shot_8a1c2e",
          "number": 1,
          "name": "Sunlight holds every colour",
          "startMs": 0,
          "endMs": 7400,
          "image": { "status": "ready", "url": "https://cdn.scenema.ai/k/1.webp" },
          "clip": { "status": "working", "url": null, "durationMs": null, "stale": false }
        }
      ]
    }
  ],
  "pollAfterMs": 5000
}

Field	Meaning
`status`	`processing` while something is being made for the project, `idle` otherwise.
`chapters[].stage`	What the chapter waits on: `needs_narration`, `needs_approval` (the user approves the narration), `needs_style`, or `ready`.
`chapters[].narration`	The chapter’s narration once there is one, and whether the user approved it.
`shots[].startMs`, `shots[].endMs`	Where the shot sits on its chapter’s timeline.
`shots[].image.status`	`waiting` (not designed yet), `queued`, `working`, `waiting_for_credits`, `ready` or `failed`.
`shots[].clip.status`	`none` (not animated), `queued`, `working`, `waiting_for_credits`, `ready` or `failed`.
`shots[].clip.stale`	True when the shot’s image changed after its clip was made. The clip still plays.

Image and clip links expire. Read the project again for fresh ones.

Follow a project while it works

While status is processing, poll it the same way as a video (see Polling):

Send wait (up to 30 seconds) to hold the request until the project changes, or until the wait ends.
Send If-None-Match with the last ETag to get 304 Not Modified when nothing changed.
pollAfterMs says how long to wait before reading again: 5 seconds while processing.

An unknown project, or one in another workspace, gets 404 with code: NOT_FOUND.