Skip to main content
POST /v1/assets/ingest creates or resolves one opaque managed asset for render and managed attachment workflows. It requires print_orders:write and an Idempotency-Key containing 1–200 characters. The returned asset_id can be used directly in a public print-order asset or a template image slot. A print-order asset also accepts an external HTTPS url; Batch Relay copies that source during quote creation and freezes the resulting managed asset with the quote.

​
Choose exactly one source

The request must contain exactly one of url or asset_id. Use url to copy an externally routable HTTPS image into Batch Relay’s private fulfillment storage:
Batch Relay downloads the complete file with network-safety checks, validates the image, calculates its SHA-256 digest and dimensions, and writes an immutable content-addressed object to private fulfillment R2. The original URL is neither retained as the fulfillment URL nor exposed to the provider. The public limits are 16 MiB, 100 million pixels, and JPEG, PNG, or TIFF input. Use asset_id to resolve a ready, authorized managed asset without copying its bytes:
For a studio-owned API account, this reuse path can also resolve a finalized same-studio platform image. Platform images remain in the studio-private bucket; they are referenced in place and are not copied into fulfillment storage. Cross-account and cross-studio IDs fail closed. Supplying both sources or neither source returns invalid_asset_source (422). Reusing an idempotency key with different request content returns idempotency_conflict (409). A deployment without its managed registry or private R2 configuration returns a managed-asset unavailable error (503). When the source host cannot be fetched, the pending managed-assets diagnostic rollout returns source_fetch_failed (502). The response tells you whether the source returned a non-2xx status, timed out, or could not be reached. It does not expose the upstream response body. The current deployed API still returns its broader ingestion failure until that rollout ships.

​
Response

The successful 201 response returns the stable asset_id plus immutable metadata. reused is true when Batch Relay resolved an existing asset_id or the content-addressed object already existed.
Use this ID in an image slot for POST /v1/templates/{template_id}/renders or as the source of a public print-order asset. Each print-order asset contains its semantic role and exactly one of url or asset_id. Test and Live requests use the same public host. The authenticated API-key record selects the lane.

​
Retention and reprints

Managed external assets are temporary:
  • An unattached asset is scheduled for cleanup 28 days after its managed record is created.
  • Once attached to an order, retention extends to the later of 28 days after order placement or 14 days after verified shipment.
  • An open reprint hold removes the cleanup deadline. Closing the hold applies its explicit future extension and recalculates the latest deadline across all attachments.
Cleanup operates in bounded batches through short-lived claimed jobs. Before deletion, Batch Relay rechecks the deadline and retention state; an open reprint hold cancels authorization. Deletion is restricted to exact managed object-key shapes under fulfillment/api-ingested/sha256/ and fulfillment/rendered/<job>/<surface>/<sha256>.<format>; it cannot delete a studio object or enumerate a prefix. Do not treat asset_id as permanent archival storage. After authorized cleanup, re-ingest your retained source before a new render or attachment.