---
title: "Plan which printers can take a plate and what to load"
method: POST
path: "/v1/print-jobs/plan"
tags: ["Print Jobs", "Public"]
---

# Plan which printers can take a plate and what to load

`POST /v1/print-jobs/plan`

## Request

- Base URL: `https://api.printhiv3d.com`
- URL: `https://api.printhiv3d.com/v1/print-jobs/plan`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/printhiv3d/apis/hive-api-documentation/docs/v1/print-jobs/plan/post.ts> (a function with typed inputs; its response is checked against the schema)

Takes the plate's effective filament requirements and returns the printers where every filament has a bay, ranked by fewest load and swap actions, then by Smart Queue match score, then by name. Each suggestion lists only what is still missing, as load actions that name the exact bay and its text. This is material-routing advice: connectivity, readiness, maintenance and current work are not checked, and a suggestion does not reserve a printer or authorize changing a bay during a print. Printers with no material route are listed with why. Name printers with printer_id or printer_ids, up to 25; otherwise up to 100 printers are evaluated in name order. An unknown or inaccessible named printer returns 404. Reading sends nothing to a printer, slices nothing and creates no job.

## Request body

- object
  - `filaments` object[], required
    - `filamentId` string, uuid
    - `brand` string, nullable
    - `name` string
    - `colorName` string, nullable
    - `material` string, required: The job's effective material family, used as given: PLA, PLA-S, PETG
    - `colorHex` string
    - `match` union
      - object
        - `kind` 'exact_material', required
        - `alternates` string[]
      - object
        - `kind` 'type_color', required
      - object
        - `kind` 'type_only', required
    - `sourceSlot` integer, required: Zero-based project filament index
    - `color` string
    - `targetSlot` object
      - `ams_id` integer, required
      - `slot_id` integer, required
    - `nozzle` integer: Logical nozzle the slice binds this filament to: 0 left, 1 right. Omit on a single-nozzle plate.
  - `filament_source` 'any' | 'ams' | 'external_spool': Where the job may take filament from. Defaults to any.
  - `nozzle_diameters` number[]: Nozzle sizes in millimetres the plate was sliced for, in nozzle order. Omit when unknown: no bay is then ruled out by size.
  - `printer_id` string, uuid: Evaluate only this printer.
  - `printer_ids` string[]: Evaluate only these printers. Omit both to evaluate the organization's printers in name order.

## Response `200`

Default Response

- object
  - `suggestions` object[], required
    - `rank` integer, required
    - `printer` object, required
      - `id` string, uuid, required
      - `name` string, nullable, required
    - `load_actions` object[], required
      - `actionId` string, required
      - `sourceSlot` integer, required
      - `kind` 'load' | 'swap' | 'already_loaded', required
      - `filament` object, required
        - `filamentId` string, uuid
        - `brand` string, nullable
        - `name` string
        - `colorName` string, nullable
        - `material` string, required
        - `colorHex` string, nullable, required
      - `bay` object, required
        - `id` string, required
        - `unitLabel` string, required
        - `label` string, required
        - `ams_id` integer
        - `slot_id` integer
      - `current` object
        - `material` string, nullable, required
        - `colorHex` string, nullable, required
      - `text` string, required
    - `already_loaded_count` integer, required
  - `ineligible` object[], required
    - `printer` object, required
      - `id` string, uuid, required
      - `name` string, nullable, required
    - `reason` 'no_filament_bays' | 'no_eligible_bay' | 'no_free_bay', required
    - `message` string, required
    - `source_slots` integer[], required
  - `evaluated` integer, required
  - `truncated` boolean, required

## Other responses

- `400`: Default Response
- `401`: Default Response
- `403`: Default Response
- `404`: Default Response
- `422`: Default Response
- `503`: Default Response

## Changes

- **2026-11-10** `09f2403145b5`: 1 info
  - api operation id `planPrintJob` was added
- **2026-11-10** `86492c6abdea`: 2 info
  - added the new optional request property `filaments/items/match`
  - the request property `filaments/items/color` became optional
- **2026-11-09** `48e1ada05d57`: 2 warning, 2 info
  - changed the pattern of the request property `filaments/items/color` from `^#?[0-9a-fA-F]{6}$` to `^#?[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$`
  - changed the pattern of the request property `filaments/items/colorHex` from `^#[0-9A-F]{6}$` to `^#[0-9A-F]{6}(?:[0-9A-F]{2})?$`
  - the `suggestions/items/load_actions/items/current/colorHex` response's property pattern was changed from `^#[0-9A-F]{6}$` to `^#[0-9A-F]{6}(?:[0-9A-F]{2})?$` for the status `200`
  - the `suggestions/items/load_actions/items/filament/colorHex` response's property pattern was changed from `^#[0-9A-F]{6}$` to `^#[0-9A-F]{6}(?:[0-9A-F]{2})?$` for the status `200`
- **2026-11-05** `aceead3d83f6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/printhiv3d/apis/hive-api-documentation/changes/v1/print-jobs/plan/post.md)

---

[API](https://skmtc.dev/printhiv3d/apis/hive-api-documentation.md) - [All operations](https://skmtc.dev/printhiv3d/apis/hive-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/printhiv3d/apis/hive-api-documentation/revisions/35a7515c29d5?raw)