Productions

Create a production

Push a brief. Raylight writes a free pitch (script plus shot list) in the background; poll the production or receive production.pitch_ready on a webhook. externalId makes the call idempotent per key owner and workspace: repeating it with a key from the same owner, in the same workspace, answers 200 with the production the first call made and Idempotent-Replayed: true, and nothing new is created. origin is display only (the Productions pages and emails); Raylight never calls the provider.

POST/v1/productions

API key with the productions scope.

Request body

application/json

Field	Type	Description
`workspaceId`	uuid
`brief`required	object
`brief.intent`required	string
`brief.context`	string \| null	Default `null`
`brief.media`	object[]
`brief.media[].id`required	string
`brief.media[].kind`required	enum	One of: `image`, `video`
`brief.media[].url`required	url
`brief.media[].name`required	string
`brief.media[].description`	string \| null	Default `null`
`brief.code`	object[]
`brief.code[].path`required	string
`brief.code[].source`required	string
`brief.code[].status`	enum \| null	One of: `added`, `modified`, `removed`, `renamed`Default `null`
`brief.code[].additions`	integer	Default `0`
`brief.code[].deletions`	integer	Default `0`
`brief.code[].patch`	string \| null	Default `null`
`brief.code[].digest`	string \| null	Default `null`
`brief.code[].score`	number	Default `0`
`brief.code[].sourceOmitted`	boolean
`brief.format`	object
`brief.format.template`	enum	One of: `changelog`, `launch`, `feature`, `digest`, `custom`Default `changelog`
`brief.format.durationMs`	integer	Default `10000`
`brief.format.aspect`	enum	One of: `16:9`, `4:3`, `3:2`, `21:9`, `1:1`, `9:16`, `3:4`, `2:3`, `4:5`Default `16:9`
`brief.format.sound`	object
`brief.format.sound.voiceover`	boolean	Default `true`
`brief.format.sound.music`	boolean	Default `true`
`brief.format.sound.sfx`	boolean	Default `true`
`brief.brand`	object
`brief.brand.name`	string \| null	Default `null`
`brief.brand.logoUrl`	url \| null	Default `null`
`brief.brand.primaryColor`	string \| null	Default `null`
`brief.brand.backgroundColor`	string \| null	Default `null`
`brief.brand.fontFamily`	string \| null	Default `null`
`brief.brand.tone`	string \| null	Default `null`
`greenlightMode`	enum	One of: `manual`, `auto`Default `manual`
`externalId`	string
`origin`	object
`origin.provider`required	string
`origin.label`required	string
`origin.url`	url \| null	Default `null`
`origin.ref`	string \| null	Default `null`
`origin.requestedBy`	string \| null	Default `null`

Responses

200A repeat of an earlier create with the same externalId: the existing production.

201The new production, queued for a pitch.

400Invalid request.

401Missing, invalid or revoked key.

402The workspace owner's credits do not cover a video of the length asked for (code credits). A pitch is free, but it is only written when the video it asks for could be paid for. Nothing was created.

403The key lacks the scope, or the key's owner has view-only access to the workspace (code forbidden).

404Not found.

429Rate limited, or a monthly cap reached.

503Raylight can't write pitches right now (code disabled). Nothing was created.

200 response body

