Booklets API

The booklets API does what the Booklets pages do: send a book's PDF, choose how it folds, binds and prints, read the plan and get the press forms back as a PDF with bindery marks. Every endpoint is under your team, starting with /a/{team_slug}/imposition-layout/booklets/api/v1/jobs/, 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).

All lengths are in millimetres. An object of another team is a 404.

A booklet in one call#

impose/ takes the PDF and the settings and answers with the press forms. Nothing is stored.

curl -s -X POST https://app.example.com/a/acme/imposition-layout/booklets/api/v1/impose/ \
  -H "Authorization: Api-Key $API_KEY" \
  -F file=@menu-11x17.pdf \
  -F 'settings={"binding": "perfect_bound", "scheme": "F16-7", "head": 5, "sheet_w": 1020, "sheet_h": 720}' \
  -o press-forms.pdf

Jobs#

A job keeps the PDF (in Files, in the Booklets folder) and the settings, so you can plan, change and download it again. Create one with multipart file (or JSON with file_version, a PDF version from the Files API), an optional name, settings (an object, or a JSON string in multipart) and optional press, folder and guillotine ids from Equipment. The answer has the page count and each page's trim size.

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

# 1. Upload the PDF with a few settings
curl -s -X POST "$JOBS" -H "$AUTH" -F file=@menu-11x17.pdf -F 'settings={"binding": "saddle_stitch"}'

# 2. Try other settings without saving them, then save them
curl -s -X POST "$JOBS$JOB/plan/" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"settings": {"binding": "saddle_stitch", "lip": 10, "creep_direction": "both"}}'
curl -s -X PATCH "$JOBS$JOB/" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"settings": {"binding": "saddle_stitch", "lip": 10, "creep_direction": "both"}}'

# 3. Download the press forms (add ?marks=0 to leave the marks out)
curl -s -o press-forms.pdf "$JOBS$JOB/press-forms/" -H "$AUTH"

The PDF can be up to 200 MB, for a job or for impose/; a larger one answers 413. A file that isn't a readable PDF answers 422 and isn't kept in Files. The jobs list is paged.

PATCH replaces the whole settings object when you send one; fields you leave out go back to their defaults.

Plans#

A plan is the whole imposition as JSON:

• signatures: per signature its scheme, pages, section and depth (nesting), the book_pages it carries, its flat sheet as grid.front / grid.back (page, rotation, book page and source PDF page per cell) and creep per leaf (mm toward the spine).
• forms: per press form its work_style, ups, copies_per_sheet and sides; each side lists its pages (book and source page, trim and clip rectangles in sheet millimetres with y up from the gripper edge, rotation, shift), folds and marks.
• reading: the book in reading order (added marks blanks the plan added); cover for a separate cover; summary (pages, signatures, forms, plates, blanks, thickness, creep); splits (other splits worth considering: sizes in book order, blanks, signatures; send sizes as signature_sizes to use one); warnings (code, severity, message).

A plan that can't be made (say, signature_sizes that hold fewer pages than the book) answers 422 with detail. POST plan/ on a job lays settings over the saved ones; with "replace": true it uses them instead. POST plan/ without a job plans from settings alone: give page_count, trim_w and trim_h.

PDF and thumbnails#

Output: PDF, zip or JDF#

The output the job's settings ask for: output_format (pdf or jdf), output_layout (all, form or side) and output_name, the file name template (see Booklet output: PDF and JDF for the values it can use). One PDF comes as application/pdf; a PDF per form or per side, and the JDF package, as a zip. The file name is in Content-Disposition. A JDF package holds one folder with <name>.jdf, <name>_pages.pdf (the book in reading order) and <name>_marks.pdf (one page per form side); see Booklet output: PDF and JDF.

