Conventions
Base URL, how parameters are sent, workspace scope, pagination, and safe retries.
Base URL
https://app.kalpana.one/apiResponses are JSON. Identifiers are opaque strings and timestamps are ISO 8601. Template, page and flow ids are text: new ones are short, such as k7fq2m8a, and older ones are UUIDs. Job and batch ids are UUIDs. Take every id from the API and pass it back as it is; never build or parse one.
How parameters are sent
| Request type | Where parameters go |
|---|---|
GET | Query string. Path placeholders such as {batchId} are part of the URL. |
POST, PATCH, PUT, DELETE | JSON body with content-type: application/json, including workspace. Path placeholders stay in the URL. |
Numbers and booleans in a query string are coerced for you, so ?page=2&limit=50 works as expected.
Workspace scope
Resources belong to a workspace. Send the workspace slug or id as workspace in the query or body. There is no separate workspace header.
A few endpoints name the field differently:
| Endpoint | Field |
|---|---|
GET /workspaces/{slug} | Path placeholder slug. |
GET /fonts | slug in the query. |
PATCH /templates/{id} | workspace_id in the body. |
POST /assets, POST /assets/from-url, POST /assets/uploads, POST /assets/uploads/complete | workspaceId in the body. |
POST /fonts, POST /fonts/uploads, POST /fonts/uploads/complete | workspaceId in the body. |
Request size
POST /jobs and the /batches writes accept a body of up to 4 MiB. A larger one is refused with 413 and Request exceeds 4 MiB.. A full batch of 1,000 rows is about 1.2 MiB at its largest.
Pagination
List endpoints accept page (starts at 1) and limit, and return the matching total. The maximum limit is 100 on every list endpoint. Default page sizes differ by resource and are stated on each page.
Safe retries
GET requests are safe to repeat. Before repeating a POST that creates something, list the resource first: a lost response does not mean the request failed. Running a batch is idempotent in effect, because only jobs that are still pending are dispatched. Run a job runs only a job that is pending or failed. A job that is rendering, has rendered or was cancelled is refused with 409. A missing job returns 404.
Slow calls
Most calls answer at once. Create jobs with run set to true waits up to 30 seconds for the renders. If a render is still running, it answers 202 with the jobs, a Location header that points to them and a Retry-After header with the seconds to wait. 202 is not an error: poll the Location URL. Send Prefer: wait=N to shorten the wait, or Prefer: wait=0 to skip it.
Updated 9 Nov 2026