Upload and render a job

Renderjuice separates file transfer from job orchestration. Request an upload target, send the file bytes to object storage, then exchange the returned upload slug for a job. Use the job id for validation, rendering, monitoring, and downloads.

External API v1 requires validation for each new job. If a job already reports validated, continue to the render step instead of starting validation again.

Complete request flow

The workflow uses three values:

Value	Meaning	Stop using it after
`uploadUrl`	A presigned URL that accepts one file upload.	The `PUT` succeeds or the URL expires.
`slug`	The handle for the uploaded source file.	`POST /jobs` returns a job.
`id`	The identifier for the Renderjuice job.	Keep it for the life of the job.

Prerequisites

A Renderjuice API key with access to the target workspace. See the API overview.
A .blend or .zip file smaller than 5 GiB. The shell examples use curl and jq.

Set these variables before running the examples:

export RENDERJUICE_API_KEY="RJ-ABC-XYZ..."
export RENDERJUICE_API_BASE="https://api.renderjuice.com/api/external/v1"
export SOURCE_FILE="shot-010.zip"

1. Create an upload target

Call POST /uploads with the source filename and its matching file type:

upload_response=$(curl --fail-with-body --silent --show-error \
  --request POST "$RENDERJUICE_API_BASE/uploads" \
  --header "Authorization: Bearer $RENDERJUICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "fileName": "shot-010.zip",
    "fileType": "zip"
  }')

upload_url=$(jq -r '.uploadUrl' <<< "$upload_response")
upload_slug=$(jq -r '.slug' <<< "$upload_response")

The response contains:

{
  "uploadUrl": "https://storage.example.com/...",
  "slug": "quiet-lake-1234",
  "expiresAt": "2026-03-26T13:00:00.000Z"
}

The upload target reserves a storage location. It does not upload the file or create a job.

2. Upload the source file

Send the file bytes to uploadUrl with PUT:

curl --fail-with-body --silent --show-error \
  --request PUT \
  --upload-file "$SOURCE_FILE" \
  "$upload_url"

Do not send the Renderjuice API key to the presigned URL. The URL contains the storage authorization. Wait for a 2xx response before creating the job. Request a new upload target if expiresAt has passed.

External API v1 does not support multipart or resumable uploads. It accepts one .blend or .zip file smaller than 5 GiB in each presigned PUT. If the transfer fails, send the whole file again. If this limit blocks your workflow, email support@renderjuice.com with the file sizes you need to upload. Your message helps us measure demand and prioritize multipart upload support.

3. Create the job

Call POST /jobs with the upload slug after the PUT succeeds:

job_response=$(curl --fail-with-body --silent --show-error \
  --request POST "$RENDERJUICE_API_BASE/jobs" \
  --header "Authorization: Bearer $RENDERJUICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$(jq -n --arg slug "$upload_slug" '{slug: $slug}')")

job_id=$(jq -r '.id' <<< "$job_response")

The new job starts in created status:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174001",
  "createdAt": "2026-03-26T13:01:00.000Z",
  "updatedAt": "2026-03-26T13:01:00.000Z"
}

Use job_id for each request that follows. The upload slug has completed its role.

4. Start validation

Validation inspects the Blender project and records the scenes, cameras, view layers, frame settings, add-ons, and resource requirements that Renderjuice needs for rendering. It runs as an asynchronous job. Call POST /jobs/{id}/validate with an empty object to use the active scene and detected file defaults:

curl --fail-with-body --silent --show-error \
  --request POST "$RENDERJUICE_API_BASE/jobs/$job_id/validate" \
  --header "Authorization: Bearer $RENDERJUICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

For ZIP files that contain more than one .blend file or scene, send validationConfig to select pathToFileForRender and sceneToRender. The endpoint reference also documents bundled add-on selection.

New jobs created through external API v1 start as created, and the public API does not expose reuse of a previous job’s validation. If you resume an integration and GET /jobs/{id} reports validated, proceed to rendering without calling validation again.

5. Wait for validation

Use GET /jobs/{id} as the source of truth for job state. The endpoint returns the job under data:

while :; do
  job_response=$(curl --fail-with-body --silent --show-error \
    "$RENDERJUICE_API_BASE/jobs/$job_id" \
    --header "Authorization: Bearer $RENDERJUICE_API_KEY")

  job_status=$(jq -r '.data.status' <<< "$job_response")
  printf 'Validation status: %s\n' "$job_status"

  case "$job_status" in
    validated) break ;;
    failed|canceled)
      jq '.data.failedReason // .data.status' <<< "$job_response"
      exit 1
      ;;
    *) sleep 5 ;;
  esac
