Converter Service

The Converter service transforms files between different formats. It supports InDesign and POD (Print on Demand) package conversion, font format conversion, and image processing.

Base URL: /v1/converter/

Scopes: converter (full), converter:read, converter:write

Token type: any — converter endpoints accept either a user token or a client token. See Token Types.

Endpoints

Method	Path	Scopes	Description
`GET`	`/v1/converter/jobs`	`converter` / `converter:read`	List conversion jobs
`POST`	`/v1/converter/jobs`	`converter` / `converter:write`	Create a conversion job
`GET`	`/v1/converter/jobs/{path}`	`converter` / `converter:read`	Job detail and output files
`GET`	`/health/converter`	—	Service health (public, unauthenticated)

The single-item endpoint uses a catch-all {path} — concrete sub-paths handled by the converter service include /v1/converter/jobs/{id} (job details) and /v1/converter/jobs/{id}/files (download converted files, see File Types below).

Supported Conversions

Package Conversion

Input	Output	Description
`indesign_package`	`typograph_package`	Convert an InDesign package (zipped Collect-for-Output bundle) to Typograph format
`pod_package`	`typograph_package`	Convert a POD (Print on Demand) package to Typograph format

Font Conversion

Input Types	Output Types
`eot`, `otf`, `ttf`, `woff`, `woff2`	`ttf`, `otf`, `woff`, `woff2`

Image Conversion

Input Types	Output Types
`bmp`, `ai`, `eps`, `gif`, `psd`, `jpg`, `jpeg`, `png`, `svg`, `webp`, `tiff`	`jpg`, `png`, `webp`, `svg`

Package Formats

Package conversions exchange ZIP archives. The exact archive layout matters — the converter validates and rejects anything it can't parse. The structures below describe what to send in (input.source.url) and what to expect back (uploaded to output.upload.url).

`indesign_package` (input)

A standard Adobe InDesign Collect for Output bundle, zipped. The archive may contain a single wrapper folder or place the bundle contents at the root — both are accepted (the converter ignores __MACOSX and .DS_Store entries).

indesign_package.zip
└── <bundle-folder>/                  (optional wrapper — may be omitted)
    ├── <document>.idml               required — the InDesign document
    ├── Links/                        required if the document references images
    │   ├── photo-01.jpg
    │   └── logo.ai
    └── Document fonts/               required if the document references fonts
        ├── MyFont-Regular.otf
        └── MyFont-Bold.otf

Linked images and embedded fonts are converted as part of the job — see the typograph_package output below for what comes back.

`pod_package` (input)

A ZIP containing the MY VIVENDA POD template JSON. The converter scans the archive, skips macOS metadata (__MACOSX/, ._*), and uses the first .json file it finds.

pod_package.zip
└── <any-name>.json                   POD template — single template object OR array of templates

The JSON itself follows the POD template schema. Multiple templates in one array become multiple pages in the resulting Typograph document.

`typograph_package` (output)

The converted bundle. Contents differ slightly between InDesign and POD sources:

typograph_package.zip                 (from indesign_package conversion)
├── templatebundle.json               { "version": "1.0.0", "template": {...}, "manifest": {...} }
├── images/                           browser-ready variants of all linked images
│   ├── photo-01.webp
│   └── logo.png
└── fonts/                            TTF versions of all embedded fonts
    ├── MyFont-Regular.ttf
    └── MyFont-Bold.ttf

typograph_package.zip                 (from pod_package conversion)
└── templatebundle.json               { "version": "1.0.0", "template": {...}, "manifest": {...} }

The templatebundle.json carries both the template (pages, elements, styles, swatches, fontData) and the manifest (referenced images and fonts) as top-level fields. See the Documents concept page for the full schema.

Feeding the output into Publisher

The Publisher Service does not accept typograph_package.zip directly — it expects separate URLs for template.json and manifest.json. Unzip the package, host templatebundle.template and templatebundle.manifest as two JSON files, and point input.template.url / input.manifest.url at them. Images and fonts in images/ and fonts/ are referenced by URL inside the template, so they need to stay reachable from the Publisher worker.

Create a Conversion Job

Request Structure

