Cartridges

A cartridge is a sparse tape image on its library’s pool, labelled with a barcode. Its capacity follows the library’s drive generation. Export, evict, and import are asynchronous jobs; mint and delete are synchronous.

The cartridge object

{
  "label": "OVB001L5",
  "library": 10,
  "size_bytes": 267421859840,
  "phys_bytes": 171798691840,
  "modified": "2026-08-31T00:14:20Z",
  "location": "slot:1",
  "local_state": "resident",
  "last_export_gen": "20260831T001507Z"
}

Field	Meaning
`size_bytes`	Bytes the host has written (the logical tape image).
`phys_bytes`	Allocated on disk after compression. Global dedup savings appear at pool level, not here.
`location`	`slot:N`, `ie:N`, `drive:N`, or `missing`.
`local_state`	`resident`, or `evicted` when only a labelled stub remains and the data must be imported before a restore.
`last_export_gen`	The most recent bucket generation for this label, if any.

GET /api/cartridges

read-only

Every cartridge on every library.

curl -sk https://appliance:8443/api/cartridges -H "Authorization: Bearer $OVTL_KEY"

GET /api/cartridges/{label}

read-only

One cartridge, or 404.

POST /api/cartridges

admin

Mints cartridges into free storage slots. No restart. Minted cartridges already carry their volume label, so on the host they are ready for ADDTAPCTG and INZTAP.

Body field	Type	Notes
`library`	int	Library id. `0` picks the only live library, and is a `400` if there is more than one.
`label`	string	Six `A-Z0-9` characters plus the media suffix, e.g. `OVB011L5`. Empty auto-sequences from the library’s prefix. Must be empty when `count` > 1.
`count`	int	Default 1. Capped at the library’s free storage slots.

curl -sk -X POST https://appliance:8443/api/cartridges \
  -H "Authorization: Bearer $OVTL_KEY" -H 'Content-Type: application/json' \
  -d '{"library":10,"count":3}'

{"library": 10, "size_gb": 1500, "created": [{"label": "OVB004L5", "slot": 4}, {"label": "OVB005L5", "slot": 5}, {"label": "OVB006L5", "slot": 6}]}

size_gb is the native capacity of the library’s drive generation in decimal GB; the image is sparse and takes disk only as it is written. A label that already exists locally or in the S3 catalog is refused. If a batch fails part way, the response is a 500 that lists the cartridges that were created; they are real and usable.

DELETE /api/cartridges/{label}

admin Destructive confirm: the label

Erases the cartridge’s data and removes it from the library. Copies in the bucket are not touched: the label can be minted again and its generations imported. Refused while the cartridge is in a drive or any job references it.

curl -sk -X DELETE https://appliance:8443/api/cartridges/OVB006L5 \
  -H "Authorization: Bearer $OVTL_KEY" -H 'Content-Type: application/json' \
  -d '{"confirm":"OVB006L5"}'

{"ok": true, "label": "OVB006L5"}

POST /api/cartridges/{label}/export

admin

Queues an export: the cartridge is tarred deterministically, split into chunks, compressed, uploaded with a resumable per-chunk ledger, and verified remote-side; the manifest lands last as the completion marker. The cartridge must be idle and out of any drive when the job reaches quiescing.

Body field	Type	Notes
`remote_id`	int	Required.
`generation`	string	Optional `YYYYMMDDTHHMMSSZ`. Omit to let the export mint a new one.

curl -sk -X POST https://appliance:8443/api/cartridges/OVB001L5/export \
  -H "Authorization: Bearer $OVTL_KEY" -H 'Content-Type: application/json' \
  -d '{"remote_id":1}'

Returns 201 with the job in state detected. Watch it on the jobs page or the events stream. 409 while a graceful restart is draining.

POST /api/cartridges/{label}/evict

admin Destructive

Queues an eviction: the job re-verifies the bucket copy of the named generation, then deletes the cartridge’s local data, leaving a labelled stub. A host that mounts the stub gets a media error and the volume reads as unlabelled; nothing overwrites it. Import the generation back before any restore.

Body field	Type	Notes
`remote_id`	int	Required.
`generation`	string	The generation to verify against.

Returns 201 with the job in state queued.

POST /api/cartridges/{label}/import

admin

Queues an import from the bucket. Two shapes:

Same-system re-import of an evicted stub: give remote_id and generation only. The data streams back, is verified, and is swapped into place; the result is byte-identical.
Import into a library (a cartridge from another appliance, or one that no longer exists here): also give system_name (the exporting appliance’s name) and target_library. The cartridge is created in that library through its import/export slot, label preserved. target_library may be omitted when exactly one library is live.

Body field	Type	Notes
`remote_id`	int	Required.
`generation`	string	Required. Must exist in the catalog for that remote; rebuild the catalog first if not.
`system_name`	string	Required for an import into a library.
`target_library`	int	A live library id.

curl -sk -X POST https://appliance:8443/api/cartridges/OVB001L5/import \
  -H "Authorization: Bearer $OVTL_KEY" -H 'Content-Type: application/json' \
  -d '{"remote_id":1,"generation":"20260831T001507Z","system_name":"demo01","target_library":10}'

Returns 201 with the job in state queued. 409 if a cartridge with that label already exists here and is not an evicted stub: two cartridges cannot share a barcode. 400 if the target library is not live, the generation is not in the catalog, or system_name is missing.