Render Jobs

Every call to POST /api/v2/render or POST /api/v2/preflight creates a durable render job record. Jobs capture the input payload, output artifacts, quality report, approval state, and an event timeline so you can trace exactly what happened.

Job Lifecycle

A render job moves through these states:

Code

queued -> running -> succeeded
                  \-> failed

Status	Meaning
`queued`	Job created, waiting for processing
`running`	Engine is actively rendering or running preflight
`succeeded`	Render completed, artifacts available
`failed`	Render failed -- `error_code` and `error_message` explain why
`cancelled`	Job was cancelled before completion

When you submit a render with mode: "async", the response returns immediately with job_id and job_url. Poll GET /api/v2/jobs/:id until the status reaches succeeded or failed.

Synchronous mode (mode: "sync") blocks until the job finishes and returns artifacts inline.

Job Record Fields

Key fields on the job record:

kind -- render, preflight, or validate
source_schema -- protocol_v2, agent_v1, or paper_document
document_title, slide_count -- extracted from the input
deck_score -- numeric quality score from the preflight report
brand_pack_id, brand_pack_version_id -- brand pack used during rendering
baseline_job_id -- the previous job used for diff comparison
approval_status -- see Review Loop
download_url, preview_url -- links to the generated PPTX and slide preview

Artifacts

Each job can have multiple artifact records:

Kind	Description
`generated_pptx`	The rendered PowerPoint file
`preview_png`	Per-slide rasterized previews
`quality_report`	JSON quality report with deck score and findings
`validation_record`	Desktop validation recording URL (when applicable)
`baseline_diff`	Diff data against the baseline job

Quality Report

The quality report is available on the job record at quality_report and includes:

deckScore -- 0-100 composite quality score
slideCount -- number of slides evaluated
findings -- array of issues with message, severity, and location metadata

Viewing a Job

Terminal

curl https://api.cmdcal.com/api/v2/jobs/JOB_ID \
  -H "Authorization: Bearer pj_live_YOUR_KEY"

The response includes the job record plus computed summaries: approval, diffSummary, preflight, policy, findingSummary, brandCompliance, validation, baseline, and artifacts.

Listing Jobs

Terminal

curl "https://api.cmdcal.com/api/v2/jobs?limit=25&status=succeeded" \
  -H "Authorization: Bearer pj_live_YOUR_KEY"

Filter parameters: status, approvalStatus, kind, brandPackId, sourceSchema. Maximum limit is 100.

Re-rendering

To re-render a job, submit the same payload to /api/v2/render with the original job_id as baselineJobId. The new job records a diff against the baseline so you can compare output changes.

Retention

Render job records and their metadata are retained indefinitely. Binary artifacts (PPTX files, preview images) are stored in the platform's object storage and are available for download as long as the job record exists.