Batches

A batch renders one template version with many records of values: a badge for every attendee, an invoice for every customer. The server’s workers render the records one by one, and the batch can end in one file: their pages merged into one PDF, or every record’s file in a ZIP.

Submit a batch

Each record is a values object, as one render takes. With "combine": "pdf" the records’ pages are merged in order:

curl -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"template": "tpl_9fK2mQ7rLx4VbN1s", "combine": "pdf", "records": [{"name": "Grace Hopper", "role": "Keynote speaker"}, {"name": "Alan Turing", "role": "Panel chair"}]}' "$PAPRIKA_URL/v1/batches"

{
  "id": "bat_A1b2C3d4E5f6G7h8I9j0",
  "status": "queued",
  "template": "tpl_9fK2mQ7rLx4VbN1s",
  "version": 1,
  "format": "pdf",
  "combine": "pdf",
  "records": 2,
  "counts": { "queued": 2, "running": 0, "done": 0, "failed": 0, "cancelled": 0, "remaining": 2 }
}

What a batch takes besides its records:

Setting	What it does
version	The version to render, latest by default.
combine	none (the default: every record’s file on its own), pdf (merged into one PDF, up to 1,000 records) or zip (every record’s file and a report.json).
filename	Each record’s file name as a pattern of its values, such as badge-{name} (a number or switch as sent, 12.5 or true; a choice its value); by default its number.
skipInvalid	true renders the records that are fine and fails the others; by default one bad record refuses the batch.
stopOnFailure	true cancels the rest when a record fails to render; by default the others carry on.
format, profile, …	What a render takes, the same for every record.

A batch has up to 10,000 records. Every record is checked against the template’s fields as the batch is submitted: if any break them, the batch is refused (422) with every problem by record. Here the second record has no name:

curl -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"template": "tpl_9fK2mQ7rLx4VbN1s", "records": [{"name": "Grace Hopper", "role": "Keynote speaker"}, {"role": "Speaker"}]}' "$PAPRIKA_URL/v1/batches"

{
  "code": "records-invalid",
  "message": "1 record breaks the template's contract; see errors (or send skipInvalid: true)",
  "records": [
    {
      "record": 2,
      "errors": [
        { "field": "name", "code": "field-missing", "message": "Missing required field: name" }
      ]
    }
  ],
  "requestId": "fd1b399f"
}

The Idempotency-Key header makes a retried submit safe, as it does for jobs.

Follow it

curl -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/batches/bat_A1b2C3d4E5f6G7h8I9j0"

{
  "id": "bat_A1b2C3d4E5f6G7h8I9j0",
  "status": "done",
  "records": 2,
  "counts": { "queued": 0, "running": 0, "done": 2, "failed": 0, "cancelled": 0, "remaining": 0 },
  "output": {
    "id": "out_Q2nW8vX4zR6tY1uI3oP5",
    "records": 2,
    "pages": [
      { "record": 1, "pages": [1, 1] },
      { "record": 2, "pages": [2, 2] }
    ],
    "download": "/v1/outputs/out_Q2nW8vX4zR6tY1uI3oP5"
  }
}

A batch is queued, running, then done (every record rendered), partial (some failed), failed (none rendered) or cancelled. The combined output says which pages are whose. Download it:

curl -H "Authorization: Bearer $PAPRIKA_KEY" -o badges.pdf "$PAPRIKA_URL/v1/outputs/out_Q2nW8vX4zR6tY1uI3oP5"

Each record is a job of its own, with its own output and its error when it failed:

curl -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/batches/bat_A1b2C3d4E5f6G7h8I9j0/records"

POST /v1/batches/<id>/cancel cancels the records not yet rendered. Rather than asking, a webhook can tell you when a batch ends: batch.done, batch.partial, batch.failed or batch.cancelled.