API Endpoint Reference / Print Jobs

Send every print request of one project send in one batch

POST https://api.printhiv3d.com/v1/print-jobs/sends

Operation ID sendPrintJobs. Requires the control API key scope.

Hive accepts every request in one batch, or none of them. A send of one request can send `batch: {unbatched: true}` instead: Hive then makes no batch, `batchId` is null, and the request is read, released, approved, retried and cancelled by its id through `/v1/print-jobs/create-requests`. A send with no batch holds exactly one request, and the request it replaces, in `batch.supersedes`, also has no batch. `submissionId` identifies the send: a replay with the same id and body returns the same send and makes nothing new, so a caller that lost the answer sends the same body again. Hive accepts one body for each `submissionId`: another body is refused with 409 `idempotency_conflict`, and `accepted` is the send that stands. A 4xx answer means nothing was made; `refused` names each request Hive refused. To replace requests of a batch that an earlier send made, send `batch.batchId` and `batch.supersedes`: Hive adds the new requests to that batch only when it accepts the send, cancels the held requests it replaces, and marks the failed ones replaced so they are not retried. A cancelled or archived batch takes no send.

Request body

Content type application/json.

FieldTypeRequiredDescription
submissionIdstringYes
batchobjectYes
requestsobject[]Yes

Responses

StatusDescription
200Default Response
201Default Response
400Default Response
401Authentication required
403API key requires control scope
404Source or batch not found
409Default Response
422Default Response
503Hive could not take the send; replay it with the same body

200 response fields

FieldTypeRequiredDescription
sendIduuidYes
submissionIdstringYes
batchIduuid | nullYes
batchNamestring | nullYes
replayedbooleanYes
requestsobject[]Yes
supersededuuid[]Yes

201 response fields

FieldTypeRequiredDescription
sendIduuidYes
submissionIdstringYes
batchIduuid | nullYes
batchNamestring | nullYes
replayedbooleanYes
requestsobject[]Yes
supersededuuid[]Yes

400 response fields

FieldTypeRequiredDescription
errorstringYes
refusedobject[]No
acceptedobjectNo

401 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo
codestringNo
statusCodeintegerNo

403 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo
codestringNo
statusCodeintegerNo

404 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

409 response fields

FieldTypeRequiredDescription
errorstringYes
refusedobject[]No
acceptedobjectNo

422 response fields

FieldTypeRequiredDescription
errorstringYes
refusedobject[]No
acceptedobjectNo

503 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

Example 201 response

{
  "sendId": "0e4c8a2f-6b1d-4d97-8a3e-f5c2b9d7e104",
  "submissionId": "storefront-send-1042",
  "batchId": "b6e3a9d1-7c4f-4b28-9e0a-5d1c8f3b7a62",
  "batchName": "phone-stand.3mf",
  "replayed": false,
  "requests": [
    {
      "requestId": "a91d4f7c-3e2b-4a6d-8c5f-0b7e2d9a4c18",
      "status": "created",
      "externalId": "order-1042-line-1",
      "createdAt": "2026-11-04T18:00:00.000Z",
      "job": {
        "id": 48213,
        "status": "queued",
        "model_file_id": "e2b7c9d4-1f6a-4c38-9b0e-7a5d3f8c1e26",
        "printer_id": "7d3f1c2a-5b8e-4f6a-9c1d-2e4b6a8c0f13",
        "print_options": {}
      },
      "requiredActions": [],
      "error": null
    }
  ],
  "superseded": []
}