Screening API

The screening API does what the Screening pages do: it creates a job from a PDF, from a PDF in Files or from the sheets of an imposition layout, changes its screens and output, screens it into 1-bit TIFFs and reads back the plates and the report. It also manages the team's profiles, platesetters, presses and plate curves. Every endpoint is under your team, at /a/<team_slug>/screening/api/v1/.

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).

Job ids are UUIDs; profile, device and curve ids are numbers. An object of another team is a 404. Deleting a profile, a device or a curve needs a team administrator (403 for other members).

Screen a PDF from start to finish#

JOBS=https://app.example.com/a/acme/screening/api/v1/jobs/
AUTH="Authorization: Api-Key $API_KEY"
JOB=00000000-0000-0000-0000-000000000000   # the id the first call returns

# 1. Upload pages 1-2 of a PDF with profile 42 (multipart; 201 with the new job, preflighted and configuring)
curl -s -X POST "$JOBS" -H "$AUTH" -F source=upload -F file=@postcard-a.pdf -F pages=1-2 -F profile=42

# 2. Change the resolution and the Black screen (the answer has the checks again, in "guardrails")
curl -s -X PATCH "$JOBS$JOB/" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"settings": {"dpi": 2540, "separations": [{"name": "Black", "screen": {"lpi": 175, "angle": 45}}]}}'

# 3. Screen it (202), then poll until the status is done, failed or cancelled
curl -s -X POST "$JOBS$JOB/start/" -H "$AUTH"
curl -s "$JOBS$JOB/" -H "$AUTH"

# 4. Read the report of the done job
curl -s "$JOBS$JOB/report/" -H "$AUTH"

Jobs#

A new job is made in one call: the app copies the pages, runs the preflight and gives each separation the screen its profile says, so the answer (201) is a job in configuring, ready to check and start. The call takes as long as the preflight, up to a few minutes for a large file.

• An uploaded PDF: send multipart/form-data with source=upload and file, and optionally pages, profile and name. See Sources: PDFs, Files and imposition sheets. Once the preflight passes, the PDF is also saved in the team's Screening folder in Files, and the job keeps that version. A full Files storage answers 507 and creates nothing.
• A PDF in Files: send JSON with source: "file" and file_version, the id of a version from the Files API, and optionally pages, profile and name. The job keeps that exact version; a newer version never changes it. A version of another team, or one still being processed, is a 404; a file that isn't a PDF is a 422. See Sources: PDFs, Files and imposition sheets.
• Imposition sheets: send JSON with source: "imposition", imposition_job and layout_ref, and optionally sheets. The app builds the imposed PDF of those sheets, as the imposition export does, and screens that. See Sources: PDFs, Files and imposition sheets.

{"source": "file", "file_version": 42, "pages": "1-2"}

{"source": "imposition", "imposition_job": 42, "layout_ref": "l-42", "sheets": [0, 1]}

The imposition jobs to choose from, and the layouts of one, are listed by:

The first lists the team's 100 most recently changed imposition jobs (id, name, run_type, updated_at). The second lists a job's saved layouts and the layouts of its last run, each with its ref, name, sheets, run_type, size_in, method, press_sheets and yield_pct, plus roll and fresh. A roll layout can't be screened, and a layout that isn't fresh is refused with 409 until the imposition job runs again.

The list takes ?status= (one status), ?imposition_job= (an id) and ?limit= (1 to 200, 50 by default), and answers {"count": …, "results": […]}, newest first. Each job in a list has the first group of fields below; a job read alone, and the answer of every call that changes a job, has them all.

What each status means is in Running a screening job. The addresses in urls are the job's pages and files in the app. source_file tells where the PDF is in Files:

{"version_id": 42, "file_id": 42, "path": "Customers / Postcard A.pdf", "version": 2, "url": "/a/acme/files/f/42/"}

The path and version are recorded when the job is made. Once the job expires it lets go of the version, and version_id, file_id and url become null.

Deleting a job deletes its plates and files (204). A job that is rendering or finishing must be cancelled first (409).

Change a job's settings#

While a job is configuring, PATCH takes a new name and settings changes; send only what changes. Every other status answers 409.

A screen takes any of kind (am, fm or solid), lpi (50 to 300, and at most dpi ÷ 4), angle (degrees, counter-clockwise on the right-reading sheet), dot (round, euclidean, ellipse, square, line or diamond) and fm_dot_um (5 to 100). curve is a curve id, or null for the profile's chain. role is spot, solid or technical; a technical ink is never output, so it can't be included (see Screens per separation).

The answer is the job with its checks run again. A setting the app refuses is a 400 that names each one:

{"detail": "Some settings are not valid.", "settings": {"separations.Black.lpi": "Enter a value from 50 to 300."}}

