Run a job
Render a pending or failed job, waiting for the file like Create jobs does.
POST /api/jobs/{jobId}/runRequires renders:create.
| Name | Type | Required | Description |
|---|---|---|---|
workspace | string | Yes | Workspace slug or id. |
curl --request POST "https://app.kalpana.one/api/jobs/7b0c2d1e-4f5a-4c8b-9e3d-2a6f1b8c0d11/run" \
--header "x-api-key: $KALPANA_API_KEY" \
--header "content-type: application/json" \
--header "Prefer: wait=25" \
--data '{"workspace":"acme"}'Response
The answer has the shape Create jobs gives, with the one job in jobs:
{
"status": "done",
"jobs": [
{
"id": "7b0c2d1e-4f5a-4c8b-9e3d-2a6f1b8c0d11",
"status": "success",
"template": { "id": "t4hz8c1n", "name": "Weekend sale" },
"page": { "id": "k7fq2m8a", "name": "Feed" },
"flow": null,
"batch": null,
"modifications": { "Headline": "Weekend offer" },
"output": { "format": "png", "kind": "image" },
"creditCost": 1,
"error": null,
"file": {
"creativeId": "5d3a9c70-1e2b-4f86-a7c4-90b1d2e3f4a5",
"url": "https://cdn.kalpana.one/...",
"fileName": "weekend-sale-feed.png",
"contentType": "image/png",
"sizeBytes": 284113,
"width": 1080,
"height": 1080
},
"createdAt": "2026-11-09T09:41:07.512Z",
"updatedAt": "2026-11-09T09:41:11.208Z"
}
]
}The call waits up to 30 seconds (Prefer: wait=N to change that, wait=0 to skip it). It answers 200 when the job has finished. While it is still rendering it answers 202 with a Location header, /api/jobs?workspace=acme&ids=<id>, and Retry-After: 5: poll Get jobs until the request status is done.
Only a pending or failed job runs, so it is never rendered or charged twice. A job that is processing, success or cancelled is refused with 409; to render a finished or cancelled job again, create a new one. Credits are checked next and the call fails with 402 if there are not enough. Use it to retry one failed job; running a batch again only dispatches jobs that are still pending.
Errors
| Status | Cause |
|---|---|
402 | Not enough credits to run the job. |
403 | Your role or key lacks renders:create. |
404 | The job is not in this workspace, or its template has been deleted. |
409 | The job is processing, success or cancelled. message says which. |
500 | The job could not be dispatched. message gives the reason. |
Updated 9 Nov 2026