Marks API

The marks API manages your mark sets and applies them to imposition jobs. Every endpoint is under your team, starting with /a/{team_slug}/marks/api/v1/mark-sets/, and takes the same authentication as the rest of the API: an API key of a team member, or a signed-in session (see API overview). Lengths are in points (1/72 in). What marks are and how they place is on How print marks work.

Order data that marks print (order numbers, PO, your own fields, per-copy rows) is written on the imposition API: see Imposition API.

A job's marks from start to finish#

SETS=https://app.example.com/a/acme/marks/api/v1/mark-sets/
JOB=https://app.example.com/a/acme/marks/api/v1/jobs/42/marks/
AUTH="Authorization: Api-Key $API_KEY"

# 1. Make a mark set from a preset (the answer has its id, here 7)
curl -s -X POST "$SETS" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "Slug line", "preset": "slug_line"}'

# 2. Add it to imposition job 42
curl -s -X PUT "$JOB" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"added": [{"set": 7, "pin": null}]}'

# 3. Check the marks on the job's layout before exporting
curl -s "${JOB}check/" -H "$AUTH"

Mark sets and presets#

A set is a document of marks (doc): {"schema": 1, "name": …, "units": "mm", "requires": {"profile": null}, "marks": [...]}. Create a set from {name, doc} or from {name, preset}. Lengths in a doc you send may be unit strings ("8mm", "0.25in"); reads return points. Validation errors name the JSON path, such as {"doc": {"marks[0].place.anchor": ["…"]}}. Each change saves a version (versions/, versions/{number}/restore/); jobs can pin one. A set in use can't be deleted: archive it. export/ and import/ move a set between teams as JSON, with assets referenced by key.

Previews and templates#

preview/ places a set (set or an unsaved doc) on a sample sheet, roll or 1-up, or on a job's layout ({"job": 42, "layout": "c-…", "sheet": 0}), and returns every placed mark with its box, text, code and problems. variables/ lists every field a template can use, with samples. validate/ checks a template; render/ fills one.

A job's marks#

jobs/{id}/marks/ returns the sets that apply (effective, each with its sources: team, cutter, printer or job), and what the job changed: added ([{set, pin}]), disabled (inherited sets turned off), artwork_disabled ({"<artwork id>": [set ids]}), settings (stretch, reflective) and dismissed_suggestions. PUT replaces the fields you send; settings merge.

resolved/ places the marks on a layout (layout = a c-… or l-… ref; default the selected or best layout) for one sheet, or every sheet in pages of 20. check/ returns the problems of every sheet grouped by code, with counts and examples, without drawing. Both answer 409 while the job has no layout. customize/ and reset/ make and drop a job-only copy of a set; exports/ lists what each export contained.

artworks/{id}/marks/ lists the item-mark sets of one artwork with their toggles; PUT {"disabled": [...]} turns sets off on that item.

Cutters, printers and defaults#

A cutter's registration is a preset (see registration-presets/) plus your overrides. A printer's mark profile holds its nonprintable edges ({lead, trail, left, right}) and white spot. defaults/ adds a set as the team default or a cutter's or printer's default (target: team, cutter or printer; new_jobs_only).

Fields, assets and settings#

Fields declare order-data keys (scope job, item or copy; key, label, type, sample, required); fields/discovered/ lists keys your system sent that aren't declared. variables/ also lists your team's file properties as fields with scope file (file.<key>, with their labels): items whose file is in Files print them (see Order data in marks).

Assets are images, PDFs or fonts (20 MB each) that image and text marks use by key. An asset's content is a version in Files: file_version (its id; null for an asset uploaded before assets moved to Files), file_id, file_path and file_version_number say which. An image asset's preview_url is assets/{id}/content/, which redirects to the image through a download link made for that request, so a page left open keeps showing it (the link it redirects to is short-lived: don't store it). An upload to assets/ is stored in Files, in your team's Marks folder, and counts toward storage (507 with code quota_exceeded when storage is full). assets/from-files/ makes an asset from a version you already have ({"version_id": 42}; key and name default to the file's name), without copying it; assets/ takes a version_id in place of the file too, with your own key and name. PATCH assets/{id}/ with a file upload or a version_id replaces the content and keeps the key. Deleting an asset leaves its file in Files; a version an asset uses can't be deleted from Files.

Team settings hold the display_unit, the team's marks spot colour (marks_spot) and gate_downgrades: problem codes team admins allow to export as warnings.

Production keys#

keys/{key}/ resolves a sheet code (see Cutter registration and job codes) to its job, layout, sheet and cut file name. The short link /m/{key}/ opens it in the app for team members.

Every operation#