Skip to main content
PATCH
Update a workflow

Authorizations

Authorization
string
header
required

Your secret key as a bearer token, e.g. Authorization: Bearer sk_live_…. Secret keys are server-side only.

Path Parameters

id
string
required

The workflow id.

Query Parameters

dryRun
boolean
default:false

Validate and check references without saving: the response shows the record as it would be saved.

Body

application/json

A workflow is the fulfilment pipeline for a product: what happens to a customer's upload from the moment it is dropped on the product page until the print-ready file reaches the shop. Intake runs first, while the customer waits: it points at an upload rule (which file kinds, how many files or slots, and per kind the preflight profile that checks them and whether a failing file is rejected). When the trigger fires (order placed, upload accepted, proof approved or a manual run), each accepted file runs the stream for its kind (autofix, convert an image to PDF, optimize with a preset, split pages); then merge can combine the files, and delivery sends the result to the account's destinations. Proofing optionally shows the customer a soft proof at the end of intake, and can hold the job until they approve it. Rules, preflight profiles, optimize presets, destinations and scenes are separate records referenced by id; product mappings and the embedded upload widget point at a workflow by its id. A job copies the workflow when it is created; jobs that already hold files keep the version they started with. A minimal create body is { "title", "intake": { "ruleId" } } plus one stream per file kind the rule accepts; without streams files are delivered as they left intake.

intake
object
required

The upload stage. Runs for every uploaded file as soon as it arrives, whatever the trigger: checks the file against the upload rule and its preflight profile, and makes the soft proof when proofing is enabled.

schemaVersion
enum<integer>
default:1

Version of this record format. Always 1; can be left out.

Available options:
1
title
string

Name shown in the dashboard, usually the product it serves (for example "Business cards 85 × 55 mm"). The dashboard's title editor takes up to 40 characters and will not save a workflow without one.

Minimum string length: 1
description
string
default:""

Internal note shown under the title in the dashboard. Customers never see it.

tags
string[]

Free-form labels for organising workflows (the spec importer adds "imported" and the product type). No effect on processing.

trigger
enum<string>
default:order_placed

When processing after intake (streams, then merge and delivery) starts for a job whose files have passed intake. Until it fires, nothing after intake runs. "order_placed" (default): when the customer checks out in a connected cart and the order is linked to the job; the customer can still replace files until then, so use it on product pages. "on_accept": immediately, once the job holds enough accepted files for the rule's minimum file count; files are locked from then on. "proof_approval": when the customer approves the soft proof in the upload widget; needs proofing.enabled true. "manual": only when someone runs the job from the dashboard. Any job can also be run manually from the dashboard whatever its trigger.

Available options:
order_placed,
on_accept,
proof_approval,
manual
streams
object[]

Per-file processing that runs after the trigger fires, one stream per file kind. After intake every accepted file is routed by kind: PDFs, and vector or office files the rule converts to PDF, go to the "pdf" stream; images go to the "raster" stream; anything else goes to "other". Add a stream for each kind the upload rule accepts, at most one per kind. A file whose kind has no stream is not processed and is delivered as it left intake. Named slots (Front, Back, …) do not get streams of their own: every file of a kind runs the same steps. Default [] (no processing).

Maximum array length: 3
merge
object

What happens to the job's files once every file has finished its stream. Runs once per job; a merged file replaces the individual files in delivery and in the job's deliverables (downloads, GET /jobs/{id}).

finalize
array

Reserved for steps after merge (imposition, export). None are implemented, so it must be empty.

proofing
object
required if trigger = proof_approval

Soft proof: a colour-managed preview of each uploaded file, drawn on the print sheet with bleed and cut marks and showing the fixes autofix will make, shown to the customer in the upload widget at the end of intake. With trigger "proof_approval" the job waits until the customer approves it; with any other trigger it is for information only.

optionSet
object

Customer-facing option fields (paper, sides, quantity and so on) meant to be shown next to the upload. Reserved: nothing reads it yet; the upload widget does not show it and jobs ignore it. Leave it disabled; product options belong in the store.

delivery
object

Where the finished print files go when a job completes successfully (after streams and merge). Every destination receives the job's final files: the merged PDF or ZIP when merge made one, otherwise each file as its stream left it (the original upload when no step changed it). Jobs that end in error are not delivered.

ui
object

Display settings for the dashboard and the upload widget. Free-form: unknown keys are kept as they are.

Response

OK

workflow
Workflow · object

A workflow is the fulfilment pipeline for a product: what happens to a customer's upload from the moment it is dropped on the product page until the print-ready file reaches the shop. Intake runs first, while the customer waits: it points at an upload rule (which file kinds, how many files or slots, and per kind the preflight profile that checks them and whether a failing file is rejected). When the trigger fires (order placed, upload accepted, proof approved or a manual run), each accepted file runs the stream for its kind (autofix, convert an image to PDF, optimize with a preset, split pages); then merge can combine the files, and delivery sends the result to the account's destinations. Proofing optionally shows the customer a soft proof at the end of intake, and can hold the job until they approve it. Rules, preflight profiles, optimize presets, destinations and scenes are separate records referenced by id; product mappings and the embedded upload widget point at a workflow by its id. A job copies the workflow when it is created; jobs that already hold files keep the version they started with. A minimal create body is { "title", "intake": { "ruleId" } } plus one stream per file kind the rule accepts; without streams files are delivered as they left intake.

dryRun
boolean

Present and true when nothing was saved.