OpenAPI Spec & Postman

The entire public API is described by a single OpenAPI 3.1 document. Download it to explore endpoints in Postman or Insomnia, generate a typed client, or drive your own tooling — no copy-pasting from these docs required.

Download

• Download OpenAPI spec (YAML) — recommended
• Download OpenAPI spec (JSON)

The spec covers only the public endpoints. Every operation carries one tag, and the tags are grouped (the x-tagGroups extension), so Postman and Insomnia build one folder per tag, code generators one client class per tag, and Redoc and Scalar show the groups in their sidebars:

Generate images

Tag	Method	Path	Purpose
Image generation	POST	/api/v1/templates/{templateId}/generate	Render a personalized image — returns bytes, or a share link with delivery: "link"
Batch jobs	POST	/api/v1/batch-jobs	Submit a batch job — one template, many rows
Batch jobs	GET	/api/v1/batch-jobs	List your batch jobs
Batch jobs	GET	/api/v1/batch-jobs/{jobId}	Poll a batch job’s status
Batch jobs	GET	/api/v1/batch-jobs/{jobId}/items	List a job’s per-row outcomes
Batch jobs	GET	/api/v1/batch-jobs/{jobId}/result	Fetch a completed job’s results (URL or ZIP)
Batch jobs	POST	/api/v1/batch-jobs/{jobId}/cancel	Cancel a batch job, refunding unrendered rows
Batch jobs	DELETE	/api/v1/batch-jobs/{jobId}	Delete a finished batch job and its archive
Share links	GET	/api/v1/shares	List your public share links
Share links	DELETE	/api/v1/shares/{shareId}	Revoke a public share link

Design & authoring

Tag	Method	Path	Purpose
Design reference	GET	/api/v1/design-reference	Index of the design reference knowledge pack
Design reference	GET	/api/v1/design-reference/{topic}	A markdown topic from the design reference
Design reference	GET	/api/v1/design-reference/element-types	Index of element and supporting types
Design reference	GET	/api/v1/design-reference/element-types/{type}	One element or supporting type’s field table
Design reference	GET	/api/v1/design-reference/examples/{name}	One golden example design
Design authoring	POST	/api/v1/designs/validate	Validate a design without saving it (free) — see Authoring Templates
Design authoring	POST	/api/v1/designs/render	Render a charged preview of a design and get its render receipt

Manage content

Tag	Method	Path	Purpose
Templates	GET	/api/v1/templates/{templateId}	Inspect a template and its variable schema; ?include=canvas adds the design
Templates	GET	/api/v1/templates/{templateId}/thumbnail	Stream the template’s stored thumbnail — see Templates & Schema Discovery
Templates	POST	/api/v1/templates	Create a template from a previewed design, or copy a built-in one with fromLibrary
Templates	PATCH	/api/v1/templates/{templateId}	Update a template’s metadata or design
Templates	DELETE	/api/v1/templates/{templateId}	Delete a template
Template versions	GET	/api/v1/templates/{templateId}/versions	List a template’s retained versions — see Version history
Template versions	GET	/api/v1/templates/{templateId}/versions/{version}	Get one version; ?include=canvas adds its design
Template versions	GET	/api/v1/templates/{templateId}/versions/{version}/thumbnail	Stream a version’s stored thumbnail
Template versions	POST	/api/v1/templates/{templateId}/versions/{version}/restore	Restore a version as the template’s current design
Projects	GET	/api/v1/projects	List your projects
Projects	GET	/api/v1/projects/{projectId}	Get one project
Projects	GET	/api/v1/projects/{projectId}/templates	List templates in a project
Projects	POST	/api/v1/projects	Create a project
Images	GET	/api/v1/images	List the organization’s image library
Images	POST	/api/v1/images	Upload an image (multipart file, or JSON url)
Images	GET	/api/v1/images/{id}	Get one image
Images	DELETE	/api/v1/images/{id}	Delete an image
Images	GET	/api/v1/images/{id}/preview	Stream an image’s preview

Account

Tag	Method	Path	Purpose
Account	GET	/api/v1/account	Get the organization, plan, quota and scopes for the presenting credential

The document’s servers block is set to https://app.zandovi.com, and every operation declares two security schemes: apiKey (the X-Api-Key header) and bearerAuth (an OAuth Authorization: Bearer token). Either one satisfies the request, so imported requests are pre-wired with the right base URL and auth.

Import into Postman

1. Open Postman → Import (top-left), then drag in zandovi-openapi.yaml (or File → Choose Files).
2. Before confirming, open the import settings: set Folder organization to Tags to get one folder per tag above, and Request parameter generation to Example so request bodies are filled from the spec’s examples rather than from placeholder values.
3. Postman creates a Zandovi API collection with every endpoint and example request, and detects the X-Api-Key auth from the spec.
4. Open the collection → Variables (or its Authorization tab) and set your API key once — every request inherits it.
5. Create your key first in Settings → API Keys — see Authentication.

Ready to send

Because the spec ships with https://app.zandovi.com as the server and X-Api-Key as the security scheme, imported requests only need your key filled in before you hit Send. Every request body comes with a named example that passes validation as it is: the generate endpoint, for instance, offers binary, link and print. Replace the ids in the path and body (templateId, projectId), any renderReceipt, and the variable names with your own; those are the only values the examples cannot know.

Import into Insomnia or generate a client

• Insomnia: Create → Import From File → pick the YAML. Same result.

• Client generation: feed the file to any OpenAPI 3.1 tool, e.g.

  # TypeScript types
  npx openapi-typescript zandovi-openapi.yaml -o zandovi.d.ts
  
  # A full client with openapi-generator
  openapi-generator generate -i zandovi-openapi.yaml -g python -o ./zandovi-client

What’s not in the spec

Admin, billing, and internal endpoints are intentionally excluded — the document contains only the public API described in these docs, including the batch-jobs and authoring endpoints listed above.

Completion callbacks are only half-visible here, by nature: the callbackUrl request field and the completionCallback response object are in the spec, but the delivery we POST to your endpoint isn’t — it’s a request you receive, not one you make, so no operation describes it. Its payload and signature are documented on the callbacks page.

Staying current

The spec is regenerated from the API itself, so the download tracks the live https://app.zandovi.com/api/v1 behavior. Pin against the info.version field inside the file if you need to detect changes.