Skip to main content
POST
Render the project head

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string | null

Path Parameters

project_id
string
required

Response

Successful Response

A freshly submitted render: the job row plus the advisory lint of its composition.

Returned only by the two submit routes (POST /v1/renders, POST /v1/projects/{id}/renders). A subclass rather than two more fields on :class:JobOut, because JobOut is the shape of a job row on every read route (GET /v1/renders, all /v1/tasks routes, the MCP read tools) where a lint result does not exist and would be permanently null.

id
string
required

Unique job ID. Prefix indicates type: render_ or task_.

Example:

"render_01J8QR2K5VKDGN2T4FBM3CZYX7"

kind
enum<string>
required

Whether this is a render or a task.

Available options:
render,
task
Example:

"render"

workspace_id
string
required

ID of the workspace that owns this job.

Example:

"ws_01J8QR2K5VKDGN2T4FBM3CZYX8"

status
enum<string>
required

Current lifecycle state: queuedprocessingcompleted / failed / cancelled.

Available options:
ingesting,
queued,
processing,
completed,
failed,
cancelled
Example:

"queued"

created_at
string<date-time>
required

ISO-8601 UTC timestamp when the job was created.

updated_at
string<date-time>
required

ISO-8601 UTC timestamp of the last status change.

ok
boolean
required

Advisory — the render was still accepted and dispatched. False means the composition has error-severity findings that will likely make the output wrong (a self-transition, a fully off-canvas element); it does NOT mean the submission was refused. Everything that actually blocks a render is a 422 before you ever see this field.

Example:

true

is_preview
boolean
default:false

True for a cheap preview render. Previews are not billed and are excluded from the renders list.

Example:

false

task_type
enum<string> | null

For task jobs only — the specific AI operation.

Available options:
transcribe
Example:

"transcribe"

progress_percent
integer
default:0

0–100 progress indicator updated by the render engine.

Required range: 0 <= x <= 100
Example:

0

progress_stage
enum<string> | null

Current processing phase within a job.

Available options:
downloading,
compositing,
encoding,
uploading
Example:

"compositing"

output
JobOutput · object | null

Populated once status == completed. Contains the signed artifact URL.

result
Result · object | null

Structured JSON result for tasks that return data rather than a file — transcribe returns the transcript here (text, words, utterances, and any requested analysis). Populated once status == completed; null for renders and for any job whose only artifact is the file at output.url.

Example:
error
JobError · object | null

Populated when status == failed. Contains a structured error code.

metadata
Metadata · object

Caller-supplied key-value pairs echoed back on every webhook and response.

Example:
completed_at
string<date-time> | null

ISO-8601 UTC timestamp when the job reached a terminal state.

violations
Violation · object[]

Advisory — the render was still accepted and dispatched. Cross-element and layout findings from the same linter the preview dry-run runs, attached so you can see problems on the render you just paid for instead of only in the artifact. To catch these BEFORE spending a render, call POST /v1/preview with dry_run.Truncated to the first 40 findings (errors first) on very large compositions, with a VIOLATIONS_TRUNCATED marker carrying the full count; the free dry run is never truncated.