API Endpoint Reference / Print Jobs
Request dispatch of a queued print job to its assigned printer
POST https://api.printhiv3d.com/v1/print-jobs/{id}/start
Operation ID startPrintJob. Requires the control API key scope.
Requires control scope. Asks Print Hive to start a QUEUED print job on the printer it is assigned to. Print Hive sends no command to the printer. It checks that dispatch is safe now and moves the job to the front of that printer's queue. The job stays QUEUED, and the HiveLink host of that printer claims it on its next poll, which makes it IN_PROGRESS. A 200 answer means the request is accepted, not that the print has begun. Read the job with `getPrintJob` to follow it.
Print Hive checks the job and the printer again on every call. The job must be QUEUED, assigned to a printer, and have an available model file. The printer must be online, ready for a new job, out of maintenance, not locked by another job, and free of any job in progress. A job queued with a fixed material route also needs its printer to still hold the materials that route chose. A failed check answers 409 with a `reason` and changes nothing.
Send `expected_printer_id` with the printer you mean. If the job was reassigned, the call answers 409 `job_assignment_changed` and starts nothing, so a start cannot land on a different printer than the one you checked.
A started print uses printer time and filament. Ask the person who owns the job before you start it.
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | Yes | The numeric print job id. |
Request body
Content type application/json.
| Field | Type | Required | Description |
|---|
expected_printer_id | uuid | No | The printer you expect the job to be assigned to. If the job was reassigned, the call answers 409 `job_assignment_changed` and starts nothing. |
organizationId | string | No | Organization ID (optional, defaults to user's primary organization) |
Responses
| Status | Description |
|---|
200 | Dispatch requested. The job stays QUEUED until the HiveLink host of its printer claims it. |
400 | The request is malformed: the job id is not numeric, or `expected_printer_id` is not a UUID. |
401 | Default Response |
403 | The API key lacks the `control` scope (`code: API_KEY_SCOPE_REQUIRED`). |
404 | The job is not in the organization (`job_not_found`), or its assigned printer was not found (`printer_not_found`). |
409 | Dispatch is not possible now, and nothing changed. The `reason` field names the failed check. `job_not_queued` means the job is not QUEUED. `job_unassigned` means no printer is assigned. `job_assignment_changed` means the job's printer is not `expected_printer_id`. `printer_offline` means HiveLink does not report the printer as connected. `printer_not_ready` means the printer is not marked ready, or its ready state has no bed-clear evidence. `printer_in_maintenance` means the printer is in maintenance mode. `printer_locked` means another job holds the printer. `printer_busy` means the printer already has a job in progress. `material_route_changed` means the printer no longer holds the materials that the job's route chose, or the file could not be checked against them. `model_file_unavailable`, `model_file_deleted`, `model_unavailable`, and `model_deleted` mean the job's model file or its parent model is missing or deleted. `model_file_not_ready` means the model file is still processing; try again when it is ready. `batch_scheduling_held` means an operator holds new print admission for the job's batch. `batch_scheduling_scope_conflict` means the job's batch is not in this organization. `h3c_rack_dispatch_unqualified` means print start is on hold for this printer model. |
500 | Print Hive could not check the model file (`model_file_check_failed`) or could not request dispatch (`dispatch_failed`). Try again. |
default | Any other error, such as 413 for a body over 1 MiB, 415 for an unsupported content type or encoding, or 503 when a dependency is unavailable. |
200 response fields
| Field | Type | Required | Description |
|---|
id | number | No | |
printer_id | null | string | No | |
queue_rank | null | number | No | |
global_queue_rank | null | number | No | |
status | string | No | |
dispatch | "requested" | No | |
400 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | Request id for support. Present when the global error handler answers. |
401 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | Request id for support. Present when the global error handler answers. |
403 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
code | string | No | |
message | string | No | |
requestId | string | No | Request id for support. Present when the global error handler answers. |
404 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
reason | "job_not_found" | "printer_not_found" | No | |
requestId | string | No | Request id for support. Present when the global error handler answers. |
409 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
reason | "h3c_rack_dispatch_unqualified" | "job_assignment_changed" | "batch_scheduling_held" | "batch_scheduling_scope_conflict" | "job_not_queued" | "job_unassigned" | "model_file_unavailable" | "model_file_deleted" | "model_file_not_ready" | "model_unavailable" | "model_deleted" | "printer_in_maintenance" | "printer_offline" | "printer_not_ready" | "printer_locked" | "printer_busy" | "material_route_changed" | No | |
requestId | string | No | Request id for support. Present when the global error handler answers. |
500 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
reason | "model_file_check_failed" | "dispatch_failed" | No | |
requestId | string | No | Request id for support. Present when the global error handler answers. |
default response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | Request id for support. Present when the global error handler answers. |
Example 200 response
{
"id": 48213,
"printer_id": "7d3f1c2a-5b8e-4f6a-9c1d-2e4b6a8c0f13",
"queue_rank": -1024,
"global_queue_rank": null,
"status": "QUEUED",
"dispatch": "requested"
}