Variable Schema & API Preview

Light-dev section

This page bridges the visual designer and the API. If you’re only using Zandovi from the browser you don’t need to read this — but if you or a developer on your team will be rendering templates programmatically, this is the connecting piece.

What is the variable schema?

Every template that contains one or more variable-bound elements has a schema — a machine-readable description of the variables it accepts. The schema is used by the API to validate render requests, and is shown in the API documentation for that template.

The API Preview code block

In the Variable section for each element (for a text variable, inside its Advanced sub-section), the API Preview shows a read-only snippet of how to send that variable in a request’s variables object. For a text variable named discount_code:

"variables": {
  "discount_code": "value"
}

The Variables panel (left rail) has the same preview for the whole template under API Request Preview.

Viewing the full schema

The schema itself is served by the API: GET /api/v1/templates/{id} returns the template’s variables list — see Templates & schema discovery. A required text variable named discount_code with the label “Discount Code” and the default SAVE10 appears as (abridged):

{
  "name": "discount_code",
  "type": "text",
  "label": "Discount Code",
  "required": true,
  "defaultValue": "SAVE10"
}

An image variable named profile_photo with an empty Default URL and a photo placed on the canvas appears as (abridged; an image variable’s label is its name):

{
  "name": "profile_photo",
  "type": "image",
  "label": "profile_photo",
  "required": false,
  "defaultValue": "zandovi://images/3f2a9c1e-7b4d-4e8a-9c21-5d6f0a1b2c3d"
}

The defaultValue is the Default URL when one is set, otherwise the image placed on the canvas. An image variable is required only when it has no Default URL and no canvas image.

For a ready-to-run request, click API in the header (tooltip: “API usage example”). It opens the Generate dialog on its API tab, with cURL, JavaScript and Python examples for this template, filled with the values from the Single Image tab. A developer reads the schema to know which keys to send in the variables object.

How render requests use the schema

When your developer generates an image they POST to the template’s generate endpoint with a variables object whose keys match the variable names you defined:

curl -X POST https://app.zandovi.com/api/v1/templates/$TEMPLATE_ID/generate \
  -H "X-Api-Key: $ZANDOVI_API_KEY" \
  -H "Content-Type: application/json" \
  -o coupon.png \
  -d '{
    "variables": {
      "first_name": "Sarah",
      "discount_code": "VIP30",
      "redemption_url": "https://shop.example.com/redeem/VIP30"
    },
    "format": "png"
  }'

The response is the rendered image itself. Required variables that are missing return a validation error; optional variables that are missing use their default values. See Generating images.