Productions

Send comments

Send comments on the pitch and get the next pitch version, free. A production gets up to 6 pitch versions, so 5 rounds of comments; past that the answer is 429 with code cap. Pass pitchVersion to refuse the comments if the pitch changed meanwhile. If the next version cannot be written (the monthly pitch cap, or pitches being unavailable), the current pitch stands and a note event carries revisionRefused and message.

POST/v1/productions/{id}/comments

API key with the productions scope.

Parameters

Field	In	Type	Description
`id`required	path	uuid	The production id.

Request body

application/json

Field	Type	Description
`comment`required	string
`pitchVersion`	integer

Responses

200The production, writing its next pitch.

400Invalid request.

401Missing, invalid or revoked key.

402The workspace owner's credits do not cover the video (code credits). The current pitch stands.

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

404Not found.

409The pitch is not ready, or its version is out of date (code stage).

429Rate limited, or a monthly cap reached.

503Raylight can't write pitches right now (code disabled). The current pitch stands.

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.

Example

curl

curl -X POST https://api.raylight.app/v1/productions/$ID/comments \  -H "Authorization: Bearer $RAYLIGHT_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "comment": "Open on the toggle, not the logo. Drop the pricing shot.", "pitchVersion": 1 }'