Update a batch
Rename a batch, or add, change and remove its pending jobs.
PATCH /api/batches/{batchId}Requires batches:update. Every part is optional and they can be combined in one call. An archived batch is refused with 400. Only pending jobs are changed or removed; a job that has started rendering or finished is never touched.
Request body
{
"workspace": "acme",
"name": "September products, final",
"add": {
"pages": ["k7fq2m8a", "p3rtv9we"],
"rows": [
{ "modifications": { "Headline": "Last chance", "Photo": "shoe.png" } }
]
},
"update": [
{
"job": "7b0c2d1e-4f5a-4c8b-9e3d-2a6f1b8c0d11",
"modifications": { "headline": "Weekend offer, extended", "Badge": null },
"output": { "format": "jpeg" }
}
],
"remove": ["c19e5a44-8d70-4b2f-b6a1-3e7d9f0a2c58"]
}| Field | Description |
|---|---|
workspace | Required. Workspace slug or id. |
name | A new name, up to 200 characters. |
add | New rows, built as in Create a batch: exactly one of pages, templates or flow, and 1 to 1,000 rows. Each row makes a job on every page named. |
update | Up to 1,000 changes to pending jobs. Each names a job (its id, which must belong to this batch) and gives modifications, output or both, with the same merge rules as Update a job: keys replace the job's own (case aside), null clears one back to the page's value, and output fields replace. |
remove | Ids of pending jobs of this batch to delete. A job that is not pending, or not in this batch, is skipped and not counted. |
Fields the API does not know are refused.
Response
{
"id": "9a2e6f31-5c7d-4b08-8e1a-d4f2c6b0a937",
"added": 2,
"updated": 1,
"removed": 1
}added counts the jobs created (rows times pages), updated the changes applied, and removed the jobs deleted. A batch's name change is not counted.
Added and updated jobs are pending. Run the batch again with Run a batch to render them: only jobs still pending are dispatched.
add is checked first and update is applied job by job. If an update entry is refused, the entries before it have already been applied. Check new rows with Validate a batch first, and send a small update list when the values are uncertain.
Errors
| Status | Cause |
|---|---|
400 | The batch is archived, add has issues (each row's problems are in data.issues), an update entry has a key or value that is not valid, or a field is unknown. |
403 | Your role or key lacks batches:update. |
404 | The batch is not in this workspace, a page, template or flow in add is not, or an update job is not in this batch. |
409 | An update job is not pending. |
413 | The body is larger than 4 MiB. |
Updated 9 Nov 2026