Property	Type	Required	Description
`tag`	string	No	Optional tag to identify or group jobs (max 255 chars)
`input`	object	Yes	Input file specification
`input.type`	string	Yes	Input file format
`input.source`	object	Yes	Source file URL and optional headers
`input.source.url`	string	Yes	URL to download input file
`input.source.headers`	object	No	HTTP headers for downloading (max 5)
`output`	object	Yes	Output specification
`output.type`	string	Yes	Output file format
`output.upload`	object	Yes	Target for converted files
`output.upload.url`	string	Yes	URL to upload converted files
`output.upload.headers`	object	No	HTTP headers for uploading (max 5)
`output.config`	object	No	Configuration for image conversions

Convert an InDesign Package

Convert an InDesign package to Typograph format:

curl -X POST https://api.typograph.nl/v1/converter/jobs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "design-project-alpha",
    "input": {
      "type": "indesign_package",
      "source": {
        "url": "https://example.com/packages/design.zip"
      }
    },
    "output": {
      "type": "typograph_package",
      "upload": {
        "url": "https://example.com/webhook/upload"
      }
    }
  }'

Response

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "tag": "design-project-alpha",
  "status": "queued",
  "input": {
    "type": "indesign_package",
    "source": {
      "url": "https://example.com/packages/design.zip"
    }
  },
  "output": {
    "type": "typograph_package",
    "upload": {
      "url": "https://example.com/webhook/upload"
    }
  },
  "created_at": "<ISO 8601 timestamp>"
}

Convert a POD Package

Convert a POD (Print on Demand) package — a zipped archive of POD-schema documents — to Typograph format:

curl -X POST https://api.typograph.nl/v1/converter/jobs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "pod-import-batch-001",
    "input": {
      "type": "pod_package",
      "source": {
        "url": "https://example.com/pod/template.zip"
      }
    },
    "output": {
      "type": "typograph_package",
      "upload": {
        "url": "https://example.com/webhook/upload"
      }
    }
  }'

The response shape is the same as for InDesign packages — only input.type differs. POD packages always convert to typograph_package; pairing pod_package with any other output type is rejected with a validation error.

Convert Fonts

Convert a TTF font to WOFF2 for web use:

curl -X POST https://api.typograph.nl/v1/converter/jobs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "font-conversion-001",
    "input": {
      "type": "ttf",
      "source": {
        "url": "https://example.com/fonts/myfont.ttf"
      }
    },
    "output": {
      "type": "woff2",
      "upload": {
        "url": "https://example.com/webhook/upload"
      }
    }
  }'

Convert and Resize Images

Convert images with optional resizing and optimization:

curl -X POST https://api.typograph.nl/v1/converter/jobs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "image-optimization",
    "input": {
      "type": "png",
      "source": {
        "url": "https://example.com/images/photo.png"
      }
    },
    "output": {
      "type": "webp",
      "upload": {
        "url": "https://example.com/webhook/upload"
      },
      "config": {
        "width": 1200,
        "height": 800,
        "quality": 85,
        "fit": "max",
        "strip": true
      }
    }
  }'

Image Configuration

Property	Type	Description
`width`	integer	Target width in pixels (1-10000)
`height`	integer	Target height in pixels (1-10000)
`quality`	integer	Output quality (1-100, default: 90)
`fit`	string	Sizing method (see below)
`strip`	boolean	Remove metadata from output

Fit Options

Value	Description
`max`	Scale to fit within dimensions, maintaining aspect ratio
`min`	Scale to fill dimensions, maintaining aspect ratio
`exact`	Stretch to exact dimensions
`crop`	Crop to exact dimensions from center

Download Converted Files

Download the output once conversion is complete:

curl "https://api.typograph.nl/v1/converter/jobs/{id}/files?file_type=output" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o converted-file.zip

File Types

Type	Description
`output`	Converted file (default)
`input`	Original source file

Upload Request Format

When a job completes successfully, Typograph sends the converted file as a single HTTP PUT request to output.upload.url. Your upload target must accept this request shape:

