BlobStore
Upload binary files (images, PDFs, models) to SapixDB and link them to strand records.
What you'll learn
- ✓POST /v1/blobs — upload with Content-Type: application/octet-stream
- ✓Response: blob_hash (permanent address), size_bytes
- ✓GET /v1/blobs/:hash — retrieve blob
- ✓GET /v1/blobs — list all blobs
- ✓DELETE /v1/blobs/:hash — delete blob (does not affect strand records)
- ✓Pattern: store blob_hash in record payload for reference
Upload a text file. Write a record to files agent with blob_hash, filename, uploaded_at. Retrieve the blob via the stored hash.
Interactive Walkthrough
What you'll learn
Upload binary files (images, PDFs, ML models) to SapixDB's blob storage and link them to records.
Upload a blob
curl -s -X POST http://localhost:7475/v1/blobs \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @/path/to/document.pdf \
| python3 -m json.toolResponse:
`json
{
"blob_hash": "9c4d2e7f...",
"size_bytes": 204800,
"content_type": "application/octet-stream"
}
`
Retrieve a blob
curl -s "http://localhost:7475/v1/blobs/9c4d2e7f..." \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-o downloaded.pdfLink a blob to a record
Store the blob_hash in the record payload:
curl -s -X POST http://localhost:7475/v1/agents/documents/write \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{
"payload": {
"title": "Q2 2026 Financial Report",
"blob_hash": "9c4d2e7f...",
"size_bytes": 204800,
"uploaded_by": "finance-agent"
}
}' | python3 -m json.toolList all blobs
curl -s http://localhost:7475/v1/blobs \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
| python3 -m json.toolDelete a blob
curl -s -X DELETE http://localhost:7475/v1/blobs/9c4d2e7f... \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY"Note: deleting a blob does not delete the strand record that referenced it. Store blob hashes in records before deleting.
Challenge
Upload a text file as a blob. Write a record to a files agent with blob_hash, filename, and uploaded_at. Retrieve the blob using the hash stored in the record.
---