Print File Handling
Print File Handling — API Reference for External Integrators
Overview
Purple DAM supports print-ready file variants (PSD, TIFF, AI, EPS, INDD) alongside standard web images, and additionally keeps the full-resolution original of standard web images (JPEG, PNG, GIF, WebP) that exceed the online downscaling threshold. Editors can upload these files directly or attach them to existing online images. Only PSD and TIFF files are automatically converted into a web-friendly image (WebP, with JPEG fallback) for use in online articles; other print formats (AI, EPS, INDD) cannot be converted and use a placeholder as the online image instead. Standard web images need no conversion at all: the downscaled copy goes online and the original upload becomes the print variant. In all cases, the original file is preserved and exposed via the REST API as a separate variant.
This document describes the resulting API field and how a client (e.g. an InDesign plugin) should consume it.
This entire feature is behind a feature toggle. It only exists on a given Hub if explicitly enabled for that Hub; where it is not enabled, the API and media behavior are unchanged from today, and the print_image field will not appear at all.
Background: Print formats such as PSD/TIFF were previously classified with generic MIME types (e.g. application/octet-stream) and treated as media_type: "file" rather than images, making them undiscoverable through image-specific queries. The new print_image field solves this by exposing print files with their correct, format-specific MIME type (e.g. image/vnd.adobe.photoshop) through the standard image endpoint — no separate endpoint or MIME-type workaround required.
Endpoint
No new endpoint is introduced. The print variant is exposed as an additional field on the standard WordPress media endpoint:
Example:
curl https://example.com/wp-json/wp/v2/media/41API Field: print_image
Every image object returned by the REST API now includes a print_image object in addition to the existing online file data (WebP/PNG/JPEG, etc.). The field is only populated when print image handling is enabled on the DAM side (Settings → Purple DAM → Filters → Enable Print Images). If the feature is disabled, media responses are unchanged from today's behavior.
Field | Type | Description |
|---|---|---|
exists | boolean | Whether a print variant is attached to this image. |
id | integer | ID of the print file. Present only when exists is true. |
url | string | Download URL of the original print file. Present only when exists is true. |
mime_type | string | Correct MIME type of the print file, e.g. image/vnd.adobe.photoshop. Present only when exists is true. |
filename | string | Original filename of the print file. Present only when exists is true. |
filesize | integer | File size in bytes. Present only when exists is true. |
Example: image with a print variant
"print_image": {
"exists": true,
"id": 46,
"url": "http://example.com/uploads/datei.psd",
"mime_type": "image/vnd.adobe.photoshop",
"filename": "datei.psd",
"filesize": 1926287
}Example: image without a print variant
"print_image": {
"exists": false
}Required Client Behavior
When placing an image, the client should:
- Check whether print_image.exists is true.
- If true, download and place the file at print_image.url, using print_image.mime_type to handle the format correctly.
- If false, fall back to the standard online image file as before — no change in behavior needed.
No changes to the existing online-image workflow are required beyond this check.
Supported Print Formats
Currently: PSD, TIFF, AI, EPS, INDD — each returned with its correct native MIME type (e.g. image/vnd.adobe.photoshop for PSD).
Standard web image formats (JPEG, PNG, GIF, WebP) also get print-file handling. When such an image is uploaded above the resolution threshold used for online downscaling (default 2560px), a downscaled version is created for online use, and the original high-resolution upload becomes its print_image — the same mechanism already used for PSD/TIFF. In that case print_image.mime_type is a standard image type (e.g. image/jpeg) rather than a print-specific one, so clients must not infer the format from a fixed list of print extensions: always read print_image.mime_type.
Manually attached image print versions: an image format can also be attached as a print variant by hand. Such a print version is not required to exceed the resolution threshold, and it may show something other than the online image it is attached to.
Upload Path (for reference)
Print files can reach the DAM in three ways:
- Attached to an existing web image via the Media Library (recommended workflow).
- Uploaded directly (e.g. a print file sent from InDesign via a plugin). For PSD and TIFF, the DAM automatically converts the file to a web image (WebP, JPEG fallback, max. 1920 px on the longest side, 85% quality — less if the Hub's resolution limit is set below 1920 px) and attaches the original as its print_image. If conversion fails, the upload fails with an explicit error rather than producing an empty or broken image — clients should surface that error rather than retry silently. For formats that cannot be converted (AI, EPS, INDD), a placeholder is used as the online image and the original file is attached as print_image.
- Derived automatically from an oversized upload of a standard web image (JPEG, PNG, GIF, WebP). No conversion is involved: the downscaled copy becomes the online image, and the untouched original becomes its print_image.
Upload size limit: up to 100 MB per print file. This ceiling applies to print formats regardless of the per-file-type upload limit configured for the Hub, and is enforced in the media library upload, the print-version upload and the client-side pre-check alike.
Notes
- Automatic conversion to a web image (WebP, max. 1920 px, 85% quality, JPEG fallback) only happens for PSD and TIFF. Other print formats (AI, EPS, INDD) use a placeholder as the online image, since they cannot be converted.
- Print files are never exposed as browser-renderable images, so there is no risk of them being inserted directly into online articles.
- This also holds for a print variant that is itself a JPEG or PNG: print attachments are excluded from media library queries, so they cannot be picked or inserted as an online image.
- The Media Library additionally offers filtering by print-variant status (all / with print variant / without print variant) and visual indicators for images with print variants, though this is editor-facing and not part of the API contract.
- The whole feature is gated behind a toggle per Hub installation, so integrators should always check print_image.exists rather than assuming the field is present.
Status & Outlook
- The print_image field is live in the current Purple DAM plugin and deployed to dev/staging and demo environments for integration testing.
- The underlying implementation is expected to evolve in a future Purple DAM version. The print_image field contract described here is intended to remain stable across that migration, but integrators should expect a follow-up notice if anything changes.
- A planned improvement will keep an image MIME type on the underlying PSD/TIFF asset itself (instead of it flipping to a generic "file" type), so uploaded and transformed assets stay linked as the same object.
- Print-file handling for standard image formats that exceed the online downscaling threshold is live. Where EXIF/IPTC metadata is read from and written to for such an image pair is still being finalised, so integrators should not yet rely on metadata being present on one specific file of the pair.
- Please confirm whether the described print_image check can be implemented on your side, and flag any concerns before general rollout.