Property	Value
Method	`PUT`
URL	Exactly the URL you provided in `output.upload.url` (redirects are not followed)
`Content-Type`	Detected from the file — e.g. `font/woff2`, `image/webp`, `image/png`, `application/zip` for package conversions
`User-Agent`	`Typograph/Util-Upload`
Custom headers	Merged from `output.upload.headers` (can't override `Content-Type` or `User-Agent`)
Body	Raw file bytes, streamed (no multipart / form-data wrapper)
Connection timeout	10 seconds
Transfer timeout	300 seconds

Your endpoint must respond with an HTTP status in the 200–299 range — anything else fails the job.

Uploading Directly to Cloud Storage

You can point output.upload.url straight at a presigned URL from S3, GCS, Azure Blob, Cloudflare R2, etc. Each provider accepts signed PUT requests with a raw body; set output.upload.headers to whatever the signer expects. Make sure the presigned URL is signed against the content type Typograph will send (see the list above) — protected headers (Content-Type, User-Agent) cannot be overridden.

Custom Headers

Include authentication headers for protected resources:

{
  "tag": "protected-conversion",
  "input": {
    "type": "png",
    "source": {
      "url": "https://storage.example.com/private/image.png",
      "headers": {
        "Authorization": "Bearer storage-token"
      }
    }
  },
  "output": {
    "type": "webp",
    "upload": {
      "url": "https://webhook.example.com/uploads",
      "headers": {
        "X-API-Key": "webhook-api-key"
      }
    }
  }
}

Examples

PSD to PNG Thumbnail

curl -X POST https://api.typograph.nl/v1/converter/jobs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "psd-thumbnail",
    "input": {
      "type": "psd",
      "source": {
        "url": "https://example.com/designs/layout.psd"
      }
    },
    "output": {
      "type": "png",
      "upload": {
        "url": "https://example.com/webhook/upload"
      },
      "config": {
        "width": 400,
        "fit": "max"
      }
    }
  }'

AI to SVG Conversion

curl -X POST https://api.typograph.nl/v1/converter/jobs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "logo-conversion",
    "input": {
      "type": "ai",
      "source": {
        "url": "https://example.com/logos/company-logo.ai"
      }
    },
    "output": {
      "type": "svg",
      "upload": {
        "url": "https://example.com/webhook/upload"
      }
    }
  }'

Batch Font Conversion

Convert multiple fonts by creating separate jobs:

for font in regular bold italic; do
  curl -X POST https://api.typograph.nl/v1/converter/jobs \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"tag\": \"font-${font}\",
      \"input\": {
        \"type\": \"otf\",
        \"source\": {
          \"url\": \"https://example.com/fonts/myfont-${font}.otf\"
        }
      },
      \"output\": {
        \"type\": \"woff2\",
        \"upload\": {
          \"url\": \"https://example.com/webhook/upload\"
        }
      }
    }"
done

Complete Example with Headers

Convert an image from protected storage with custom headers:

curl -X POST https://api.typograph.nl/v1/converter/jobs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "premium-image-conversion",
    "input": {
      "type": "tiff",
      "source": {
        "url": "https://storage.example.com/originals/photo.tiff",
        "headers": {
          "Authorization": "Bearer storage-token"
        }
      }
    },
    "output": {
      "type": "webp",
      "upload": {
        "url": "https://cdn.example.com/upload",
        "headers": {
          "X-Upload-Token": "upload-secret-key"
        }
      },
      "config": {
        "width": 1920,
        "height": 1080,
        "quality": 90,
        "fit": "max",
        "strip": true
      }
    }
  }'

Endpoints​

Supported Conversions​

Package Conversion​

Font Conversion​

Image Conversion​

Package Formats​

indesign_package (input)​

pod_package (input)​

typograph_package (output)​

Create a Conversion Job​

Request Structure​

Convert an InDesign Package​

Response​

Convert a POD Package​

Convert Fonts​

Convert and Resize Images​

Image Configuration​

Fit Options​

Download Converted Files​

File Types​

Upload Request Format​

Uploading Directly to Cloud Storage​

Custom Headers​

Examples​

PSD to PNG Thumbnail​

AI to SVG Conversion​

Batch Font Conversion​

Complete Example with Headers​