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

NameInTypeRequiredDescription
idempotency-keyheaderstringNo

Request body

Content type application/json.

Send one of these shapes.

Option 1

FieldTypeRequiredDescription
namestringYes
allowUnqualifiedConversionbooleanNoAccepted for compatibility. Has no effect on JSON creates, which use an existing artifact and do not perform conversion.
externalIdstringNo
acceptEngineSettingUpdatesbooleanNo
model_file_idstringYes
organization_idstringNo
organizationIdstringNoOrganization ID (optional, defaults to user's primary organization)
printer_iduuid | nullNo
plateintegerNoOne-based plate number in the project archive
filamentsobject[]NoComplete 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"NoCreate assigned jobs waiting for filament, or reject mismatches with 422
task_iduuid | nullNo
make_idstringNoOptional make ID to derive required materials
print_optionsobjectNo

Option 2

FieldTypeRequiredDescription
source_version_iduuidYesA 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.
namestringNo
allowUnqualifiedConversionbooleanNoAccept unqualified same-brand Bambu printer conversions for a named printer. Defaults to the organization setting, or false. Safety checks still apply.
allowNozzleChangebooleanNoReslice 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.
plateintegerYesOne-based plate number in the project archive
filamentsobject[]YesFilament 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_iduuidNo
on_filament_mismatch"wait" | "reject"NoCreate assigned jobs waiting for filament, or reject mismatches with 422
externalIdstringNo
acceptEngineSettingUpdatesbooleanNo
release"automatic" | "manual"No
print_optionsobjectNo

Content type multipart/form-data.

FieldTypeRequiredDescription
filebinaryYes
namestringNo
allowUnqualifiedConversionbooleanNoAccept unqualified same-brand Bambu printer conversions for a named printer. Defaults to the organization setting, or false. Safety checks still apply.
allowNozzleChangebooleanNoReslice 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.
plateintegerYesOne-based plate number in the project archive
filamentsobject[]YesFilament 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_iduuidNo
on_filament_mismatch"wait" | "reject"NoCreate assigned jobs waiting for filament, or reject mismatches with 422
externalIdstringNo
acceptEngineSettingUpdatesbooleanNo
release"automatic" | "manual"No
print_optionsobjectNo

Responses

StatusDescription
201Default Response
202Default Response
400Default Response
409Default Response
422Default Response
500Default Response
503Print 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

FieldTypeRequiredDescription
jobobjectNo
eligiblePrintersobject[]NoDetailed match results for fully eligible printers
partiallyEligiblePrintersobject[]NoDetailed match results for partially eligible printers including missing materials

202 response fields

FieldTypeRequiredDescription
requestIduuidYes
status"preparing" | "held" | "created" | "failed" | "cancelled"Yes
externalIdstring | nullYes
createdAtstringYes
plateinteger | nullNo
printerIduuid | nullNo
namestring | nullNo
sourceVersionIduuid | nullNo
jobobject | nullYes
requiredActionsobject[]Yes
warningsobject[]No
errorobject | nullYes
batchIduuid | nullNo
attemptintegerNo
retryOfuuid | nullNo
retriedByuuid | nullNo
supersededbooleanNo
variantsobject[]No
filamentsobject[]No
estimatedSecondsinteger | nullNo
createdJobIdinteger | nullNo
modelFileIduuid | nullNo

400 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo

409 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
reasonstringNo
retry_countnumberNo
max_retriesnumberNo
next_eligible_atdate-time | nullNo

422 response fields

FieldTypeRequiredDescription
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
messagestringNo
filamentsobject[]No

500 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo

503 response fields

FieldTypeRequiredDescription
errorstringYescatalog_store_failed for catalog availability failures, or another existing print-creation availability error code.
messagestringYes
filamentsobject[]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
}