Review Loop

The review loop lets your team inspect rendered output, compare it against a baseline, and formally approve or reject it before the artifact is delivered downstream.

Requesting Approval

Set approvalRequired: true when submitting a render:

{
  "sourceSchema": "protocol_v2",
  "mode": "async",
  "approvalRequired": true,
  "baselineJobId": "job_previous_abc",
  "document": { ... }
}

The job is created with approval_status: "needs_review" instead of "not_requested".

Approval States

Comparing Against a Baseline

When you pass baselineJobId, the platform records a diff between the current render and the baseline. The diff summary includes:

• totalSlides -- slides in the current render
• changedSlides -- slides that differ from the baseline
• unchangedSlides -- slides identical to the baseline
• addedSlides -- slides present in current but not baseline
• removedSlides -- slides present in baseline but not current

Retrieve the diff via GET /api/v2/jobs/:id, which returns a diffSummary object alongside the job record.

Approving or Rejecting

Update the approval status on a job by calling the approval endpoint:

curl -X PATCH https://api.paperjsx.com/api/v2/jobs/JOB_ID \
  -H "Authorization: Bearer pj_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "approval": {
      "status": "approved",
      "note": "Layout looks correct, brand compliance passed."
    }
  }'

Each approval or rejection is recorded as an entry in the job's approvalHistory array with the actor ID, actor type (user or system), note, and timestamp.

Who Can Approve

Any authenticated user with owner or admin role in the organization can approve or reject jobs. API key-authenticated requests can also update approval status when the key belongs to the same organization.

Approval History

The job record stores the full approval history in metadata.approvalHistory. Each entry contains:

• status -- needs_review, approved, or rejected
• actorId -- the user or API key that took the action
• actorType -- user or system
• note -- optional free-text note
• createdAt -- ISO 8601 timestamp

Filtering Jobs by Approval Status

List jobs that need review:

curl "https://api.paperjsx.com/api/v2/jobs?approvalStatus=needs_review" \
  -H "Authorization: Bearer pj_live_YOUR_KEY"

Next Steps

• Render Jobs -- full job lifecycle reference
• Brand Packs -- brand compliance findings feed into review decisions
• Automation -- integrate approval gates into CI/CD