Skip to main content

Templates

Templates are the reusable design files in Typograph — created in the Editor, stored in the File Service, rendered by the Publisher. This page covers the API surface around them; see Concepts → Documents for the underlying JSON schema.

Lifecycle​

[Editor creates]
      ↓
POST /v1/file/projects/{projectId}/templates   ← persist (project-scoped)
      ↓
PATCH /v1/file/templates/{id}                  ← autosave changes
      ↓
POST /v1/document/validate                     ← pre-flight validation
      ↓
POST /v1/publisher/jobs                        ← render to PDF / image
      ↓
GET  /v1/publisher/jobs/{id}/files             ← download output (or wait for webhook)

All File Service endpoints require a user token with file, file:read, file:write, or file:delete as appropriate. See Token Types.

Template Endpoints​

The authoritative list is in File Service → Templates. In short:

EndpointMethodScopesPurpose
/v1/file/projects/{projectId}/templatesGETfile:readList templates in a project
/v1/file/projects/{projectId}/templatesPOSTfile:writeCreate a template in a project
/v1/file/templates/{id}GETfile:readRead a template by ID
/v1/file/templates/{id}PATCHfile:writeUpdate
/v1/file/templates/{id}/touchPATCHfile:writeBump modified timestamp (recency)
/v1/file/templates/{id}/{fileType}/presigned-urlPOSTfile:writePresigned upload URL — fileType is thumbnail or document

Templates are created and listed under their owning project, then addressed by their own UUID. Deleting a template happens through the user's trash flow, not a direct DELETE. Collaboration (comments, replies, resolve, invites, roles) lives under /v1/file/templates/{templateId}/comments/... and /v1/file/template/{templateId}/invites — see the File Service page.

Wiring Templates Into the Editor​

The Editor loads templates via callbacks you register. The editor asks your page for a list of available template URLs; you fetch those from your backend (which in turn talks to the File Service) and return them.

document.addEventListener('typograph_editor_ready', () => {
  const typograph_document = window.typograph.get_typograph_document();

  typograph_document.set_templates_callback(() => {
    // Your backend resolves the current user's templates via
    // GET /v1/file/projects/{projectId}/templates and returns URLs.
    const xhr = new XMLHttpRequest();
    xhr.open('POST', '/api/list-templates', false);
    xhr.send();
    return xhr.response; // JSON array of { url } objects
  });

  // Plus set_documents_callback and set_clips_callback — same pattern.
});

See Editor → Backend Glue for the full callback set.

Template Variables / Data Binding​

Rich-text elements can carry inline Tag-style placeholders. They get resolved at render time in the Publisher — either from the request itself or from a CSV the publisher processes row-by-row. The exact placeholder syntax is driven by the template author at design time.

Server-side merge via CSV​

Submit the template plus a CSV file to the Publisher. The Publisher produces one output per CSV row (as child jobs of the parent):

curl -X POST https://api.typograph.nl/v1/publisher/jobs \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "template": { "url": "https://example.com/template.json" },
      "manifest": { "url": "https://example.com/manifest.json" },
      "csv":      { "url": "https://example.com/rows.csv" }
    },
    "output": {
      "upload": { "url": "https://example.com/upload-target" },
      "config": { "type": "pdf" }
    }
  }'

See Publisher for the full job schema including watermark, DPI, page ranges, and crop marks.

Validating Before Render​

Always validate before submitting a publisher job — the publisher rejects malformed templates with a failed job status (and charges rate-limit either way).

curl -X POST https://api.typograph.nl/v1/document/validate \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_url": "https://example.com/template.json",
    "version": "1.0.0"
  }'

The response is the violations array — empty means valid. See Document Service.