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
| Name | In | Type | Required | Description |
|---|
requestId | path | string | Yes | Creation request UUID. Invalid or inaccessible IDs return 404. |
Responses
| Status | Description |
|---|
200 | Default Response |
202 | Default Response |
400 | Invalid request or organization scope |
401 | Authentication required |
403 | Insufficient API key scope or organization membership |
404 | Creation request not found |
409 | A 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. |
500 | Unexpected server error |
503 | creation_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
| Field | Type | Required | Description |
|---|
requestId | uuid | Yes | |
status | "failed" | 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 | |
code | "already_terminal" | Yes | |
Option 2
| Field | Type | Required | Description |
|---|
requestId | uuid | Yes | |
status | "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 | |
code | "already_cancelled" | Yes | |
202 response fields
| Field | Type | Required | Description |
|---|
cancelled | true | Yes | |
status | "cancelled" | Yes | |
code | "cancelled" | Yes | |
400 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
code | string | No | |
statusCode | integer | No | |
401 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
code | string | No | |
statusCode | integer | No | |
403 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
code | string | No | |
statusCode | integer | No | |
404 response fields
| Field | Type | Required | Description |
|---|
error | string | Yes | |
message | string | No | |
requestId | string | No | |
409 response fields
| Field | Type | Required | Description |
|---|
error | "job_already_created" | Yes | |
code | "job_already_created" | Yes | |
status | "created" | Yes | |
jobId | number | null | Yes | |
500 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
code | string | No | |
statusCode | integer | No | |
503 response fields
| Field | Type | Required | Description |
|---|
error | "creation_unavailable" | Yes | |
code | "creation_unavailable" | Yes | |
message | string | Yes | |
Example 202 response
{
"cancelled": true,
"status": "cancelled",
"code": "cancelled"
}