# A JDF package named by the production preset, without saving the settings
curl -s -X POST "$JOBS$JOB/output/" -H "$AUTH" -H "Content-Type: application/json" -o booklet.zip \
  -d '{"settings": {"output_format": "jdf", "output_name": "{{ booklet.trim }}_{{ booklet.pages }}pg"}}'

Marks#

Besides its bindery marks (the marks settings), a job prints mark sets from the marks library: its press's defaults, sets added on the job, and the job's own sets (its own marks, presets added to it, and customized copies of library sets). See The booklet marks editor.

sets lists every set on the job with its doc (a mark-set document, lengths in pt from the sheet's bottom-left corner), its sources (press, booklet for a booklet rule, job, local), enabled, local and own (the job's own sets), replaces (the library set a customized copy stands in for) and part (a rule's forms: any, text or cover). Each mark's place.on says where it prints: containers counts the text forms (all, first, last, odd, even, every:N or "1-3,7"), sides is front, back or both, and mirror_on_back mirrors its position left to right on the back. PATCH sets added (library set ids) and disabled (sets left off this job). The answer also gives the press, its press_defaults, the job's binding (key, label), the team's booklet_rules ({set id: {bindings, part}}) and the sets among them for this binding (binding_defaults), the library sets and the presets (booklet: true for the booklet presets).

Preview JSON of one form side (form: its index, -1 for the cover's form), as the marks designer draws it. Pass settings and docs ({set id: document}) to preview what isn't saved yet.

Without set, the marks go into the job's own marks (made on first use). With a set of the job's own, they replace its marks. With a library set, scope: "job" keeps them for this job only (a customized copy) and scope: "set" saves them as the set's next version; a customized copy with scope: "set" goes back into its library set.

A new library set from doc, used on the job instead of replaces (one of the job's own sets is deleted; a library set comes off the job, or is left off it when it is a press default). press_default applies it on the job's press.

binding-default/ adds the job's binding to the set's booklet rule (on: false takes it out; a rule left with no binding is deleted).

Recommendations#

The wizard's suggestions: the booklet planned on each press given (every active press when presses is empty; only the sheet in settings with "custom_sheet": true) with each usual scheme that fits the press and the folder, ranked, at most four. Each option has the settings that make it (apply them with PATCH), a summary, its work_styles, reasons and warnings.

The separate cover#

A separate cover has its own press form in the plan: cover.form, in the same shape as forms (with cover: true, its press and stock), set by the cover_* settings and the job's cover_press. See Press sheets and bindery marks.

Saves the cover spread to Files and adds it to an Imposition job as a front-and-back item: a new job, or the one in imposition_job, for quantity covers. The response gives the Imposition job, its url, the artwork and the file_version.

Scheme catalog and templates#

A scheme has its id, pages, grid (cols, rows), folds (edge, travel in cells, to) and page layout (front, back: rows top first of [page, rotation]; the back as seen turned left to right). Retrieving one also gives states, the packet before every fold, which the fold preview draws. ?binding_edge=right or top gives the layout for that binding edge.

A template is folded by its folds, or numbered by hand with mode: "pages" and cells ({"front": [[{"page": 4, "rotation": 0}, …]], "back": …}). Use it with "scheme": "custom:<id>".

Upload a JDF, XJDF or JDF MIME package as file (multipart). Each signature in it becomes a template with source: "jdf", its source_name, the catalog schemes it matches and the settings the file states (sheet, trim size, trims, lip, work style, binding, signature split). Send the marks PDF the JDF refers to as marks, or upload it to the template later (below); until then the response's marks_needed names it. A template's marks lists the sheet sides, the placeholder separations and their colors, which the marks PATCH maps to inks. The response lists the templates, the settings and notes on anything skipped. A file with nothing usable, or with values that can't be read (such as a page count or fold travel that isn't a number), answers 422. See Signature schemes and pagination.

Settings#

Every field is optional. A field you leave out takes its default; spine, lip, assembly, blank_policy, small_signature and creep_mode follow the binding (see Bindings, trims and creep).