done

A production integration should set a client timeout and choose a poll interval that fits its workload. Stop polling when the job reaches validated, failed, or canceled.

6. Start the render

Call POST /jobs/{id}/render after validation succeeds. colorManagementPreset is required. Use default unless the project uses ACES:

render_response=$(curl --fail-with-body --silent --show-error \
  --request POST "$RENDERJUICE_API_BASE/jobs/$job_id/render" \
  --header "Authorization: Bearer $RENDERJUICE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "requestedRenderConfig": {
      "colorManagementPreset": "default"
    }
  }')

Renderjuice uses values found during validation for omitted settings. Add overrides such as frameRanges, activeCamera, activeViewLayer, or outputFormat when the render should differ from the validated project.

7. Monitor the render

Poll GET /jobs/{id} until the job reaches a terminal status:

while :; do
  job_response=$(curl --fail-with-body --silent --show-error \
    "$RENDERJUICE_API_BASE/jobs/$job_id" \
    --header "Authorization: Bearer $RENDERJUICE_API_KEY")

  job_status=$(jq -r '.data.status' <<< "$job_response")
  printf 'Render status: %s\n' "$job_status"

  case "$job_status" in
    completed) break ;;
    failed|canceled)
      jq '.data.failedReason // .data.status' <<< "$job_response"
      exit 1
      ;;
    *) sleep 5 ;;
  esac
done

Use GET /jobs/{id}/progress for frame counters while the render runs:

curl --fail-with-body --silent --show-error \
  "$RENDERJUICE_API_BASE/jobs/$job_id/progress" \
  --header "Authorization: Bearer $RENDERJUICE_API_KEY" | jq

The progress endpoint can return null before counters exist. Treat data.status from GET /jobs/{id} as the completion signal. Frame counts do not replace job status.

Status	Meaning	Client action
`created`	The job exists and has not started validation.	Start validation.
`validating`	Renderjuice is analyzing the source project.	Poll the job.
`validated`	Analysis succeeded and render configuration is available.	Start the render.
`booting`	Renderjuice is provisioning render workers.	Poll status; progress may be `null`.
`rendering`	Workers are rendering frames.	Poll status and optional progress.
`finalizing`	Renderjuice is packaging outputs.	Continue polling status.
`completed`	Outputs are ready.	Request download URLs.
`failed`	Validation or rendering failed.	Read `data.failedReason`.
`canceled`	A user or the system canceled the job.	Stop polling.

The onRenderComplete webhook can notify your integration when a render completes. Fetch the job after receiving the event, confirm its status, then request the downloads.

8. Download the outputs

Call GET /jobs/{id}/downloads after the job reaches completed:

downloads_response=$(curl --fail-with-body --silent --show-error \
  "$RENDERJUICE_API_BASE/jobs/$job_id/downloads" \
  --header "Authorization: Bearer $RENDERJUICE_API_KEY")

jq '{frameOutputs, compositeNodeOutputs, transforms}' \
  <<< "$downloads_response"

Use frameOutputs and compositeNodeOutputs for individual files. Each entry includes its signed url and preserved fileName; compositor outputs can include relativePath. The transforms object contains ZIP and video output states. Download the files before their signed URLs expire. The frames and compositeNodes URL arrays remain available for older integrations. New integrations should use the structured output fields.

Failures, cancellation, and retries

GET /jobs/{id} returns failedReason when Renderjuice can provide a client-facing failure description. Stop the workflow on failed or canceled; do not continue to render or download. Use POST /jobs/{id}/cancel to cancel work that has not finished. The start-render endpoint supports idempotent retries: a repeated request returns the current job and sets X-Idempotent-Replay: true after rendering has started. Do not assume that other POST endpoints share this retry behavior.

Overview

Endpoint Reference

Webhook Reference

Complete request flow

Prerequisites

1. Create an upload target

2. Upload the source file

3. Create the job

4. Start validation

5. Wait for validation

6. Start the render

7. Monitor the render

8. Download the outputs

Failures, cancellation, and retries

​Complete request flow

​Prerequisites

​1. Create an upload target

​2. Upload the source file

​3. Create the job

​4. Start validation

​5. Wait for validation

​6. Start the render

​7. Monitor the render

​8. Download the outputs

​Failures, cancellation, and retries

Complete request flow

Prerequisites

1. Create an upload target

2. Upload the source file

3. Create the job

4. Start validation

5. Wait for validation

6. Start the render

7. Monitor the render

8. Download the outputs

Failures, cancellation, and retries