Skip to content
HiveGuard

hiveguard items

items upload

Upload ground-truth items from a JSONL or CSV file.

Terminal window
hiveguard items upload FILE

Requires an API key.

FILE can be .jsonl or .csv. Items are sent in batches of 1,000 with a progress bar.

JSONL format

{"dataset_id": "UUID", "data_ref": "https://example.com/img.jpg", "modality": "image"}
{"dataset_id": "UUID", "data_ref": "https://example.com/clip.wav", "modality": "audio"}

CSV format

dataset_id,data_ref,modality
00000000-0000-0000-0000-000000000001,https://example.com/img.jpg,image

Validation

Before sending, the CLI validates each item:

  • dataset_id must be a valid UUID
  • modality must be image, text, or audio
  • CSV files must have all required columns (dataset_id, data_ref, modality)

Invalid items are rejected with the line number:

Error on line 5: invalid UUID "not-a-uuid"

Large files

For files larger than 1,000 items, the CLI automatically batches:

Uploading 5001 items in 6 batches...
 ✓ Batch 1/6 — 1000 created
 ✓ Batch 2/6 — 1000 created
 ...
Total: 5001 items created

If a batch fails (e.g., 422 from the server), the error is shown and remaining batches continue.

items list

List all items visible to your API key.

Terminal window
hiveguard items list
hiveguard items list --output json

Output columns: id, dataset_id, data_ref, modality, created_at.

Results are paginated automatically — all pages are fetched and combined.