API Endpoint Reference / Print Jobs
Create one print job for one plate
POST https://api.printhiv3d.com/v1/print-jobs/create
Operation ID createPrintJob. Requires the control API key scope.
Parameters
| Name | In | Type | Required | Description |
|---|
idempotency-key | header | string | No | |
Request body
Content type application/json.
Send one of these shapes.
Option 1
| Field | Type | Required | Description |
|---|
name | string | Yes | |
allowUnqualifiedConversion | boolean | No | Accepted for compatibility. Has no effect on JSON creates, which use an existing artifact and do not perform conversion. |
externalId | string | No | |
acceptEngineSettingUpdates | boolean | No | |
model_file_id | string | Yes | |
organization_id | string | No | |
organizationId | string | No | Organization ID (optional, defaults to user's primary organization) |
printer_id | uuid | null | No | |
plate | integer | No | One-based plate number in the project archive |
filaments | object[] | No | Complete filament requirements for the selected plate. Cannot be combined with raw AMS mappings. An omitted match keeps type_color matching. |
on_filament_mismatch | "wait" | "reject" | No | Create assigned jobs waiting for filament, or reject mismatches with 422 |
task_id | uuid | null | No | |
make_id | string | No | Optional make ID to derive required materials |
print_options | object | No | |
Option 2
| Field | Type | Required | Description |
|---|
source_version_id | uuid | Yes | A source version of the organization, such as the one PUT /v1/model-files/{id}/print-source returns. It may still be reading. Many requests can name one source. Cannot be combined with model_file_id. |
name | string | No | |
allowUnqualifiedConversion | boolean | No | Accept unqualified same-brand Bambu printer conversions for a named printer. Defaults to the organization setting, or false. Safety checks still apply. |
allowNozzleChange | boolean | No | Reslice a project saved for another nozzle with the target printer's stock profile. Without it, a nozzle change holds with nozzle_change_requires_consent. Bed, material and printer checks still apply. |
plate | integer | Yes | One-based plate number in the project archive |
filaments | object[] | Yes | Filament requirements for the selected plate. Name every filament the sliced plate uses. Slots the slicer leaves unused, such as an unneeded support filament, are dropped from the job. A used slot that is not named ends the creation request as failed, with error filaments_do_not_cover_plate, the missing zero-based slots in missingSlots, and the sliced output in outputFileId. Cannot be combined with raw AMS mappings. Each filament can set match to exact_material with ordered alternates, type_color, or type_only. An omitted match keeps material and color proximity rules. |
printer_id | uuid | No | |
on_filament_mismatch | "wait" | "reject" | No | Create assigned jobs waiting for filament, or reject mismatches with 422 |
externalId | string | No | |
acceptEngineSettingUpdates | boolean | No | |
release | "automatic" | "manual" | No | |
print_options | object | No | |
Content type multipart/form-data.
| Field | Type | Required | Description |
|---|
file | binary | Yes | |
name | string | No | |
allowUnqualifiedConversion | boolean | No | Accept unqualified same-brand Bambu printer conversions for a named printer. Defaults to the organization setting, or false. Safety checks still apply. |
allowNozzleChange | boolean | No | Reslice a project saved for another nozzle with the target printer's stock profile. Without it, a nozzle change holds with nozzle_change_requires_consent. Bed, material and printer checks still apply. |
plate | integer | Yes | One-based plate number in the project archive |
filaments | object[] | Yes | Filament requirements for the selected plate. Name every filament the sliced plate uses. Slots the slicer leaves unused, such as an unneeded support filament, are dropped from the job. A used slot that is not named ends the creation request as failed, with error filaments_do_not_cover_plate, the missing zero-based slots in missingSlots, and the sliced output in outputFileId. Cannot be combined with raw AMS mappings. Each filament can set match to exact_material with ordered alternates, type_color, or type_only. An omitted match keeps material and color proximity rules. |
printer_id | uuid | No | |
on_filament_mismatch | "wait" | "reject" | No | Create assigned jobs waiting for filament, or reject mismatches with 422 |
externalId | string | No | |
acceptEngineSettingUpdates | boolean | No | |
release | "automatic" | "manual" | No | |
print_options | object | No | |
Responses
| Status | Description |
|---|
201 | Default Response |
202 | Default Response |
400 | Default Response |
409 | Default Response |
422 | Default Response |
500 | Default Response |
503 | Print creation is temporarily unavailable. catalog_store_failed indicates a failed organization-setting or catalog read and can include the affected source slot. |
201 response fields
| Field | Type | Required | Description |
|---|
job | object | No | |
eligiblePrinters | object[] | No | Detailed match results for fully eligible printers |
partiallyEligiblePrinters | object[] | No | Detailed match results for partially eligible printers including missing materials |
202 response fields
| Field | Type | Required | Description |
|---|
requestId | uuid | Yes | |
status | "preparing" | "held" | "created" | "failed" | "cancelled" | Yes | |
externalId | string | null | Yes | |
createdAt | string | Yes | |
plate | integer | null | No | |
printerId | uuid | null | No | |
name | string | null | No | |
sourceVersionId | uuid | null | No | |
job | object | null | Yes | |
requiredActions | object[] | Yes | |
warnings | object[] | No | |
error | object | null | Yes | |
batchId | uuid | null | No | |
attempt | integer | No | |
retryOf | uuid | null | No | |
retriedBy | uuid | null | No | |
superseded | boolean | No | |
variants | object[] | No | |
filaments | object[] | No | |
estimatedSeconds | integer | null | No | |
createdJobId | integer | null | No | |
modelFileId | uuid | null | No | |
400 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
409 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
reason | string | No | |
retry_count | number | No | |
max_retries | number | No | |
next_eligible_at | date-time | null | No | |
422 response fields
| Field | Type | Required | Description |
|---|
error | "invalid_preparation_mappings" | "filament_catalog_conflict" | "alternate_material_mismatch" | "primary_in_alternates" | "catalog_filament_not_found" | "invalid_catalog_filament" | "filament_requirements_unsatisfied" | "printer_model_incompatible" | "hardware:nozzle_diameter_mismatch" | "h3c_rack_dispatch_unqualified" | "hardware:nozzle_diameter_multiple_unsupported" | "target_slot_unavailable" | "insufficient_filament_routes" | No | |
message | string | No | |
filaments | object[] | No | |
500 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
503 response fields
| Field | Type | Required | Description |
|---|
error | string | Yes | catalog_store_failed for catalog availability failures, or another existing print-creation availability error code. |
message | string | Yes | |
filaments | object[] | No | |
Example 202 response
{
"requestId": "a91d4f7c-3e2b-4a6d-8c5f-0b7e2d9a4c18",
"status": "preparing",
"externalId": "order-1042-line-1",
"createdAt": "2026-11-04T18:00:00.000Z",
"job": null,
"requiredActions": [],
"error": null,
"plate": 1,
"printerId": "7d3f1c2a-5b8e-4f6a-9c1d-2e4b6a8c0f13",
"name": "Phone stand",
"sourceVersionId": "5f8a2c6e-9d1b-4e73-b4a0-2c7e9f1d6b85",
"warnings": [],
"batchId": null,
"attempt": 1,
"retryOf": null,
"retriedBy": null,
"superseded": false
}