Design Reference

GET /api/v1/design-reference and its sub-routes serve the same knowledge pack the Zandovi MCP server bundles for AI assistants: the authoring guide, every element type’s field table, the bundled fonts and icons, canvas size presets, and complete golden examples. If you’re calling POST /api/v1/designs/validate, POST /api/v1/templates or PATCH /api/v1/templates/{id} directly, without going through an MCP client, this is where you learn the design format.

The whole family requires the design:read scope, costs nothing against your render quota, and is cheap to poll: every response carries a content ETag you can send back as If-None-Match.

Authentication and cost

Credential	X-Api-Key header or Authorization: Bearer (OAuth)
Required scope	design:read
Quota	Free, does not consume renders
Rate limit	The DESCRIBE tier, same as other read-only discovery endpoints
Caching	ETag + Cache-Control: private, max-age=3600; send If-None-Match for a 304

A request without design:read returns 403 with code: INSUFFICIENT_SCOPE. See Errors, quotas & rate limits for the response shape.

JSON only

Every route produces application/json, including the markdown topics below; the markdown is a string field inside a JSON envelope. Sending Accept: text/markdown (or any media type other than JSON) returns 406 Not Acceptable.

Index

GET /api/v1/design-reference

Everything the family serves, with relative hrefs so you can navigate from this one response: the eight markdown topics, one entry per element type, the three supporting types, the golden examples, and the capabilitiesVersion / capabilitiesHash of this deployment. These are the same values GET /api/v1/account reports, so you can tell when reference content you cached is stale.

curl https://app.zandovi.com/api/v1/design-reference \
  -H "X-Api-Key: $ZANDOVI_API_KEY"

Response fields

Field	Type	Description
capabilitiesVersion	string	Version of the canvas schema this deployment accepts
capabilitiesHash	string	Fingerprint of the fonts, icons, presets and element tables this deployment validates against
topics	array	The eight markdown topics, in reading order: {topic, href, description}
elementTypes	array	One entry per element type: {type, origin, summary, requiredOwnFields, href}
supportingTypes	array	["viewport", "background", "fill"], the types element-types/{type} also describes
examples	array	The golden examples: {name, description, href}
note	string	The base fields every element needs, beyond type and its own required fields

Markdown topics

GET /api/v1/design-reference/{topic}

topic is one of guide, variables, elements, fonts, icons, presets, examples or codes, matched after trimming and lower-casing (Guide and %20fonts%20 both resolve). content is byte-identical to the corresponding pack file the MCP server ships: the same prose, not a paraphrase.

curl https://app.zandovi.com/api/v1/design-reference/guide \
  -H "X-Api-Key: $ZANDOVI_API_KEY"

Response fields

Field	Type	Description
topic	string	The requested topic
capabilitiesVersion	string	Version of the canvas schema this deployment accepts
capabilitiesHash	string	Fingerprint this deployment validates against
contentType	string	Always text/markdown, the media type of content, not of the response itself
content	string	The topic’s markdown
related	object	Relative hrefs. The three fixed keys index, elementTypes and examples are always present, plus the other topics keyed by name, except the requested one (for the examples topic, this leaves examples itself as a self-link, since that fixed key is not topic-keyed)

The eight topics cover different ground:

• guide: how a design is put together, document shape, coordinates, text, variables, images, the authoring loop, and the per-type table of element fields that have a default value (see optional fields with defaults). At most 9,000 characters. Its variables section is a short summary that points at variables.
• variables: template variables in full: how an element is bound, which value renders, missing values and required, the checks on supplied values, shared names, render and batch behaviour with their error codes, and a worked upload → validate → generate → batch example.
• codes: every validation code validate_design, preview_design, create_template and edit_template can report, with its severity and meaning — the same table this page’s Authoring guide shows, split out of guide to keep that topic short.
• elements: field tables for every element type, as markdown, meant for reading. For a JSON version of the same fields, use element types below; elements and element-types describe the same fields in different formats, not different content. A field with a declared default is marked optional here, not required.
• fonts: the bundled font families, their weights and script coverage.
• icons: every bundled icon name, grouped for browsing.
• presets: canvas size presets with their design-space viewport, DPI and output intent.
• examples: the golden examples explained, what each one shows and how to adapt it. GET .../design-reference/examples with no name is this markdown topic, not a list; the list of examples is in the index.

