Preflight API

The preflight API runs the same checks as the Preflight page. Queue a report for an approval artwork version, an imposition artwork or a version of a file in Files, poll it until it finishes, and read its findings. Every endpoint is under your team, at /a/<team_slug>/preflight/api/reports/.

Every call takes the same authentication as the rest of the API: an API key of a team member, or a signed-in session that also sends its CSRF token when it changes data (see authentication).

What the checks look for and what the results mean is in How preflight works.

Run preflight and read the result#

REPORTS=https://app.example.com/a/acme/preflight/api/reports/
AUTH="Authorization: Api-Key $API_KEY"

# 1. Queue a report for approval version 42 with the Packaging preset (202; the answer has its id, here 7)
curl -s -X POST "$REPORTS" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"version": 42, "profile": "preset:packaging"}'

# 2. Poll it every few seconds until the status is no longer "running"
curl -s "${REPORTS}7/" -H "$AUTH"

# 3. Or ask for the newest report of the version
curl -s "${REPORTS}latest/?version=42" -H "$AUTH"

Queue a report#

The body names one target and optionally a profile:

Give exactly one of version, imposition_artwork and file_version. The answer is 202 Accepted with the report, status running. When the same check of the same target is already waiting to start, you get that report instead of a new one. A target or profile of another team is 404.

New approval versions, and new PDF versions in Files, are preflighted without a call: see on upload and when a PDF arrives in Files. A file in Files shows the result of its current version's latest report as its preflight_status.

Read a report#

Poll until status is no longer running: then it is pass, warn, fail or error. A report that waits more than an hour to start, or runs more than 15 minutes, becomes error on its own.

{
  "id": 7,
  "status": "warn",
  "counts": {"error": 0, "warning": 1, "info": 0},
  "findings": [
    {
      "id": "f1",
      "check": "image_resolution",
      "severity": "warning",
      "code": "image_low_ppi",
      "message": "Image prints at 250 ppi (2000 × 1500 px); at least 300 ppi is needed.",
      "params": {"pixels": "2000 × 1500", "ppi": 250, "limit": 300, "count": 1},
      "page": 1,
      "bbox": [18.0, 72.0, 594.0, 504.0],
      "bboxes": [[18.0, 72.0, 594.0, 504.0]],
      "count": 1,
      "fixup": null
    }
  ],
  "target": "Postcard A v2",
  "artwork_version": 42,
  "imposition_artwork": null,
  "file_version": null,
  "file_name": "postcard-a.pdf",
  "profile": null,
  "profile_label": "Packaging and folding carton",
  "duration_ms": 2140,
  "error": "",
  "url": "/a/acme/preflight/reports/7/"
}

(Some fields are left out of the example.)

Findings#

Locations are in points on the page as stored in the PDF: before its rotation, with the origin at the top left of the visible page (the CropBox) and y growing downwards. Each entry of pages gives the page's width and height, its rotation, the rotated size as displayed (view) and the matrix [a, b, c, d, e, f] that maps a location onto it, with the trim, bleed and media boxes in the same coordinates.

Finding codes#

Values in braces come from params.

The latest report#

Pass version, imposition_artwork or file_version. The answer is the newest report of that target, running or not, or 404 ("No preflight report yet.").

Apply a fix#

POST /a/acme/preflight/api/reports/7/fixups/set_boxes/ applies a fix the report offers (a fixup of one of its findings) to the file of an approval version or a version in Files. The fixed file becomes the artwork's next version, or the file's next version in Files (source preflight_fix), and is queued for preflight with the same profile. The answer is 201 with:

Fixes of imposition artwork are downloads, offered on the report page only: the API answers 400. A fix that can't run answers 400 with the reason, such as a fix the report doesn't offer, a newer version of the artwork or file, a file in the Files trash, or a file that changed since the report. See Preflight fixes.

Errors and limits#

A report that could not check its file has status error and says why in error; see when a report can't run.