Skip to main content

Quick Start

This walkthrough takes you from "I have a client_id/client_secret" to a successful API call in a few minutes. It uses the Client Credentials flow, which is appropriate for server-to-server work. If you're building a user-facing app, use Authorization Code with PKCE instead.

1. Obtain an Access Token​

curl -X POST https://api.typograph.nl/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$TYPOGRAPH_CLIENT_ID" \
  -d "client_secret=$TYPOGRAPH_CLIENT_SECRET" \
  -d "scope=document publisher converter webhook"

Response:

{
  "access_token": "typ_abc123...",
  "token_type": "Bearer",
  "expires_in": 172800,
  "scope": "document publisher converter webhook"
}

Access tokens are valid for 2 days. Cache them rather than minting a new one per request.

2. Call an Endpoint That Accepts Client Tokens​

Validate a document payload — requires the document or document:read scope, accepts a client token:

curl -X POST https://api.typograph.nl/v1/document/validate \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @template.json

Or create a publisher job to generate a PDF. The publisher downloads your template from the input.template.url you provide and, once rendered, POSTs the result to output.upload.url:

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/my-template.json" },
      "manifest": { "url": "https://example.com/my-manifest.json" }
    },
    "output": {
      "upload": { "url": "https://example.com/upload-target" },
      "config": { "type": "pdf" }
    }
  }'

Publisher and converter endpoints return a job with a queued status. See Asynchronous Processing.

3. Track the Job​

You have two options:

  • Poll GET /v1/publisher/jobs/{id} until status is completed or failed.
  • Subscribe to a webhook (recommended) — see Webhooks. The service delivers publication.completed / publication.failed (and conversion.completed / conversion.failed for converter jobs) to your configured URL.

Once the job is completed, fetch the generated file directly from the jobs endpoint:

curl "https://api.typograph.nl/v1/publisher/jobs/{id}/files?file_type=output" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -L

The file_type query parameter accepts output, template, manifest, or csv.

Generated files are available for 4 days after job completion, then return 410 Gone.

4. Embed the Editor or Viewer (Optional)​

For a browser integration, include the Editor or Viewer from the CDN and pass it the host providers your backend supports:

<script src="https://cdn.typograph.nl/editor/latest/scripts/jsColorEngineWeb.js"></script>
<div id="app" style="position:absolute; inset:0;"></div>
<script type="module">
  import { Editor } from 'https://cdn.typograph.nl/editor/latest/editor.js';

  new Editor({
    container: '#app',
    host: {
      // Return [{ name, url }, …] — the templates the user can start from.
      templates: () => fetch('/api/templates').then(r => r.json()),
      // Persist `data` (serialized template JSON) to your backend.
      save_template: (name, data) => fetch('/api/templates', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ name, data }),
      }),
    },
    legacy_php_fallback: false,
  });
</script>

See Editor Integration for every provider, and Viewer Integration for the read-only template-filling UI.

Next Steps​