Upload and retrieve raw binary content (images, audio, PDFs).

Blobs

Blobs are content-addressed binary objects. Reference them from an experience envelope via content.kind = "blob_ref" or as media[].blob_id inside a message.

Content negotiation

Blob endpoints use Content-Type to describe the request body (on upload) and the response body (on download). They do not look at Accept. Concretely:

  • Upload (POST /v1/blobs): send the bytes raw with Content-Type: <mime>. Do not wrap them in JSON / multipart / base64 — the body is the file. The server stores the declared MIME alongside the bytes.
  • Download (GET /v1/blobs/{id}): the response Content-Type echoes whatever was declared at upload. Accept headers are ignored — there is no transcoding. If you uploaded image/png, you always get image/png back.

POST /v1/blobs with a JSON-or-multipart body returns 415 unsupported_media_type.

POST /v1/blobs

Upload a blob.

POST /v1/blobs
Content-Type: image/png
Content-Length: 245892

<binary bytes>

Response

{
  "blob_id":      "blob_01HX...",
  "size_bytes":   245892,
  "content_type": "image/png",
  "sha256":       "..."
}

Blobs are content-deduplicated by SHA-256 — uploading the same bytes twice returns the same blob_id cheaply.

End-to-end: ingest a PDF

Upload the raw bytes, then reference the returned blob_id from an experience envelope:

# 1. Upload — the body IS the file, Content-Type declares its MIME.
BLOB_ID=$(curl -s -X POST https://api-v1.cortexdb.ai/v1/blobs \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "X-Cortex-Actor: $CORTEX_ACTOR" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf | jq -r .blob_id)

# 2. Reference it from an experience.
curl -X POST "https://api-v1.cortexdb.ai/v1/experience?wait=indexed" \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "X-Cortex-Actor: $CORTEX_ACTOR" \
  -H "Content-Type: application/json" \
  -d "{
    \"scope\": \"org:acme/user:alice\",
    \"modality\": \"document\",
    \"content\": { \"kind\": \"blob_ref\", \"blob_id\": \"$BLOB_ID\" },
    \"context\": { \"labels\": [\"q1-report\"] }
  }"
Warning

Text extraction requires a configured document processor. The blob itself is always stored losslessly, but extracting searchable text from PDF/DOCX/PPTX/XLSX requires CORTEX_DOCUMENT_PROVIDER=tika (self-hosted Apache Tika, set CORTEX_DOCUMENT_API_URL) or =unstructured (Unstructured.io, plus CORTEX_DOCUMENT_API_URL/CORTEX_DOCUMENT_API_KEY). Without a provider, the built-in native parser handles plain text, Markdown, HTML, CSV, JSON and XML only — a PDF will be stored but will not become searchable text.

GET /v1/blobs/

Returns the raw bytes with the original Content-Type. Auth checked at the scope of the calling experience (a blob with no referencing experience is accessible only to the original uploader).

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: inline; filename="architecture-diagram.png"
Content-Length: 245892

<binary bytes>