API Endpoint Reference / Print Jobs

Cancel a creation request before job admission

POST https://api.printhiv3d.com/v1/print-jobs/create-requests/{requestId}/cancel

Operation ID cancelPrintJobCreateRequest. Requires the control API key scope.

Requires control scope. Preparing or held requests become cancelled without printer action and return 202 with code cancelled. Failed requests return 200 with code already_terminal and their unchanged receipt. Cancelled requests return 200 with code already_cancelled. Terminal states are preserved, including when they win a concurrent cancellation. Pending is a prepared-plate state, not a creation-request state. Cancellation settles pending plates and stops polling; it does not delete stored files or preparation receipts.

Parameters

NameInTypeRequiredDescription
requestIdpathstringYesCreation request UUID. Invalid or inaccessible IDs return 404.

Responses

StatusDescription
200Default Response
202Default Response
400Invalid request or organization scope
401Authentication required
403Insufficient API key scope or organization membership
404Creation request not found
409A job already exists. Cancel it with PATCH /v1/print-jobs/{id}/status using status CANCELLED and a reason. jobId is null if the job was deleted.
500Unexpected server error
503creation_unavailable: cancellation could not be confirmed, including an RPC failure or a lost response after commit. Retry the same request safely; a committed cancellation returns 200 already_cancelled on retry instead of 202.

200 response fields

Send one of these shapes.

Option 1

FieldTypeRequiredDescription
requestIduuidYes
status"failed"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
code"already_terminal"Yes

Option 2

FieldTypeRequiredDescription
requestIduuidYes
status"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
code"already_cancelled"Yes

202 response fields

FieldTypeRequiredDescription
cancelledtrueYes
status"cancelled"Yes
code"cancelled"Yes

400 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo
codestringNo
statusCodeintegerNo

401 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo
codestringNo
statusCodeintegerNo

403 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo
codestringNo
statusCodeintegerNo

404 response fields

FieldTypeRequiredDescription
errorstringYes
messagestringNo
requestIdstringNo

409 response fields

FieldTypeRequiredDescription
error"job_already_created"Yes
code"job_already_created"Yes
status"created"Yes
jobIdnumber | nullYes

500 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo
codestringNo
statusCodeintegerNo

503 response fields

FieldTypeRequiredDescription
error"creation_unavailable"Yes
code"creation_unavailable"Yes
messagestringYes

Example 202 response

{
  "cancelled": true,
  "status": "cancelled",
  "code": "cancelled"
}