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.
| Field | Type | Required | Description |
|---|
filaments | object[] | Yes | |
filament_source | "any" | "ams" | "external_spool" | No | Where the job may take filament from. Defaults to any. |
nozzle_diameters | (number | null)[] | No | 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 | uuid | No | Evaluate only this printer. |
printer_ids | uuid[] | No | Evaluate only these printers. Omit both to evaluate the organization's printers in name order. |
Responses
| Status | Description |
|---|
200 | Default Response |
400 | Default Response |
401 | Default Response |
403 | Default Response |
404 | Default Response |
422 | Default Response |
503 | Default Response |
200 response fields
| Field | Type | Required | Description |
|---|
suggestions | object[] | Yes | |
ineligible | object[] | Yes | |
evaluated | integer | Yes | |
truncated | boolean | Yes | |
400 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
401 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
403 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
404 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
422 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
503 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
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
}