Skip to main content
Visual overview:

​
Upload and ingest

​
Validation

​
Render and completion

Auto transitions from booting → rendering → completed are handled by Renderjuice once render starts.

​
Ingest flow

Creating a job is not the first API call.
  1. Call POST /api/external/v1/uploads to request a presigned upload URL.
  2. Upload a small .blend or .zip file directly to object storage.
  3. Call POST /api/external/v1/jobs with the slug returned by the upload endpoint.
  4. Renderjuice creates a job in created status.
This keeps uploads and job creation as separate steps, which makes retries and debugging easier for API clients.

​
Status flow

  • Upload step before job creation: request upload URL → upload file → create job
  • created → validating → validated → booting → rendering → finalizing → completed
  • Failure branch: any stage can move to failed.
  • Cancel branch: cancel is accepted until work finishes; canceled jobs remain canceled.

​
Allowed actions by status

  • Create job (POST /api/external/v1/jobs): accepts a previously returned upload slug and creates a job in created status. You do not need to send the filename again.
  • Validate (POST /api/external/v1/jobs/:id/validate): only from created; returns 400 if already validating/validated.
  • Render (POST /api/external/v1/jobs/:id/render): call after validated. A missing or empty requestedRenderConfig yields 400.
  • Cancel (POST /api/external/v1/jobs/:id/cancel): allowed while the job is in progress; expect failure once completed/failed/canceled.
  • Progress (GET /api/external/v1/jobs/:id/progress, GET /api/external/v1/jobs/progress): available anytime; returns current counters or an empty array when nothing is running.
  • Downloads (GET /api/external/v1/jobs/:id/downloads): returns download URLs once output is ready; earlier states respond with empty arrays.

​
Status reference

  • created: upload already completed and job record exists; no validation/render started.
  • validating → validated: validation in progress/finished.
  • booting: workers are provisioning.
  • rendering: frames are processing.
  • finalizing: outputs are being packaged.
  • completed: outputs are ready for download.
  • failed: validation or render failed; check failedReason.
  • canceled: user/system canceled the job.

​
Webhooks

  • Currently documented: onRenderComplete fires when a render finishes successfully.