Typed templates and bulk rendering

A template is a published, version-pinned project with a small typed input contract. Build and visually approve the project in Studio first, then publish it for automation.

Publish a project

curl -X POST "$JSONCUT_API/api/v2/templates" \
  -H "X-API-Key: $JSONCUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"'"$PROJECT_ID"'","name":"Product launch card","publish":true}'

Discover inputs

Never guess field names or media requirements:

curl "$JSONCUT_API/api/v2/templates/$TEMPLATE_ID/inputs" \
  -H "X-API-Key: $JSONCUT_API_KEY"

The response describes required fields, types, constraints, accepted MIME types and examples. Supported types are string, number, boolean, color, image, video, audio, sanitized HTML and bounded flat string arrays.

Render one variant

curl -X POST "$JSONCUT_API/api/v2/templates/$TEMPLATE_ID/renders" \
  -H "X-API-Key: $JSONCUT_API_KEY" \
  -H "Idempotency-Key: sku-1042-de" \
  -H "Content-Type: application/json" \
  -d '{"values":{"headline":"Jetzt erhältlich","price":79.9,"productImage":"jsoncut-media://media_01J..."},"kind":"image","format":"webp","imageQuality":92}'

Bulk JSON

curl -X POST "$JSONCUT_API/api/v2/templates/$TEMPLATE_ID/bulk-renders" \
  -H "X-API-Key: $JSONCUT_API_KEY" \
  -H "Content-Type: application/json" \
  --data @variants.json

{
  "version": 4,
  "items": [
    { "idempotencyKey": "sku-1042-de", "values": { "headline": "Jetzt erhältlich", "price": 79.9 } },
    { "idempotencyKey": "sku-1042-en", "values": { "headline": "Available now", "price": 79.9 } }
  ],
  "output": { "kind": "image", "format": "png" }
}

JSON and CSV batches are capped at 500 rows. Every row is validated before queueing and the batch is pinned to one immutable template version. Invalid rows are reported without preventing valid rows from rendering.

Poll GET /api/v2/bulk-renders/{id} or cancel unfinished work with DELETE /api/v2/bulk-renders/{id}.

Bulk CSV

CSV headers must match template input IDs. Values are parsed against the published input types before any valid row is queued.

headline,price,showBadge
Jetzt erhältlich,79.9,true
Available now,79.9,false

Submit exactly one of items or csv. Batch-level defaults are merged first and row values take precedence. A batch-level idempotencyKey identifies the whole request; optional row keys identify individual outputs.

Row validation

Every row is validated against the pinned template version. Valid rows enter the queue and invalid rows remain visible with their index and safe error. Studio can correct and resubmit selected rows. Public API clients submit a new batch containing the corrected rows and keep the same explicit template version when the approved design must remain unchanged.