Render Job Workflow

Render jobs process a deployed version asynchronously into a PDF. The workflow is: create → poll → download/preview → delete output.

1. Create a render job

Request: POST /v1/render-jobs

curl -X POST "$PRESS_CLOUD_API/v1/render-jobs" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: render-2026-04-28-001" \
  -d '{
    "deployId": "dpl_abc123",
    "deployVersionId": "latest",
    "businessKey": "invoice-2026-04-28",
    "payload": {
      "customer": "Acme Corp",
      "items": ["Widget", "Gadget"],
      "total": 42.99
    },
    "outputMode": "managed"
  }'

The deployVersionId can be a concrete version ID (dv_456) or the virtual pointer latest. Use outputMode: "managed" to persist the PDF as a managed asset, or outputMode: "transient" for auto-cleanup. The request payload is scoped to this render job and is deleted after the job succeeds or reaches a terminal failure.

Response: 202 Accepted

{
  "accepted": true,
  "queue": "default",
  "job": {
    "id": "rj_abc123",
    "deployId": "dpl_abc123",
    "deployVersionId": "dv_456",
    "businessKey": "invoice-2026-04-28",
    "status": "queued",
    "attempt": 0,
    "outputMode": "managed",
    "requestedAt": 1745800000000
  }
}

Error handling: 400 if required fields are missing. 404 if the deploy or version does not exist. Use the Idempotency-Key to safely retry on network errors — the server deduplicates within 24 hours.

2. Poll for completion

Render jobs transition through queued → rendering → succeeded (or failed). Poll GET /v1/render-jobs/{jobId} at 2–5 second intervals.

Request:

curl -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  "$PRESS_CLOUD_API/v1/render-jobs/rj_abc123"

Response (in progress):

{
  "job": {
    "id": "rj_abc123",
    "status": "rendering",
    "attempt": 0,
    "requestedAt": 1745800000000,
    "startedAt": 1745800010000
  }
}

Response (complete):

{
  "job": {
    "id": "rj_abc123",
    "status": "succeeded",
    "attempt": 0,
    "outputMode": "managed",
    "requestedAt": 1745800000000,
    "startedAt": 1745800010000,
    "finishedAt": 1745800050000
  },
  "output": {
    "id": "ro_abc123",
    "bytes": 204800,
    "pageCount": 4,
    "state": "available",
    "createdAt": 1745800050000
  },
  "pdf": {
    "id": "pdf_abc123",
    "state": "available",
    "fileName": "invoice-2026-04-28.pdf",
    "bytes": 204800,
    "pageCount": 4,
    "createdAt": 1745800050000
  }
}

Response (failed):

{
  "job": {
    "id": "rj_abc123",
    "status": "failed",
    "errorCode": "render_failed",
    "errorMessage": "Navigation timeout exceeded 30000 ms",
    "attempt": 1,
    "requestedAt": 1745800000000,
    "finishedAt": 1745800060000
  }
}

Error handling: If the job status is retry_scheduled, the system is automatically retrying. Continue polling. If status is failed, inspect errorCode and errorMessage to diagnose. Common failure reasons include:

Error code	Meaning	Action
navigation_timeout	Page took too long to load (exceeds timeout)	Increase renderTimeoutMs or optimize
render_crashed	Chromium crashed during rendering	Retry the job; contact support if persistent
render_timeout_exceeded	Render exceeded plan timeout limit	Simplify the document or upgrade plan

3. Preview or download the output

Create a download link

Request: POST /v1/render-jobs/{jobId}/output-download

curl -X POST "$PRESS_CLOUD_API/v1/render-jobs/rj_abc123/output-download" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN"

Use expiresInSeconds to customize the signed URL lifetime:

curl -X POST "$PRESS_CLOUD_API/v1/render-jobs/rj_abc123/output-download?expiresInSeconds=3600" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN"

Response: 200 OK

{
  "access": {
    "url": "https://storage.pressjs.dev/ro_abc123?signature=...",
    "expiresAt": 1745800650000
  }
}

Create a preview link

Request: POST /v1/render-jobs/{jobId}/output-preview

curl -X POST "$PRESS_CLOUD_API/v1/render-jobs/rj_abc123/output-preview" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN"

Preview links also accept expiresInSeconds:

curl -X POST "$PRESS_CLOUD_API/v1/render-jobs/rj_abc123/output-preview?expiresInSeconds=3600" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN"

Response: 200 OK — same structure as download, but the signed URL renders the PDF inline in a browser.

Error handling: 404 if the output has been deleted. 409 if the output is not yet available (job still running). 503 if the render provider is not configured.

4. Delete the output

Request: DELETE /v1/render-jobs/{jobId}/output

curl -X DELETE "$PRESS_CLOUD_API/v1/render-jobs/rj_abc123/output" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN"

Response: 204 No Content

Error handling: 404 if the output does not exist. 409 if the job is still rendering — wait for completion before deleting.