Field	Type	Description
`production`required	object
`production.id`required	uuid
`production.workspaceId`required	uuid
`production.stage`required	enum	One of: `queued`, `writing_pitch`, `pitch_ready`, `greenlit`, `making`, `exporting`, `delivered`, `skipped`, `declined`, `cancelled`, `failed`
`production.source`required	object
`production.source.kind`required	enum	One of: `app`, `api`, `mcp`
`production.source.externalId`required	string \| null
`production.source.origin`	object \| null	Default `null`
`production.source.origin.provider`required	string
`production.source.origin.label`required	string
`production.source.origin.url`	url \| null	Default `null`
`production.source.origin.ref`	string \| null	Default `null`
`production.source.origin.requestedBy`	string \| null	Default `null`
`production.brief`required	object
`production.brief.intent`required	string
`production.brief.context`	string \| null	Default `null`
`production.brief.media`	object[]
`production.brief.media[].id`required	string
`production.brief.media[].kind`required	enum	One of: `image`, `video`
`production.brief.media[].url`required	url
`production.brief.media[].name`required	string
`production.brief.media[].description`	string \| null	Default `null`
`production.brief.code`	object[]
`production.brief.code[].path`required	string
`production.brief.code[].source`required	string
`production.brief.code[].status`	enum \| null	One of: `added`, `modified`, `removed`, `renamed`Default `null`
`production.brief.code[].additions`	integer	Default `0`
`production.brief.code[].deletions`	integer	Default `0`
`production.brief.code[].patch`	string \| null	Default `null`
`production.brief.code[].digest`	string \| null	Default `null`
`production.brief.code[].score`	number	Default `0`
`production.brief.code[].sourceOmitted`	boolean
`production.brief.format`	object
`production.brief.format.template`	enum	One of: `changelog`, `launch`, `feature`, `digest`, `custom`Default `changelog`
`production.brief.format.durationMs`	integer	Default `10000`
`production.brief.format.aspect`	enum	One of: `16:9`, `4:3`, `3:2`, `21:9`, `1:1`, `9:16`, `3:4`, `2:3`, `4:5`Default `16:9`
`production.brief.format.sound`	object
`production.brief.format.sound.voiceover`	boolean	Default `true`
`production.brief.format.sound.music`	boolean	Default `true`
`production.brief.format.sound.sfx`	boolean	Default `true`
`production.brief.brand`	object
`production.brief.brand.name`	string \| null	Default `null`
`production.brief.brand.logoUrl`	url \| null	Default `null`
`production.brief.brand.primaryColor`	string \| null	Default `null`
`production.brief.brand.backgroundColor`	string \| null	Default `null`
`production.brief.brand.fontFamily`	string \| null	Default `null`
`production.brief.brand.tone`	string \| null	Default `null`
`production.pitch`required	object \| null
`production.pitch.version`required	integer
`production.pitch.verdict`	enum	One of: `video`, `skip`Default `video`
`production.pitch.verdictReason`	string \| null	Default `null`
`production.pitch.title`required	string
`production.pitch.summary`required	string
`production.pitch.shots`required	object[]
`production.pitch.shots[].index`required	integer
`production.pitch.shots[].title`required	string
`production.pitch.shots[].durationMs`required	integer
`production.pitch.shots[].beat`	string \| null	Default `null`
`production.pitch.shots[].visual`required	string
`production.pitch.shots[].text`	string \| null	Default `null`
`production.pitch.shots[].voiceover`	string \| null	Default `null`
`production.pitch.shots[].mediaIds`	string[]
`production.pitch.shots[].codePaths`	string[]
`production.pitch.music`	string \| null	Default `null`
`production.pitch.estimatedCredits`required	integer
`production.pitch.createdAt`required	datetime
`production.greenlight`required	object \| null
`production.greenlight.mode`required	enum	One of: `manual`, `auto`
`production.greenlight.actor`required	string
`production.greenlight.actorName`	string \| null
`production.greenlight.at`required	datetime
`production.greenlight.pitchVersion`required	integer
`production.greenlightMode`required	enum	One of: `manual`, `auto`
`production.delivery`required	object \| null
`production.delivery.shareUrl`required	url
`production.delivery.projectId`required	uuid
`production.delivery.editUrl`required	url
`production.delivery.exportId`required	uuid
`production.delivery.deliveredAt`required	datetime
`production.projectId`required	uuid \| null
`production.creditsCharged`required	integer
`production.error`required	string \| null	Why the production failed, in words you can show a person. Never the render machine's own diagnostics.
`production.createdAt`required	datetime
`production.updatedAt`required	datetime
`production.terminal`	boolean	True once the stage is one the production never leaves (delivered, skipped, declined, cancelled, failed, or a terminal stage added later). Stop polling when it is true; it is computed by the server, so it stays right for stages your client does not know yet. Absent from payloads stored before the field existed.
`production.pageUrl`	url	The production's page in the Raylight app. Absent from payloads stored before the field existed.

201 response body

