> ## Documentation Index
> Fetch the complete documentation index at: https://filecheck.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a workflow

> A JSON Merge Patch (RFC 7396): send only what changes. Objects merge key by key, `null` removes a key, arrays replace the whole list. Patching a catalog workflow saves your own copy under the same id (`customized: true`), which you can undo with revert.



## OpenAPI

````yaml /openapi.json patch /workflows/{id}
openapi: 3.1.0
info:
  title: Filecheck API
  version: 1.1.0
  description: >-
    The Filecheck REST API. Submit files as jobs and fetch results, and set up
    your account: workflows, upload rules, preflight profiles, connectors,
    optimize presets, delivery destinations, product mappings, storefront
    settings and webhooks. All requests are authenticated server-side with your
    secret key (`sk_live_…`).
servers:
  - url: https://api.filecheck.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Jobs
    description: >-
      Submit files for preflight, fixing, optimization, validation and previews,
      and read the results.
  - name: Uploads
    description: Presigned credentials to upload large files directly.
  - name: Orders
    description: Attach jobs to commerce orders.
  - name: Workflows
    description: >-
      What happens to a customer's files for a product: the intake rule that
      checks them on upload, the processing streams, proofing, merging and
      delivery. Products in your store map to a workflow.
  - name: Rules
    description: >-
      Upload rules: which files a product accepts (kinds, MIME types, how many),
      which preflight profile checks each kind, and what happens when a file
      fails. A workflow's intake points at one rule.
  - name: Profiles
    description: >-
      Preflight profiles: the checks run on a file (size, bleed, resolution,
      colour, fonts…) with their thresholds, severities and automatic fixes. PDF
      profiles check PDFs (and vector and office files once converted); raster
      profiles check images.
  - name: Connectors
    description: >-
      Connectors wire a product page to the Element: what the shopper chose
      (size, page count, sides, finishing) adjusts the rule's size checks for
      that upload, and what FileCheck measured in the file (page count, size,
      area) can fill the page's own inputs so the store prices from the real
      file. The cart plugins store the chosen connector per product.
  - name: Optimize presets
    description: >-
      Saved optimize settings (compression, downsampling, colour conversion)
      that optimize steps can use.
  - name: Destinations
    description: >-
      Where finished files are delivered: SFTP and FTP hotfolders, S3 buckets,
      webhooks. Workflows list the destinations they deliver to. Secrets are
      write-only.
  - name: Products
    description: >-
      Which workflow each product in your store uses. The storefront Element
      opens the mapped workflow on the product page.
  - name: Settings
    description: >-
      How the storefront Element appears on your product pages: where it mounts,
      the add-to-cart button it guards, display mode and theme.
  - name: Webhooks
    description: >-
      HTTP callbacks for job, proof, account and billing events, signed with
      X-FileCheck-Signature.
