---
title: "Send every print request of one project send in one batch"
method: POST
path: "/v1/print-jobs/sends"
tags: ["Print Jobs"]
---

# Send every print request of one project send in one batch

`POST /v1/print-jobs/sends`

## Request

- Base URL: `https://api.printhiv3d.com`
- URL: `https://api.printhiv3d.com/v1/print-jobs/sends`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/printhiv3d/apis/hive-api-documentation/docs/v1/print-jobs/sends/post.ts> (a function with typed inputs; its response is checked against the schema)

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

- object
  - `submissionId` string, required
  - `batch` union, required
    - object
      - `name` string, required
      - `modelFileId` string, uuid
    - object
      - `batchId` string, uuid, required
      - `supersedes` string[]
    - object
      - `unbatched` true, required
      - `modelFileId` string, uuid
      - `supersedes` string[]
  - `requests` object[], required
    - `key` string, required
    - `body` object, required

## Response `200`

Default Response

- object
  - `sendId` string, uuid, required
  - `submissionId` string, required
  - `batchId` string, uuid, nullable, required
  - `batchName` string, nullable, required
  - `replayed` boolean, required
  - `requests` object[], required
    - `requestId` string, uuid, required
    - `status` 'preparing' | 'held' | 'created' | 'failed' | 'cancelled', required
    - `externalId` string, nullable, required
    - `createdAt` string, required
    - `plate` integer, nullable
    - `printerId` string, uuid, nullable
    - `name` string, nullable
    - `sourceVersionId` string, uuid, nullable
    - `job` object, nullable, required
      - `id` number, required
      - `status` string, required
      - `model_file_id` string, uuid, nullable, required
      - `printer_id` string, uuid, nullable, required
      - `load_actions` object[], nullable: What is still to load for the assigned printer, recomputed on each read from its current filament state and the same planner as POST /v1/print-jobs/plan: load and swap actions only, in source slot order. An empty array means nothing to load, including an unassigned or finished job. Null means the actions could not be computed or the job changed during the read, so read again.
        - `actionId` string, required
        - `sourceSlot` integer, required
        - `kind` 'load' | 'swap' | 'already_loaded', required
        - `filament` object, required
          - `filamentId` string, uuid
          - `brand` string, nullable
          - `name` string
          - `colorName` string, nullable
          - `material` string, required
          - `colorHex` string, nullable, required
        - `bay` object, required
          - `id` string, required
          - `unitLabel` string, required
          - `label` string, required
          - `ams_id` integer
          - `slot_id` integer
        - `current` object
          - `material` string, nullable, required
          - `colorHex` string, nullable, required
        - `text` string, required
      - `print_options` object, nullable, required
        - `filament_route_state` 'waiting' | 'resolved'
        - `filament_warnings` string[]
        - `filament_waiting_reasons` object[]
          - `filamentId` string, uuid
          - `brand` string, nullable
          - `name` string
          - `colorName` string, nullable
          - `material` string
          - `colorHex` string
          - `code` 'filament_not_loaded' | 'material_route_changed', required
          - `sourceSlot` integer
          - `color` string, nullable
          - `message` string
          - `messageKind` 'requirement' | 'instruction'
          - `match` union
            - object
              - …
            - object
              - …
            - object
              - …
          - `cause` 'slot_empty' | 'missing_material' | 'color_distance' | 'slot_conflict' | 'reported_material_mismatch' | 'material_type_mismatch' | 'material_unassigned'
          - `suggestedTargetSlot` object
            - `ams_id` integer, required
            - `slot_id` integer, required
    - `requiredActions` union[], required
      - union
        - object
          - `item` integer, required
          - `plateNumber` integer, required
          - `hold` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
        - object
          - `code` string, required
    - `warnings` object[]
      - `code` string, required
    - `error` object, nullable, required
    - `batchId` string, uuid, nullable
    - `attempt` integer
    - `retryOf` string, uuid, nullable
    - `retriedBy` string, uuid, nullable
    - `superseded` boolean
    - `variants` object[]
      - `targetModelId` string, required
      - `targetNozzleMm` number, required
      - `fit` string, required
      - `status` 'preparing' | 'ready' | 'held' | 'failed' | 'cancelled' | 'discarded', required
      - `representativePrinterId` string, uuid, nullable, required
      - `bound` boolean, required
      - `warnings` object[]
        - `code` string, required
      - `holds` object[]
      - `failure` object, nullable
        - `code` string
        - `sliceCode` string
        - `message` string
    - `filaments` object[]
      - `filamentId` string, uuid
      - `brand` string, nullable
      - `name` string
      - `colorName` string, nullable
      - `material` string
      - `colorHex` string
      - `sourceSlot` integer, required
    - `estimatedSeconds` integer, nullable
    - `createdJobId` integer, nullable
    - `modelFileId` string, uuid, nullable
  - `superseded` string[], required

## Other responses

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

## Changes

- **2026-11-11** `f440fad63ce0`: 21 info
  - added `subschema #3` to the `batch` request property `anyOf` list
  - added the optional property `accepted/requests/items/createdJobId` to the response with the `400` status
  - added the optional property `accepted/requests/items/createdJobId` to the response with the `409` status
  - added the optional property `accepted/requests/items/createdJobId` to the response with the `422` status
  - …17 more
- **2026-11-10** `09f2403145b5`: 1 info
  - api operation id `sendPrintJobs` was added
- **2026-11-10** `86492c6abdea`: 5 breaking, 15 warning, 20 info
  - the response property `accepted/requests/items/job/print_options/filament_waiting_reasons/items/color` became nullable for the status `400`
  - the response property `accepted/requests/items/job/print_options/filament_waiting_reasons/items/color` became nullable for the status `409`
  - the response property `accepted/requests/items/job/print_options/filament_waiting_reasons/items/color` became nullable for the status `422`
  - the response property `requests/items/job/print_options/filament_waiting_reasons/items/color` became nullable for the status `200`
  - …36 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/printhiv3d/apis/hive-api-documentation/changes/v1/print-jobs/sends/post.md)

---

[API](https://skmtc.dev/printhiv3d/apis/hive-api-documentation.md) - [All operations](https://skmtc.dev/printhiv3d/apis/hive-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/printhiv3d/apis/hive-api-documentation/revisions/35a7515c29d5?raw)