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)

File Service endpoints require a user token with file, file:read, file:write, or file:delete as appropriate, except the reads an integration needs, which also accept a client token: Token Types lists them.

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}/download-urlGETfile / file:readShort-lived link to read the file — open to an app key
/v1/file/templates/{id}/{fileType}/presigned-urlPOSTfile:writePresigned upload URL — fileType is file or thumbnail

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, invitations, roles) lives under /v1/file/templates/{templateId}/comments/... and /v1/file/template/{templateId}/invitations — see the File Service page.

Wiring Templates Into the Editor​

The Editor loads templates through the templates host provider. The editor asks your page for the available templates; you fetch those from your backend (which in turn talks to the File Service) and return them.

new Editor({
  container: '#app',
  host: {
    templates: async () => {
      // Your backend resolves the current user's templates via
      // GET /v1/file/projects/{projectId}/templates and returns them.
      const response = await fetch('/api/list-templates');
      return response.json(); // [{ name, url }, …]
    },
    // Plus documents and clips — same pattern.
  },
  legacy_php_fallback: false,
});

See Editor → Host Providers for the full provider set.

Template Variables / Data Binding​

A template's data fields are its named text frames and images, and the {{key}} placeholders inside its text: the merge fields that GET /v1/file/templates/{id}/fields lists. The Publisher fills them from a CSV, one output per row.

Server-side merge via CSV​

Submit the template plus a CSV file whose header names the fields. 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 → What the CSV holds for the header and its rules, and 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 { "violations": [...], "has_violations": false }: has_violations is false when the template is valid. A template's download-url gives the bundle the editor saved, which /validate takes as it is. See Document Service.