Templates & Schema Discovery

Before you can generate an image you need a template ID and the list of variables that template accepts. These read endpoints let you discover both. All are authenticated with the X-Api-Key header and do not consume your render quota.

List projects

GET /api/v1/projects

Returns projects visible to the key’s workspace — your own (PRIVATE or SHARED) plus projects SHARED by other members.

Query parameters

Param	Type	Default	Description
page	integer	0	Page number (0-based)
limit	integer	20	Items per page (max 100)

Response — 200 OK, a list of project items:

[
  {
    "id": "019463b8-abcd-7890-1234-ef1234567890",
    "name": "Summer Campaign",
    "description": "Q3 promotional assets",
    "templateCount": 4,
    "visibility": "SHARED",
    "updatedAt": "2026-06-10T14:30:00Z"
  }
]

List templates in a project

GET /api/v1/projects/{projectId}/templates

Returns templates in the project that are visible to the key (own + shared). Does not include full canvas data.

Accepts the same page / limit parameters.

Response — 200 OK:

[
  {
    "id": "019463b8-1234-7890-abcd-ef1234567890",
    "name": "Summer Sale Coupon",
    "description": "20% off coupon",
    "projectId": "019463b8-abcd-7890-1234-ef1234567890",
    "visibility": "SHARED",
    "updatedAt": "2026-06-10T14:30:00Z"
  }
]

Get a template (variable discovery)

GET /api/v1/templates/{templateId}

Returns full template metadata and the variable schema. Use this to learn exactly what to send to the generate endpoint. The owner can read PRIVATE templates; other members can read SHARED ones.

Response — 200 OK:

{
  "id": "019463b8-1234-7890-abcd-ef1234567890",
  "name": "Summer Sale Coupon",
  "description": "20% off coupon for the summer campaign",
  "projectId": "019463b8-abcd-7890-1234-ef1234567890",
  "viewport": { "width": 1200, "height": 628 },
  "viewportUnit": "px",
  "viewportExportDpi": 96,
  "viewportOutputIntent": "screen",
  "visibility": "SHARED",
  "createdAt": "2026-05-01T09:00:00Z",
  "updatedAt": "2026-06-10T14:30:00Z",
  "variables": [
    {
      "name": "first_name",
      "type": "text",
      "label": "Customer Name",
      "required": true,
      "defaultValue": "Friend",
      "validation": { "maxLength": 40 }
    },
    {
      "name": "discount_code",
      "type": "text",
      "label": "Discount Code",
      "required": true
    }
  ]
}

Variable fields

Field	Description
name	Use this as the key in the variables map when generating
type	One of text, number, email, url, phone, date, qrcode, barcode, image
label	Human-readable label
required	Whether a value must be supplied
defaultValue	Used when no value is provided (if present)
validation	Optional rules: minLength, maxLength, min, max, pattern, allowed options

Caching

This endpoint returns an ETag and Cache-Control: private, max-age=60. Send If-None-Match with the ETag to get a 304 Not Modified and avoid re-fetching an unchanged schema.

Templates are authored visually in the app. The public API is read-and-generate: use these endpoints to discover schemas, then generate images.