Element types

GET /api/v1/design-reference/element-types
GET /api/v1/design-reference/element-types/{type}

The structured, JSON equivalent of the elements markdown topic: the same field tables get_design_reference returns over MCP for topics elements (index) and element:<type> (one type).

The bare route is an index: {kind: "index", elements[], supportingTypes[], note, capabilitiesVersion, capabilitiesHash}, where each entry in elements[] is {type, origin, summary, requiredOwnFields}.

curl https://app.zandovi.com/api/v1/design-reference/element-types \
  -H "X-Api-Key: $ZANDOVI_API_KEY"

{type} returns one element’s full field table, or one of the three supporting types (viewport, background, fill) that element fields reference but that aren’t elements themselves:

curl https://app.zandovi.com/api/v1/design-reference/element-types/rectangle \
  -H "X-Api-Key: $ZANDOVI_API_KEY"

{
  "type": "rectangle",
  "kind": "element",
  "origin": "top-left",
  "fields": [
    { "name": "type", "type": "rectangle", "required": true },
    { "name": "cornerRadius", "type": "number", "required": true }
  ],
  "unsupportedFields": [],
  "notes": ["x,y is the top-left corner of the element."],
  "example": { "type": "rectangle", "id": "panel", "x": 0, "y": 0, "width": 200, "height": 100 },
  "capabilitiesVersion": "1.0",
  "capabilitiesHash": "357ecc2c..."
}

An element body carries kind: "element" with fields, unsupportedFields, notes and a valid example; a supporting type carries kind: "supporting" with summary, notes, and either fields (viewport) or variants (background, fill).

{type} is matched with the same normalisation as the MCP tool: trim, lower-case, and drop hyphens, underscores and spaces, so curved-rectangle, CurvedRectangle and curvedrectangle all resolve to curvedRectangle.

Golden examples

GET /api/v1/design-reference/examples/{name}

A complete design that validates clean, so you can start from a working document instead of an empty one. name is kebab-case and matched after trimming and lower-casing only; hyphens are significant, so starter_coupon and startercoupon are both 404.

curl https://app.zandovi.com/api/v1/design-reference/examples/starter-coupon \
  -H "X-Api-Key: $ZANDOVI_API_KEY"

Response fields

Field	Type	Description
name	string	The example’s kebab-case name
description	string	What the example shows
design	object	The complete design: schemaVersion, viewport, background, elements, ready to pass to validate or create a template
capabilitiesVersion	string	Version of the canvas schema this deployment accepts
capabilitiesHash	string	Fingerprint this deployment validates against

The full list of examples, with their descriptions and hrefs, is in the index.

Errors

Code	code	Cause
401	UNAUTHORIZED	Missing or invalid credential
403	INSUFFICIENT_SCOPE	Credential lacks design:read
404	UNKNOWN_TOPIC	{topic} isn’t one of the eight markdown topics; details.topics lists them
404	UNKNOWN_ELEMENT_TYPE	{type} isn’t an element or supporting type; details.validTypes lists them (no fuzzy suggestions)
404	UNKNOWN_EXAMPLE	{name} isn’t a golden example; details.available lists them
406	(none)	Accept requested something other than application/json

See Errors, quotas & rate limits for the problem+json body shape.

Staying current

capabilitiesHash on every response matches the value GET /api/v1/account reports, so a client can cache reference content and only refetch when the hash changes. A prose edit to one topic (say, a clarification in guide) moves that topic’s own ETag without moving capabilitiesHash or any other topic’s ETag: the hash tracks fonts, icons, presets and element field tables, not wording.

For an AI assistant instead of your own integration code, see the MCP tools: get_design_reference serves the same pack over MCP, including the per-type field tables (topics elements, element:<type>).