API Endpoint Reference / Print Jobs

Amend a held creation request and plan it again

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

Operation ID amendPrintJobCreateRequest. Requires the control API key scope.

Requires control scope. Read the request first: each hold in `requiredActions` names in `resolvedBy` the fields that can clear it, and amendment succeeds only when every hold lists `amend` in `allowedActions`. Send the `plateVersion` the holds report and at least one of `materialMappings`, `printerId` (a request that names its printer only) and `sourceVersionId` (an inspected source version of the organization). Each field replaces that field of the request and nothing else. Hive plans the request again with new slices under the same `requestId`, and a hold that planning finds reports as for any request. Repeating the latest amendment answers 202 and plans nothing while the request prepares or has made its job. A stale `plateVersion`, a request that is not held, or holds that no field clears answer 409 `review_conflict` and change nothing. A `sourceVersionId` whose inspection has no plate of the request's number answers 422 `plate_not_found` and changes nothing.

Parameters

NameInTypeRequiredDescription
requestIdpathstringYes

Request body

Content type application/json.

FieldTypeRequiredDescription
plateVersionstringYesThe plateVersion that the request's holds report now. A request that changed since you read it answers 409 review_conflict.
materialMappingsobject[]NoReplaces the request's filaments, in the shape a create takes. Clears holds whose resolvedBy names materialMappings.
printerIduuidNoReplaces the printer of a request that names one. Clears holds whose resolvedBy names printerId, such as an unqualified conversion. Hive qualifies the new printer when it plans again, so a printer that is still unqualified holds the request again. A Smart Queue request answers 422 printer_not_amendable.
sourceVersionIduuidNoAn inspected source version of the organization that replaces the request's source. Its inspection must list the request's plate, or the amendment answers 422 plate_not_found and changes nothing.

Responses

StatusDescription
202Default Response
400The body is not an amendment, or its materialMappings are not filaments a create takes (invalid_filaments)
401Authentication required
403Insufficient API key scope or organization membership, or a principal that is neither an API key nor a signed-in user, so Hive has no actor to record (amendment_actor_required)
404The request is unknown or belongs to another organization (not_found), or the printer (printer_not_found), source version (source_not_found) or catalog filament the body names is not the organization's
409The request changed since you read it, is not held, or holds nothing an amendment clears (review_conflict), or the source version is still being inspected (source_not_inspected)
422A Smart Queue request has no printer to replace (printer_not_amendable), the source version failed inspection (source_inspection_failed) or has no plate of the request's number (plate_not_found), or a filament cannot be used (invalid_preparation_mappings and the catalog refusals of a create)
500Unexpected server error
503Creation request storage unavailable

202 response fields

FieldTypeRequiredDescription
amendedbooleanYes

400 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo
codestringNo
statusCodeintegerNo
filamentsobject[]No

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
codestringNo
statusCodeintegerNo
filamentsobject[]No

409 response fields

FieldTypeRequiredDescription
errorstringYes
messagestringNo
requestIdstringNo
codestringNo
statusCodeintegerNo
filamentsobject[]No

422 response fields

FieldTypeRequiredDescription
errorstringYes
messagestringNo
requestIdstringNo
codestringNo
statusCodeintegerNo
filamentsobject[]No

500 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo
codestringNo
statusCodeintegerNo

503 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo
codestringNo
statusCodeintegerNo

Example 202 response

{
  "amended": true
}