paths:
  /workflows/{id}:
    patch:
      tags:
        - Workflows
      summary: Update a workflow
      description: >-
        A JSON Merge Patch (RFC 7396): send only what changes. Objects merge key
        by key, `null` removes a key, arrays replace the whole list. Patching a
        catalog workflow saves your own copy under the same id (`customized:
        true`), which you can undo with revert.
      operationId: updateWorkflow
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The workflow id.
        - name: dryRun
          in: query
          schema:
            type: boolean
            default: false
          description: >-
            Validate and check references without saving: the response shows the
            record as it would be saved.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Workflow'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  workflow:
                    allOf:
                      - $ref: '#/components/schemas/Workflow'
                      - $ref: '#/components/schemas/RecordFields'
                  dryRun:
                    type: boolean
                    description: Present and true when nothing was saved.
        '400':
          description: >-
            Invalid request: `code` says why, `param` names the field, `details`
            lists every problem
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Conflict: `code` says why (in_use, draft_reference, not_a_draft,
            not_a_catalog_record, cart_not_supported)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Workflow:
      title: Workflow
      description: >-
        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.
      type: object
      additionalProperties: false
      required:
        - intake
      properties:
        schemaVersion:
          type: integer
          enum:
            - 1
          default: 1
          description: Version of this record format. Always 1; can be left out.
        title:
          type: string
          minLength: 1
          description: >-
            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.
        description:
          type: string
          default: ''
          description: >-
            Internal note shown under the title in the dashboard. Customers
            never see it.
        tags:
          type: array
          items:
            type: string
          default: []
          description: >-
            Free-form labels for organising workflows (the spec importer adds
            "imported" and the product type). No effect on processing.
        trigger:
          type: string
          enum:
            - order_placed
            - on_accept
            - proof_approval
            - manual
          default: order_placed
          description: >-
            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.
        intake:
          type: object
          additionalProperties: false
          required:
            - ruleId
          description: >-
            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.
          properties:
            ruleId:
              type: string
              minLength: 1
              description: >-
                Id of the upload rule (GET /rules): the accepted file kinds and
                MIME types, the number of files or named slots, and per kind the
                preflight profile and onFail policy that decides whether a
                failing file is rejected. The upload widget will not load a
                workflow without a rule. The rule's accepted kinds decide which
                streams this workflow needs.
            onError:
              type: string
              enum:
                - halt
              default: halt
              description: >-
                Stored for the dashboard and not read by the pipeline: whether a
                failing file blocks the job is set per kind by the rule's
                onFail. Only "halt" is accepted.
            enabled:
              type: boolean
              enum:
                - true
              default: true
              description: Intake always runs and cannot be switched off. Always true.
        streams:
          type: array
          default: []
          maxItems: 3
          items:
            type: object
            additionalProperties: false
            required:
              - kind
            properties:
              kind:
                type: string
                enum:
                  - pdf
                  - raster
                  - other
                description: >-
                  The file kind this stream processes, after intake: "pdf" for
                  PDF uploads and for vector or office files the rule converts
                  to PDF at intake (accept entry convertToPdf true); "raster"
                  for JPEG, PNG, TIFF and other images; "other" for everything
                  else (archives, fonts, vector or office files kept as they
                  are), which no step can process.
              steps:
                type: array
                default: []
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      enum:
                        - autofix
                        - convert
                        - optimize
                        - split_pages
                      description: >-
                        What the step does. "autofix": applies the fixes the
                        intake preflight planned for this file (the profile
                        checks with severity "autofix": add bleed, convert to
                        CMYK, upscale low-resolution images and so on); it is
                        skipped when intake ran no preflight or found nothing to
                        fix. If the upload rule already autofixes at intake
                        (accept entry autofix on, without repreflight), keep
                        this step disabled or the same fixes are applied a
                        second time. "convert" (raster stream only): places the
                        image on a new PDF page sized by config.dimension.
                        "optimize": runs an optimize preset (config.presetId)
                        over the PDF; on the raster stream it needs an enabled
                        convert step before it, since it works on the converted
                        PDF. "split_pages" (pdf stream only): writes one
                        single-page PDF per page as extra outputs; the file that
                        is delivered and downloaded stays the unsplit PDF.
                    enabled:
                      type: boolean
                      default: true
                      description: >-
                        false keeps the step and its settings in the workflow
                        without running it. The dashboard lists every allowed
                        step for a stream and switches them on and off this way.
                    onError:
                      type: string
                      enum:
                        - halt
                        - continue
                      default: halt
                      description: >-
                        What a crash in this step does. "halt" (default): the
                        file ends in error, which puts the whole job in error,
                        so nothing is merged or delivered. "continue": the
                        failure is recorded as a warning on the file and the job
                        carries on with the file as it was before this step.
                    config:
                      type: object
                      default: {}
                      description: >-
                        Settings for this step type: autofix {}, convert {
                        format, dimension, outputIntent, dpi }, optimize {
                        presetId }, split_pages {}.
                  allOf:
                    - if:
                        type: object
                        required:
                          - type
                        properties:
                          type:
                            const: autofix
                      then:
                        properties:
                          config:
                            type: object
                            additionalProperties: false
                            maxProperties: 0
                            description: >-
                              Autofix takes no settings: it applies exactly the
                              fixes the intake preflight planned for the file,
                              as defined by the checks with severity "autofix"
                              in the preflight profile. Send {}.
                    - if:
                        type: object
                        required:
                          - type
                        properties:
                          type:
                            const: convert
                      then:
                        properties:
                          config:
                            type: object
                            additionalProperties: false
                            default:
                              format: pdf
                            description: How the image becomes a PDF page.
                            properties:
                              format:
                                type: string
                                enum:
                                  - pdf
                                default: pdf
                                description: >-
                                  Target format. Only "pdf" exists; it is what
                                  lets the following optimize step treat the
                                  file as a PDF.
                              dimension:
                                type: object
                                additionalProperties: false
                                required:
                                  - width
                                  - height
                                description: >-
                                  Page the image is placed on, in millimetres.
                                  The image is scaled to fit inside the whole
                                  page (trim plus bleed), keeping its
                                  proportions, centred; if its proportions
                                  differ from the page the rest stays white.
                                  While the step is enabled, the page size (trim
                                  plus bleed) is also the print size used to
                                  judge a raster upload's effective DPI when the
                                  preflight profile sets none, and the sheet the
                                  soft proof is drawn on. Omit dimension to size
                                  the page from the image's pixels at dpi.
                                properties:
                                  width:
                                    type: number
                                    exclusiveMinimum: 0
                                    description: >-
                                      Finished (trim) width of the product in
                                      millimetres, without bleed. Example: 85
                                      for an 85 × 55 mm business card.
                                  height:
                                    type: number
                                    exclusiveMinimum: 0
                                    description: >-
                                      Finished (trim) height of the product in
                                      millimetres, without bleed.
                                  bleed:
                                    type: object
                                    additionalProperties: false
                                    description: >-
                                      Bleed added outside the trim on each side,
                                      in millimetres: the page becomes trim +
                                      bleed and gets an explicit TrimBox
                                      (finished size) and BleedBox. Set it when
                                      customers upload images that already
                                      include bleed. For trim-sized images leave
                                      it out and let an optimize preset with a
                                      bleed group mirror-fill the bleed instead.
                                    properties:
                                      top:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Top side, in millimetres. Missing sides
                                          count as 0.
                                      bottom:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Bottom side, in millimetres. Missing
                                          sides count as 0.
                                      left:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Left side, in millimetres. Missing sides
                                          count as 0.
                                      right:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Right side, in millimetres. Missing
                                          sides count as 0.
                                  crop:
                                    type: object
                                    additionalProperties: false
                                    description: >-
                                      Advanced: CropBox insets in millimetres,
                                      measured inward from the final page edge.
                                      Usually omitted.
                                    properties:
                                      top:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Top side, in millimetres. Missing sides
                                          count as 0.
                                      bottom:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Bottom side, in millimetres. Missing
                                          sides count as 0.
                                      left:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Left side, in millimetres. Missing sides
                                          count as 0.
                                      right:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Right side, in millimetres. Missing
                                          sides count as 0.
                                  trim:
                                    type: object
                                    additionalProperties: false
                                    description: >-
                                      Advanced: TrimBox insets in millimetres,
                                      measured inward from the final page edge;
                                      when any side is set it replaces the
                                      TrimBox derived from bleed. Usually
                                      omitted.
                                    properties:
                                      top:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Top side, in millimetres. Missing sides
                                          count as 0.
                                      bottom:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Bottom side, in millimetres. Missing
                                          sides count as 0.
                                      left:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Left side, in millimetres. Missing sides
                                          count as 0.
                                      right:
                                        type: number
                                        minimum: 0
                                        description: >-
                                          Right side, in millimetres. Missing
                                          sides count as 0.
                                  matchOrientation:
                                    type: boolean
                                    default: true
                                    description: >-
                                      true (default): turn the page to the
                                      image's orientation, so a size set up
                                      portrait also takes landscape images
                                      (bleed and insets turn with it). false:
                                      always use width × height as given.
                              outputIntent:
                                type: string
                                enum:
                                  - cmyk-fogra29.icc
                                  - cmyk-fogra39.icc
                                  - cmyk-fogra51.icc
                                  - cmyk-fogra52.icc
                                  - cmyk-gracol2006.icc
                                  - cmyk-gracol2013.icc
                                  - cmyk-iso-coated-v2-300.icc
                                  - cmyk-iso-coated-v2.icc
                                  - cmyk-japan-coated.icc
                                  - cmyk-japan-uncoated.icc
                                  - cmyk-psr-lwc.icc
                                  - cmyk-psr-snp.icc
                                  - cmyk-swop-v2.icc
                                  - cmyk-swop2013.icc
                                  - gray-sgray.icc
                                  - rgb-adobe-1998.icc
                                  - rgb-display-p3.icc
                                  - rgb-srgb.icc
                                  - cmyk-fogra29
                                  - cmyk-fogra39
                                  - cmyk-fogra51
                                  - cmyk-fogra52
                                  - cmyk-gracol2006
                                  - cmyk-gracol2013
                                  - cmyk-iso-coated-v2-300
                                  - cmyk-iso-coated-v2
                                  - cmyk-japan-coated
                                  - cmyk-japan-uncoated
                                  - cmyk-psr-lwc
                                  - cmyk-psr-snp
                                  - cmyk-swop-v2
                                  - cmyk-swop2013
                                  - gray-sgray
                                  - rgb-adobe-1998
                                  - rgb-display-p3
                                  - rgb-srgb
                                description: >-
                                  ICC profile to embed as the PDF's output
                                  intent, by bundled file name (for example
                                  "cmyk-fogra39.icc" or "cmyk-fogra39"). Short
                                  aliases such as "fogra39" are not resolved by
                                  the conversion. A profile the conversion
                                  cannot load is skipped without failing the
                                  step, so when the intent must be in the file,
                                  set it in the optimize preset's output-intent
                                  group instead. Also used as the colour profile
                                  the soft proof simulates.
                              dpi:
                                type: integer
                                minimum: 1
                                description: >-
                                  Pixels per inch used to size the page from the
                                  image when dimension is not set (page = pixels
                                  ÷ dpi). Default 300. Ignored when dimension is
                                  set.
                    - if:
                        type: object
                        required:
                          - type
                        properties:
                          type:
                            const: optimize
                      then:
                        properties:
                          config:
                            type: object
                            additionalProperties: false
                            description: Which optimize preset to run.
                            properties:
                              presetId:
                                type: string
                                minLength: 1
                                description: >-
                                  Id of the optimize preset to apply (GET
                                  /optimize-presets): image downsampling and
                                  compression, colour conversion, page resize,
                                  bleed, hairlines, output intent and so on, as
                                  configured on the preset. Required whenever
                                  the step is enabled.
                    - if:
                        type: object
                        required:
                          - type
                        properties:
                          type:
                            const: split_pages
                      then:
                        properties:
                          config:
                            type: object
                            additionalProperties: false
                            maxProperties: 0
                            description: Split pages takes no settings. Send {}.
                    - if:
                        allOf:
                          - type: object
                            required:
                              - type
                            properties:
                              type:
                                const: optimize
                          - not:
                              properties:
                                enabled:
                                  const: false
                              required:
                                - enabled
                      then:
                        required:
                          - config
                        properties:
                          config:
                            default: {}
                            required:
                              - presetId
                description: >-
                  Steps run on each file of this kind, in this order, each on
                  the previous step's output. Allowed types, in the order they
                  must appear: pdf: autofix, optimize, split_pages. raster:
                  autofix, convert, optimize. other: none. Each type at most
                  once; leaving types out is fine. An empty list, or one with no
                  enabled step, means files of this kind are delivered as they
                  left intake.
            allOf:
              - if:
                  required:
                    - kind
                  properties:
                    kind:
                      const: pdf
                then:
                  properties:
                    steps:
                      maxItems: 3
                      items:
                        properties:
                          type:
                            enum:
                              - autofix
                              - optimize
                              - split_pages
                      allOf:
                        - if:
                            minItems: 1
                            items:
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: autofix
                          then:
                            items:
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - optimize
                                      - split_pages
                        - if:
                            minItems: 1
                            items:
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: optimize
                          then:
                            items:
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - split_pages
                        - if:
                            minItems: 1
                            items:
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: split_pages
                          then:
                            maxItems: 1
                        - if:
                            minItems: 2
                            items:
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: autofix
                          then:
                            items:
                              - true
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - optimize
                                      - split_pages
                        - if:
                            minItems: 2
                            items:
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: optimize
                          then:
                            items:
                              - true
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - split_pages
                        - if:
                            minItems: 2
                            items:
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: split_pages
                          then:
                            maxItems: 2
                        - if:
                            minItems: 3
                            items:
                              - true
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: autofix
                          then:
                            items:
                              - true
                              - true
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - optimize
                                      - split_pages
                        - if:
                            minItems: 3
                            items:
                              - true
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: optimize
                          then:
                            items:
                              - true
                              - true
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - split_pages
                        - if:
                            minItems: 3
                            items:
                              - true
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: split_pages
                          then:
                            maxItems: 3
              - if:
                  required:
                    - kind
                  properties:
                    kind:
                      const: raster
                then:
                  properties:
                    steps:
                      maxItems: 3
                      items:
                        properties:
                          type:
                            enum:
                              - autofix
                              - convert
                              - optimize
                      allOf:
                        - if:
                            minItems: 1
                            items:
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: autofix
                          then:
                            items:
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - convert
                                      - optimize
                        - if:
                            minItems: 1
                            items:
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: convert
                          then:
                            items:
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - optimize
                        - if:
                            minItems: 1
                            items:
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: optimize
                          then:
                            maxItems: 1
                        - if:
                            minItems: 2
                            items:
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: autofix
                          then:
                            items:
                              - true
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - convert
                                      - optimize
                        - if:
                            minItems: 2
                            items:
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: convert
                          then:
                            items:
                              - true
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - optimize
                        - if:
                            minItems: 2
                            items:
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: optimize
                          then:
                            maxItems: 2
                        - if:
                            minItems: 3
                            items:
                              - true
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: autofix
                          then:
                            items:
                              - true
                              - true
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - convert
                                      - optimize
                        - if:
                            minItems: 3
                            items:
                              - true
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: convert
                          then:
                            items:
                              - true
                              - true
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - optimize
                        - if:
                            minItems: 3
                            items:
                              - true
                              - true
                              - type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: optimize
                          then:
                            maxItems: 3
                        - if:
                            minItems: 1
                            items:
                              - allOf:
                                  - type: object
                                    required:
                                      - type
                                    properties:
                                      type:
                                        const: optimize
                                  - not:
                                      properties:
                                        enabled:
                                          const: false
                                      required:
                                        - enabled
                          then:
                            items:
                              - properties:
                                  type:
                                    enum:
                                      - convert
                        - if:
                            minItems: 2
                            items:
                              - true
                              - allOf:
                                  - type: object
                                    required:
                                      - type
                                    properties:
                                      type:
                                        const: optimize
                                  - not:
                                      properties:
                                        enabled:
                                          const: false
                                      required:
                                        - enabled
                          then:
                            items:
                              - properties:
                                  type:
                                    enum:
                                      - convert
                                  enabled:
                                    enum:
                                      - true
                        - if:
                            minItems: 3
                            items:
                              - true
                              - true
                              - allOf:
                                  - type: object
                                    required:
                                      - type
                                    properties:
                                      type:
                                        const: optimize
                                  - not:
                                      properties:
                                        enabled:
                                          const: false
                                      required:
                                        - enabled
                          then:
                            items:
                              - true
                              - properties:
                                  type:
                                    enum:
                                      - convert
                                  enabled:
                                    enum:
                                      - true
              - if:
                  required:
                    - kind
                  properties:
                    kind:
                      const: other
                then:
                  properties:
                    steps:
                      maxItems: 0
          allOf:
            - if:
                minItems: 1
                items:
                  - required:
                      - kind
                    properties:
                      kind:
                        const: pdf
              then:
                items:
                  - true
                  - properties:
                      kind:
                        enum:
                          - raster
                          - other
                  - properties:
                      kind:
                        enum:
                          - raster
                          - other
            - if:
                minItems: 1
                items:
                  - required:
                      - kind
                    properties:
                      kind:
                        const: raster
              then:
                items:
                  - true
                  - properties:
                      kind:
                        enum:
                          - pdf
                          - other
                  - properties:
                      kind:
                        enum:
                          - pdf
                          - other
            - if:
                minItems: 1
                items:
                  - required:
                      - kind
                    properties:
                      kind:
                        const: other
              then:
                items:
                  - true
                  - properties:
                      kind:
                        enum:
                          - pdf
                          - raster
                  - properties:
                      kind:
                        enum:
                          - pdf
                          - raster
            - if:
                minItems: 2
                items:
                  - true
                  - required:
                      - kind
                    properties:
                      kind:
                        const: pdf
              then:
                items:
                  - true
                  - true
                  - properties:
                      kind:
                        enum:
                          - raster
                          - other
            - if:
                minItems: 2
                items:
                  - true
                  - required:
                      - kind
                    properties:
                      kind:
                        const: raster
              then:
                items:
                  - true
                  - true
                  - properties:
                      kind:
                        enum:
                          - pdf
                          - other
            - if:
                minItems: 2
                items:
                  - true
                  - required:
                      - kind
                    properties:
                      kind:
                        const: other
              then:
                items:
                  - true
                  - true
                  - properties:
                      kind:
                        enum:
                          - pdf
                          - raster
          description: >-
            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).
        merge:
          type: object
          additionalProperties: false
          default:
            mode: none
            config: {}
            onError: halt
            enabled: true
          description: >-
            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}).
          properties:
            mode:
              type: string
              enum:
                - none
                - merge_pdf
                - zip
              default: none
              description: >-
                "none" (default): files stay separate and are delivered one by
                one. "merge_pdf": all of the job's files are concatenated into
                one PDF in the order they were added to the job (slot names such
                as Front/Back do not affect the order); needs at least two
                files, and every file must be a PDF by the end of its stream, so
                the raster stream needs an enabled convert step and there must
                be no "other" stream. A merge that fails stops the job before
                its webhook and delivery. "zip": all files are bundled into one
                ZIP archive.
            config:
              type: object
              default: {}
              description: >-
                Mode settings: none {}, merge_pdf { order }, zip { names, order,
                zipName }.
            onError:
              type: string
              enum:
                - halt
              default: halt
              description: >-
                Stored for the dashboard; a failed merge always stops the job
                before delivery. Only "halt" is accepted.
            enabled:
              type: boolean
              default: true
              description: false skips the merge whatever the mode. Default true.
          allOf:
            - if:
                properties:
                  mode:
                    const: none
              then:
                properties:
                  config:
                    type: object
                    additionalProperties: false
                    maxProperties: 0
            - if:
                required:
                  - mode
                properties:
                  mode:
                    const: merge_pdf
              then:
                properties:
                  config:
                    type: object
                    additionalProperties: false
                    properties:
                      order:
                        type: array
                        items:
                          type: integer
                          minimum: 0
                        uniqueItems: true
                        description: >-
                          Advanced: a permutation of the job's file positions
                          (0-based, in the order the files were added to the
                          job), listing every file exactly once. If a job has a
                          different number of files than the list, the merge
                          fails and the job is never delivered, so only use it
                          when the upload rule fixes the file count (min equals
                          max). Omit to keep the order the files were added.
                        minItems: 2
            - if:
                required:
                  - mode
                properties:
                  mode:
                    const: zip
              then:
                properties:
                  config:
                    type: object
                    additionalProperties: false
                    properties:
                      names:
                        type: array
                        items:
                          type: string
                          minLength: 1
                        description: >-
                          File names to use inside the ZIP, by file position
                          (the order the files were added to the job). Missing
                          entries fall back to the stored file name, which is an
                          internal id; duplicates get _2, _3 suffixes. With
                          order set, names must have one entry per file.
                      order:
                        type: array
                        items:
                          type: integer
                          minimum: 0
                        uniqueItems: true
                        description: >-
                          Advanced: a permutation of the job's file positions
                          (0-based, in the order the files were added to the
                          job), listing every file exactly once. If a job has a
                          different number of files than the list, the merge
                          fails and the job is never delivered, so only use it
                          when the upload rule fixes the file count (min equals
                          max). Omit to keep the order the files were added.
                      zipName:
                        type: string
                        minLength: 1
                        description: >-
                          Name for the archive itself (".zip" is added when it
                          has no extension). Delivered files are named after the
                          product or job, so this mostly shows in storage.
        finalize:
          type: array
          maxItems: 0
          default: []
          description: >-
            Reserved for steps after merge (imposition, export). None are
            implemented, so it must be empty.
        proofing:
          type: object
          additionalProperties: false
          default:
            enabled: false
            type: basic
            timing: after_intake
            requireApproval: true
            config: {}
            previewer:
              kind: pages
          description: >-
            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.
          properties:
            id:
              type: string
              description: >-
                Opaque id the dashboard stamps on this block. Optional; no
                effect.
            enabled:
              type: boolean
              default: false
              description: >-
                Make a proof of every file at the end of intake. Default false.
                Must be true when trigger is "proof_approval".
            type:
              type: string
              enum:
                - basic
              default: basic
              description: Proof style. Only "basic" (rendered page previews) exists.
            timing:
              type: string
              enum:
                - after_intake
              default: after_intake
              description: >-
                When the proof is made. Only "after_intake" is implemented:
                after the file passes intake, before the trigger fires. Later
                points (after streams, after merge) are reserved and would
                produce no proof.
            requireApproval:
              type: boolean
              default: true
              description: >-
                Informational only: whether the job waits for the customer's
                approval is decided by trigger "proof_approval", not by this
                flag.
            previewer:
              type: object
              additionalProperties: false
              required:
                - kind
              default:
                kind: pages
              description: >-
                What the customer approves on: the flat pages, or the proofed
                pages shown on a product scene.
              properties:
                kind:
                  type: string
                  enum:
                    - pages
                    - scene
                  default: pages
                  description: >-
                    "pages" (default): flat page previews. "scene": the proofed
                    pages shown on the 3D model, folded leaflet or booklet named
                    by sceneId.
                sceneId:
                  type: string
                  minLength: 1
                  description: >-
                    Id of a scene from the scene library (the account's own or
                    the built-in catalog): a 3D model, fold or flipbook the
                    proofed pages are wrapped onto. Required when kind is
                    "scene"; not allowed with "pages".
              allOf:
                - if:
                    required:
                      - kind
                    properties:
                      kind:
                        const: scene
                  then:
                    required:
                      - sceneId
                - if:
                    properties:
                      kind:
                        const: pages
                  then:
                    properties:
                      sceneId: false
            config:
              type: object
              additionalProperties: false
              default: {}
              description: >-
                Advanced overrides for the proof render. Normally empty: the
                sheet, bleed and colour profile are inferred from the stream's
                optimize preset (pdf) or convert dimension (raster), falling
                back to the intake preflight profile.
              properties:
                iccProfile:
                  type: string
                  enum:
                    - fogra51
                    - fogra52
                    - gracol2013
                    - swop2013
                    - fogra39
                    - iso-coated-v2
                    - iso-coated-v2-300
                    - gracol2006
                    - swop
                    - fogra29
                    - japan-coated
                    - japan-uncoated
                    - psr-lwc
                    - psr-snp
                    - srgb
                    - adobe-rgb
                    - display-p3
                    - greyscale
                    - cmyk-fogra29.icc
                    - cmyk-fogra39.icc
                    - cmyk-fogra51.icc
                    - cmyk-fogra52.icc
                    - cmyk-gracol2006.icc
                    - cmyk-gracol2013.icc
                    - cmyk-iso-coated-v2-300.icc
                    - cmyk-iso-coated-v2.icc
                    - cmyk-japan-coated.icc
                    - cmyk-japan-uncoated.icc
                    - cmyk-psr-lwc.icc
                    - cmyk-psr-snp.icc
                    - cmyk-swop-v2.icc
                    - cmyk-swop2013.icc
                    - gray-sgray.icc
                    - rgb-adobe-1998.icc
                    - rgb-display-p3.icc
                    - rgb-srgb.icc
                    - cmyk-fogra29
                    - cmyk-fogra39
                    - cmyk-fogra51
                    - cmyk-fogra52
                    - cmyk-gracol2006
                    - cmyk-gracol2013
                    - cmyk-iso-coated-v2-300
                    - cmyk-iso-coated-v2
                    - cmyk-japan-coated
                    - cmyk-japan-uncoated
                    - cmyk-psr-lwc
                    - cmyk-psr-snp
                    - cmyk-swop-v2
                    - cmyk-swop2013
                    - gray-sgray
                    - rgb-adobe-1998
                    - rgb-display-p3
                    - rgb-srgb
                  description: >-
                    Printing condition the proof simulates, replacing the
                    inferred one: an alias such as "fogra39", "fogra51",
                    "gracol2013", "swop2013", "srgb" or "greyscale", or a
                    bundled ICC file name.
                format:
                  type: string
                  enum:
                    - webp
                    - jpeg
                    - png
                  description: Image format of the proof pages. Default "webp".
                quality:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: >-
                    Compression quality of the proof images, 1 to 100. Default
                    91.
                maxEdge:
                  type: integer
                  minimum: 1
                  description: Longest side of a proof image in pixels. Default 1200.
                sheet:
                  type: object
                  additionalProperties: false
                  required:
                    - size
                  description: >-
                    Advanced: the print sheet each proof page is drawn on,
                    replacing the inferred one (from the optimize preset's page
                    size and bleed on the pdf stream, the convert dimension on
                    the raster stream, else the preflight profile's page size
                    and bleed). Omit unless the inference is wrong.
                  properties:
                    size:
                      type: object
                      additionalProperties: false
                      required:
                        - width
                        - height
                      description: Finished (trim) size of the sheet.
                      properties:
                        width:
                          type: number
                          exclusiveMinimum: 0
                          description: Trim width in millimetres.
                        height:
                          type: number
                          exclusiveMinimum: 0
                          description: Trim height in millimetres.
                        unit:
                          type: string
                          enum:
                            - mm
                          default: mm
                          description: Always millimetres.
                    sizes:
                      type: array
                      minItems: 1
                      items:
                        type: object
                        additionalProperties: false
                        required:
                          - width_mm
                          - height_mm
                        properties:
                          width_mm:
                            type: number
                            exclusiveMinimum: 0
                            description: Trim width in millimetres.
                          height_mm:
                            type: number
                            exclusiveMinimum: 0
                            description: Trim height in millimetres.
                      description: >-
                        For products sold in several sizes: each page is proofed
                        on the listed size nearest to it instead of on size.
                    bleed:
                      type: number
                      minimum: 0
                      description: Bleed shown around the trim, in millimetres. Default 0.
                    safeZone:
                      type: number
                      minimum: 0
                      description: >-
                        Safety margin drawn inside the trim, in millimetres.
                        Default 0.
                    fitTo:
                      type: string
                      enum:
                        - trim
                        - media
                      description: >-
                        Fit the artwork to the trim (default) or to the full
                        sheet including bleed.
                    fit:
                      type: string
                      enum:
                        - contain
                        - cover
                      description: >-
                        "contain" (default) shows the whole artwork inside the
                        trim; "cover" fills the trim and crops the overflow.
                    dpi:
                      type: integer
                      minimum: 1
                      description: >-
                        Render resolution of the sheet in pixels per inch.
                        Default 150; targetEdge wins when both are set.
                    targetEdge:
                      type: integer
                      minimum: 1
                      description: >-
                        Longest side of the rendered sheet in pixels, bleed
                        included. Inferred sheets use 1200.
                    cutMarks:
                      type: boolean
                      description: >-
                        Draw corner cut marks and the dashed trim line. Default
                        true.
                    watermark:
                      type: boolean
                      description: >-
                        Overlay a "proof" watermark band. Default false for a
                        sheet given here (inferred sheets ask for one); it can
                        also be switched off platform-wide.
                    background:
                      type: string
                      pattern: ^#[0-9A-Fa-f]{6}$
                      description: 'Sheet background colour as #rrggbb. Default #ffffff.'
                    matchOrientation:
                      type: boolean
                      description: >-
                        Turn the sheet to the artwork's orientation. Default
                        true.
            tags:
              type: array
              items:
                type: string
              default: []
              description: Free-form labels. No effect.
        optionSet:
          type: object
          additionalProperties: false
          default:
            enabled: false
            title: ''
            description: ''
            fields: []
            config: {}
          description: >-
            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.
          properties:
            id:
              type: string
              description: >-
                Opaque id the dashboard stamps on this block. Optional; no
                effect.
            enabled:
              type: boolean
              default: false
              description: Has no effect yet. Default false.
            title:
              type: string
              default: ''
              description: Heading above the fields.
            description:
              type: string
              default: ''
              description: Text under the heading.
            fields:
              type: array
              default: []
              items:
                type: object
                additionalProperties: false
                required:
                  - key
                  - type
                properties:
                  key:
                    type: string
                    minLength: 1
                    description: >-
                      Stable identifier, unique within the option set; dependsOn
                      refers to it.
                  type:
                    type: string
                    enum:
                      - select
                      - radio
                      - swatch
                      - sides
                      - binding
                      - grommet
                      - toggle
                      - number
                      - text
                      - note
                    description: >-
                      Widget: select (dropdown), radio, swatch, sides, binding,
                      grommet, toggle, number, text, or note (read-only text).
                  label:
                    type: string
                    description: Label shown to the customer.
                  help:
                    type: string
                    description: Helper text under the field.
                  required:
                    type: boolean
                    description: The customer must answer it.
                  default:
                    description: Pre-selected value.
                  choices:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      required:
                        - value
                      properties:
                        value:
                          type:
                            - string
                            - number
                            - boolean
                          description: Value recorded when the customer picks this choice.
                        label:
                          type: string
                          description: Text shown for the choice. Defaults to the value.
                        swatch:
                          type:
                            - string
                            - 'null'
                          description: Colour or material swatch for swatch fields.
                        thumb:
                          type:
                            - string
                            - 'null'
                          description: Thumbnail image URL.
                        priceHint:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Cosmetic price note such as "+€2.00"; never used to
                            price anything.
                        config:
                          type: object
                          description: Free-form widget settings for this choice; any keys.
                    description: >-
                      Choices for select, radio, swatch, sides, binding and
                      grommet fields.
                  min:
                    type:
                      - number
                      - 'null'
                    description: Smallest value for number fields.
                  max:
                    type:
                      - number
                      - 'null'
                    description: Largest value for number fields.
                  step:
                    type:
                      - number
                      - 'null'
                    description: Increment for number fields.
                  unit:
                    type: string
                    description: >-
                      Unit label shown next to the value, such as "copies" or
                      "mm".
                  dependsOn:
                    type:
                      - object
                      - 'null'
                    additionalProperties: false
                    required:
                      - key
                    properties:
                      key:
                        type: string
                        minLength: 1
                        description: Key of the field this one depends on.
                      in:
                        type: array
                        description: Values of that field for which this one is shown.
                    description: >-
                      Show this field only when another field has one of the
                      listed values.
                  source:
                    type:
                      - string
                      - 'null'
                    enum:
                      - page_count
                      - color_count
                      - width
                      - height
                      - color_space
                      - null
                    description: >-
                      Fill the value from the uploaded file instead of asking:
                      page_count, color_count, width, height or color_space.
                  preflightLink:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Preflight concern this option relates to, such as "bleed"
                      or "even_pages".
                  config:
                    type: object
                    description: Free-form widget settings for this field; any keys.
              description: The option fields, in display order.
            config:
              type: object
              default: {}
              description: Free-form layout settings; any keys.
            tags:
              type: array
              items:
                type: string
              default: []
              description: Free-form labels. No effect.
        delivery:
          type: object
          additionalProperties: false
          default:
            enabled: false
            destinationIds: []
          description: >-
            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.
          properties:
            enabled:
              type: boolean
              default: true
              description: >-
                true (default when delivery is sent): deliver to every listed
                destination. false: keep the list but deliver nothing.
            destinationIds:
              type: array
              default: []
              uniqueItems: true
              items:
                type: string
                minLength: 1
              description: >-
                Ids of delivery destinations (GET /destinations): email, S3,
                webhook, SFTP or FTP targets that hold their own credentials,
                paths and sidecar settings. Destinations that are disabled or
                deleted when a job finishes are skipped. Empty means nothing is
                delivered.
        ui:
          type: object
          default: {}
          additionalProperties: true
          description: >-
            Display settings for the dashboard and the upload widget. Free-form:
            unknown keys are kept as they are.
          properties:
            units:
              type: string
              enum:
                - mm
                - cm
                - in
                - pt
                - m
                - px
              description: >-
                Unit for sizes shown to customers and in reports for jobs of
                this workflow; overrides the account default (millimetres when
                neither is set).
            tags:
              type: array
              items:
                type: string
              description: >-
                Short labels shown on the workflow's card in the dashboard, for
                example ["2 × PDF", "85 × 55 mm"]; the description is shown when
                there are none.
      allOf:
        - if:
            required:
              - trigger
            properties:
              trigger:
                const: proof_approval
          then:
            required:
              - proofing
            properties:
              proofing:
                required:
                  - enabled
                properties:
                  enabled:
                    const: true
        - if:
            not:
              required:
                - proofing
              properties:
                proofing:
                  required:
                    - enabled
                  properties:
                    enabled:
                      const: true
          then:
            properties:
              trigger:
                enum:
                  - order_placed
                  - on_accept
                  - manual
        - if:
            required:
              - merge
            properties:
              merge:
                required:
                  - mode
                properties:
                  mode:
                    const: merge_pdf
                  enabled:
                    not:
                      const: false
          then:
            properties:
              streams:
                items:
                  properties:
                    kind:
                      enum:
                        - pdf
                        - raster
                  if:
                    required:
                      - kind
                    properties:
                      kind:
                        const: raster
                  then:
                    required:
                      - steps
                    properties:
                      steps:
                        minItems: 1
                        allOf:
                          - items:
                              - properties:
                                  type:
                                    enum:
                                      - autofix
                                      - convert
                          - if:
                              minItems: 1
                              items:
                                - type: object
                                  required:
                                    - type
                                  properties:
                                    type:
                                      const: autofix
                            then:
                              minItems: 2
                              items:
                                - true
                                - properties:
                                    type:
                                      enum:
                                        - convert
                          - items:
                              if:
                                type: object
                                required:
                                  - type
                                properties:
                                  type:
                                    const: convert
                              then:
                                properties:
                                  enabled:
                                    enum:
                                      - true
        - if:
            required:
              - streams
            properties:
              streams:
                contains:
                  anyOf:
                    - required:
                        - kind
                      properties:
                        kind:
                          const: other
                    - allOf:
                        - required:
                            - kind
                          properties:
                            kind:
                              const: raster
                        - not:
                            required:
                              - steps
                            properties:
                              steps:
                                contains:
                                  allOf:
                                    - type: object
                                      required:
                                        - type
                                      properties:
                                        type:
                                          const: convert
                                    - not:
                                        properties:
                                          enabled:
                                            const: false
                                        required:
                                          - enabled
          then:
            properties:
              merge:
                if:
                  properties:
                    enabled:
                      not:
                        const: false
                then:
                  properties:
                    mode:
                      enum:
                        - none
                        - zip
    RecordFields:
      type: object
      properties:
        id:
          type: string
          description: The record id.
        source:
          type: string
          enum:
            - domain
            - store
          description: '`domain`: yours. `store`: a built-in catalog record.'
        customized:
          type: boolean
          description: >-
            Your own copy of a built-in record, under the same id. Revert drops
            it.
        draft:
          type: boolean
          description: Present and true on an unpublished draft.
        draftExpiresAt:
          type: string
          format: date-time
          description: When an unpublished draft is deleted.
        created:
          type: integer
          description: Unix time (seconds).
        modified:
          type: integer
          description: Unix time (seconds).
    Error:
      type: object
      properties:
        error:
          type: boolean
          const: true
        code:
          type: string
          description: >-
            Machine-readable reason, such as validation_failed,
            invalid_reference, not_found, in_use, draft_reference.
        message:
          type: string
        param:
          type: string
          description: >-
            The field at fault, as a dotted path (intake.ruleId,
            accepts.0.preflight.profileId).
        details:
          type: array
          description: Every problem found, or the records that block a delete.
          items:
            type: object
            additionalProperties: true
        requestId:
          type: string
          description: Quote it to support.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your secret key as a bearer token, e.g. `Authorization: Bearer
        sk_live_…`. Secret keys are server-side only.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.