Update a job

PATCH /api/jobs/{jobId}

Requires batches:update. Only a job that is pending can be changed; any other job returns 409. To render a finished job with other values, create a new job.

Request body

modifications are merged over the job's own, not substituted for them. A key you send replaces the job's value for that layer (names are matched without regard to case, so headline replaces Headline), and layers you do not mention keep theirs. Send null to clear a layer back to the page's own value. Keys and values are as in Modifications.

Fields the API does not know are refused.

curl --request PATCH "https://app.kalpana.one/api/jobs/7b0c2d1e-4f5a-4c8b-9e3d-2a6f1b8c0d11" \
  --header "x-api-key: $KALPANA_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "workspace": "acme",
    "modifications": {
      "headline": "Last chance",
      "Badge": null
    },
    "output": { "format": "webp" }
  }'

Here Headline becomes Last chance, Badge goes back to the page's value, and every other layer is untouched.

Response

The updated job, in the shape of The job object:

{
  "id": "7b0c2d1e-4f5a-4c8b-9e3d-2a6f1b8c0d11",
  "status": "pending",
  "template": { "id": "t4hz8c1n", "name": "Weekend sale" },
  "page": { "id": "k7fq2m8a", "name": "Feed" },
  "flow": null,
  "batch": null,
  "modifications": { "Headline": "Last chance", "Photo": { "asset": "0b0f5a3e-5b1c-4d65-9a5e-3f7d2f2f6c11", "name": "shoe.png" } },
  "output": { "format": "webp", "kind": "image" },
  "creditCost": 1,
  "error": null,
  "file": null,
  "createdAt": "2026-11-09T09:41:07.512Z",
  "updatedAt": "2026-11-09T09:52:30.118Z"
}

creditCost is worked out again from the new output. After changing, run the job with Run a job, or run its batch.

A job made in the Kalpana app has no stored modifications. It can still be changed: the keys you send are applied over its own values.

Errors