Kalpana Docs

This walkthrough assumes KALPANA_API_KEY holds a key from Authentication.

Check the service

curl "https://app.kalpana.one/api/health"

A healthy service returns "OK". This call needs no key.

Find your workspace slug

curl "https://app.kalpana.one/api/workspaces" \
  --header "x-api-key: $KALPANA_API_KEY"

Each item has an id and a slug. Most endpoints take either as the workspace value.

Choose a template and read its pages and layers

curl "https://app.kalpana.one/api/templates?workspace=acme&search=product" \
  --header "x-api-key: $KALPANA_API_KEY"

curl "https://app.kalpana.one/api/templates/TEMPLATE_ID/summary?workspace=acme" \
  --header "x-api-key: $KALPANA_API_KEY"

The second response lists each page's id and its layers, with their names. A job or row fills a layer by its name or id.

Check the rows

curl --request POST "https://app.kalpana.one/api/batches/validate" \
  --header "x-api-key: $KALPANA_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "workspace": "acme",
    "pages": ["PAGE_ID"],
    "rows": [
      { "modifications": { "Headline": "Weekend offer", "Photo": "shoe.png" } },
      { "modifications": { "Headline": "New arrivals" } }
    ]
  }'

The answer says whether every row is valid, lists each problem with its row, and shows each row as the server read it. Nothing is created or charged.

Create the batch and run it

curl --request POST "https://app.kalpana.one/api/batches" \
  --header "x-api-key: $KALPANA_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "workspace": "acme",
    "name": "September products",
    "pages": ["PAGE_ID"],
    "rows": [
      { "modifications": { "Headline": "Weekend offer", "Photo": "shoe.png" } },
      { "modifications": { "Headline": "New arrivals" } }
    ],
    "run": true
  }'

The response is 201 with the batch id, its rowCount, the jobCount (rows times pages) and the creditCost. See Modifications for the keys and value formats.

Follow it and collect the files

curl "https://app.kalpana.one/api/batches/BATCH_ID?workspace=acme" \
  --header "x-api-key: $KALPANA_API_KEY"

curl "https://app.kalpana.one/api/batches/BATCH_ID/jobs/download?workspace=acme" \
  --header "x-api-key: $KALPANA_API_KEY"

Poll the batch until status is no longer pending or processing, then download. completed means every job has a file; partial, failed and cancelled mean some do not.

run: true spends credits and publishes the batch as it starts it. A batch created without it stays a draft that you review in the Studio and run there or with Run a batch. Start with a few rows while you test.

A few files without a batch

For up to 10 files you want back in the same call, skip the batch. Create jobs with run set to true renders them and, for most images, returns the files in the answer:

curl --request POST "https://app.kalpana.one/api/jobs" \
  --header "x-api-key: $KALPANA_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "workspace": "acme",
    "jobs": [
      { "page": "PAGE_ID", "modifications": { "Headline": "Weekend offer" } }
    ],
    "run": true
  }'

A 201 means every job has settled: each job's file.url holds its file, or error says why it failed. A 202 means a job is still rendering: poll Get jobs until the request status is done. See Render files without a batch.

Quickstart