Field	Type	Description
`production`required	object
`production.id`required	uuid
`production.workspaceId`required	uuid
`production.stage`required	enum	One of: `queued`, `writing_pitch`, `pitch_ready`, `greenlit`, `making`, `exporting`, `delivered`, `skipped`, `declined`, `cancelled`, `failed`
`production.source`required	object
`production.source.kind`required	enum	One of: `app`, `api`, `mcp`
`production.source.externalId`required	string \| null
`production.source.origin`	object \| null	Default `null`
`production.source.origin.provider`required	string
`production.source.origin.label`required	string
`production.source.origin.url`	url \| null	Default `null`
`production.source.origin.ref`	string \| null	Default `null`
`production.source.origin.requestedBy`	string \| null	Default `null`
`production.brief`required	object
`production.brief.intent`required	string
`production.brief.context`	string \| null	Default `null`
`production.brief.media`	object[]
`production.brief.media[].id`required	string
`production.brief.media[].kind`required	enum	One of: `image`, `video`
`production.brief.media[].url`required	url
`production.brief.media[].name`required	string
`production.brief.media[].description`	string \| null	Default `null`
`production.brief.code`	object[]
`production.brief.code[].path`required	string
`production.brief.code[].source`required	string
`production.brief.code[].status`	enum \| null	One of: `added`, `modified`, `removed`, `renamed`Default `null`
`production.brief.code[].additions`	integer	Default `0`
`production.brief.code[].deletions`	integer	Default `0`
`production.brief.code[].patch`	string \| null	Default `null`
`production.brief.code[].digest`	string \| null	Default `null`
`production.brief.code[].score`	number	Default `0`
`production.brief.code[].sourceOmitted`	boolean
`production.brief.format`	object
`production.brief.format.template`	enum	One of: `changelog`, `launch`, `feature`, `digest`, `custom`Default `changelog`
`production.brief.format.durationMs`	integer	Default `10000`
`production.brief.format.aspect`	enum	One of: `16:9`, `4:3`, `3:2`, `21:9`, `1:1`, `9:16`, `3:4`, `2:3`, `4:5`Default `16:9`
`production.brief.format.sound`	object
`production.brief.format.sound.voiceover`	boolean	Default `true`
`production.brief.format.sound.music`	boolean	Default `true`
`production.brief.format.sound.sfx`	boolean	Default `true`
`production.brief.brand`	object
`production.brief.brand.name`	string \| null	Default `null`
`production.brief.brand.logoUrl`	url \| null	Default `null`
`production.brief.brand.primaryColor`	string \| null	Default `null`
`production.brief.brand.backgroundColor`	string \| null	Default `null`
`production.brief.brand.fontFamily`	string \| null	Default `null`
`production.brief.brand.tone`	string \| null	Default `null`
`production.pitch`required	object \| null
`production.pitch.version`required	integer
`production.pitch.verdict`	enum	One of: `video`, `skip`Default `video`
`production.pitch.verdictReason`	string \| null	Default `null`
`production.pitch.title`required	string
`production.pitch.summary`required	string
`production.pitch.shots`required	object[]
`production.pitch.shots[].index`required	integer
`production.pitch.shots[].title`required	string
`production.pitch.shots[].durationMs`required	integer
`production.pitch.shots[].beat`	string \| null	Default `null`
`production.pitch.shots[].visual`required	string
`production.pitch.shots[].text`	string \| null	Default `null`
`production.pitch.shots[].voiceover`	string \| null	Default `null`
`production.pitch.shots[].mediaIds`	string[]
`production.pitch.shots[].codePaths`	string[]
`production.pitch.music`	string \| null	Default `null`
`production.pitch.estimatedCredits`required	integer
`production.pitch.createdAt`required	datetime
`production.greenlight`required	object \| null
`production.greenlight.mode`required	enum	One of: `manual`, `auto`
`production.greenlight.actor`required	string
`production.greenlight.actorName`	string \| null
`production.greenlight.at`required	datetime
`production.greenlight.pitchVersion`required	integer
`production.greenlightMode`required	enum	One of: `manual`, `auto`
`production.delivery`required	object \| null
`production.delivery.shareUrl`required	url
`production.delivery.projectId`required	uuid
`production.delivery.editUrl`required	url
`production.delivery.exportId`required	uuid
`production.delivery.deliveredAt`required	datetime
`production.projectId`required	uuid \| null
`production.creditsCharged`required	integer
`production.error`required	string \| null	Why the production failed, in words you can show a person. Never the render machine's own diagnostics.
`production.createdAt`required	datetime
`production.updatedAt`required	datetime
`production.terminal`	boolean	True once the stage is one the production never leaves (delivered, skipped, declined, cancelled, failed, or a terminal stage added later). Stop polling when it is true; it is computed by the server, so it stays right for stages your client does not know yet. Absent from payloads stored before the field existed.
`production.pageUrl`	url	The production's page in the Raylight app. Absent from payloads stored before the field existed.

Example

curl

curl -X POST https://api.raylight.app/v1/productions \  -H "Authorization: Bearer $RAYLIGHT_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "brief": {    "intent": "Announce dark mode in the Acme dashboard to existing customers.",    "context": "PR #412 adds a theme toggle to Settings. Charts, tables and the sidebar all pick up the dark palette. Ships to everyone on Thursday.",    "media": [      {        "id": "dashboard-dark",        "kind": "image",        "url": "https://cdn.acme.dev/press/dashboard-dark.png",        "name": "Dashboard in dark mode",        "description": "The analytics overview with the new dark theme."      }    ],    "code": [      {        "path": "src/components/settings/theme-toggle.tsx",        "source": "export const ThemeToggle = () => { /* ... */ }"      }    ],    "format": {      "template": "feature",      "durationMs": 10000,      "aspect": "16:9",      "sound": { "voiceover": true, "music": true, "sfx": true }    },    "brand": {      "name": "Acme",      "primaryColor": "#6C5CE7",      "tone": "confident, plain"    }  },  "greenlightMode": "manual",  "externalId": "acme/web#412",  "origin": {    "provider": "github",    "label": "acme/web #412",    "url": "https://github.com/acme/web/pull/412",    "ref": "feat/dark-mode",    "requestedBy": "jane"  }}'