API Endpoint Reference / Print Jobs

Plan which printers can take a plate and what to load

POST https://api.printhiv3d.com/v1/print-jobs/plan

Operation ID planPrintJob. Requires the read API key scope.

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

Content type application/json.

FieldTypeRequiredDescription
filamentsobject[]Yes
filament_source"any" | "ams" | "external_spool"NoWhere the job may take filament from. Defaults to any.
nozzle_diameters(number | null)[]NoNozzle sizes in millimetres the plate was sliced for, in nozzle order. Omit when unknown: no bay is then ruled out by size.
printer_iduuidNoEvaluate only this printer.
printer_idsuuid[]NoEvaluate only these printers. Omit both to evaluate the organization's printers in name order.

Responses

StatusDescription
200Default Response
400Default Response
401Default Response
403Default Response
404Default Response
422Default Response
503Default Response

200 response fields

FieldTypeRequiredDescription
suggestionsobject[]Yes
ineligibleobject[]Yes
evaluatedintegerYes
truncatedbooleanYes

400 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

401 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

403 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

404 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

422 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

503 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

Example 200 response

{
  "suggestions": [
    {
      "rank": 1,
      "printer": {
        "id": "7d3f1c2a-5b8e-4f6a-9c1d-2e4b6a8c0f13",
        "name": "Bay 3"
      },
      "load_actions": [],
      "already_loaded_count": 1
    }
  ],
  "ineligible": [],
  "evaluated": 1,
  "truncated": false
}