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 Canvas (Optional)​

For a browser integration, include the Editor or Canvas from the CDN and register the lifecycle events:

<div id="typograph" style="position:absolute; inset:0;"></div>
<script type="module" src="https://cdn.typograph.nl/editor/latest/editor.js"></script>
<script>
  document.addEventListener('typograph_editor_ready', () => {
    const doc = window.typograph.get_typograph_document();
    doc.set_templates_callback(() => /* return JSON array of template URLs */);
    doc.set_save_template_callback(({ name, data }) => {
      // Persist `data` (serialized template JSON) to your backend.
    });
  });
</script>

See Editor Integration for the full callback surface, and Canvas Integration for the read-only renderer.

Next Steps​