Screen, cancel and re-screen#

• start/ checks the job once more, freezes its settings and curve versions and queues it (202). A job with errors answers 409 with "detail": "Fix the errors before screening." and the errors in guardrails.
• cancel/ stops a queued, rendering or finishing job (202); its partial plates are deleted.
• edit/ takes a failed or cancelled job back to configuring (202), so you can change it and start it again.
• retry/ queues a job again from the start when worker_stale is true (202).
• rescreen/ makes a new job in configuring from a done, failed or cancelled job's pages and settings (201, the new job, whose rescreen_of is the first one's id). See Running a screening job.

Each answers with the job (the new one for rescreen/), or 409 with the reason when the job's status doesn't allow it, such as "Only a queued or running job can be cancelled." Poll the job while it runs: progress has the stage and the percentage, and queue_position the jobs ahead.

Plates, report and analyser#

Once a job is done, reading it alone lists its plates: one per page and separation output. Each plate has:

The report of a done job, the same record as the report.json in its ZIP, with the format automateprint.screening-report/1: the job, source, pages, engine, settings, every plate file with its checksum, and the warnings. See Downloads and the screening report. Before the job is done it is a 404.

What the plate viewer loads: the pages with their size in device pixels, zoom levels and plates (screen, coverage, ink zones), and a tile_url template. Before the job is done it describes the 50 dpi preview, with "state": "preview".

The screen analyser for one plate of a done job: page, plate (the plate's slug) and an area x, y, w, h in device pixels of the right-reading plate, at least 64 × 64. The answer has screen (am, fm, or flat for paper or a solid), coverage in %, and for an AM screen the measured lpi and angle. A job that isn't done yet is a 409.

Profiles and devices#

A profile is the setup a job starts from. The list answers {"results": […]}; each profile has its id, is_default, url (its page in the app) and the fields below.

The easiest start is a built-in profile: profiles/presets/ lists them with their full settings, and profiles/from-preset/ with {"preset": "offset_150_euclidean", "name": "Press 150"} makes a team profile from one (201). It becomes the default of its press type when the type has none; set-default/ makes another profile the default. Listing the profiles creates the "Offset 150 · Euclidean" default when the team has no Offset sheetfed default.

settings is the document the presets show: process (a screen for each of Cyan, Magenta, Yellow and Black), spot (the screen of other spot inks, with angle_from, the process colours whose angles spots take in turn), named ({ink name: screen}), technical_inks and solid_inks (lists of names, up to 60), extent, output, marks and trap. Screens and the other keys take the values of a job's settings. Errors name the key, such as {"settings": {"process.Cyan.lpi": "Enter a value from 50 to 300."}}. A curve or device slot takes an id of the team of the right kind: "This is not the right kind for this slot." otherwise.

Devices#

A platesetter's settings are resolutions (a list of dpi), default_resolution, technology (thermal, violet, uv, flexo_lams or film), compression, name_template, negative, mirror and blank_plates (skip by default). A press's are process (a press type), registration_tolerance_mm (0 to 1), ink_zones (1 to 128), trap_policy and require_traps. What each one does is in Screening profiles and devices.

Plate curves#

A plate curve keeps every version it ever had. A curve read alone lists them in versions; the list shows only current_version. Each version has its id, number, data, measured_with, hashes (the checksum of each entry), note, created_at and created_by.

A POST or PATCH with data (or preset) adds a version; changing only the name or notes doesn't. data holds separations, one entry per separation name (Default covers the others), and spot_mapping ({spot name: entry name}). An entry has a mode:

• linear: no change;
• points: points, 2 to 33 [in %, out %] pairs, or the same as in,out lines of text;
• compensation: measured (input and output lists, units percent, fraction or density) and a target from curves/presets/ (see Press compensation from measurements).

Any entry can have limits: keep_zero_below, min_dot, min_dot_mode (hold or cutoff), bump_range, max_dot, cutback_range and keep_solid (see Plate curves). binding takes resolution_dpi (a list), screen_family (am, fm, solid), lpi ([lowest, highest]), dot_shapes and polarity (see Plate curves).

restore/ takes {"version": <a version's id>} and makes it current again, as a new version. preview/ computes an entry without saving: send {"spec": {…}} for samples ([file %, plate %] pairs from 0 to 100), the sha256 of the curve and, for a compensation, the aim. import/ reads measurements (text up to 256 KB of CSV, TSV or CGATS, units auto by default, and an optional target) into compensation entries, with warnings and errors, without saving them: put them in data to save.

Errors#

Job errors answer {"detail": "…"}, with the field when one is at fault, such as {"detail": "Choose at most 50 pages.", "pages": ["Choose at most 50 pages."]}. Other limits are on Screening limits.