Media & Blob Ingestion

Store documents, images, audio, and video as blobs, then let CortexDB extract searchable text asynchronously.

CortexDB can ingest binary content — PDFs and documents, images, audio, video — as blobs, then extract searchable text from them so the content becomes recallable memory. The pipeline is: upload the bytes → reference the blob from an experience → the server extracts text asynchronously.

1. Upload the bytes

curl -X POST http://localhost:3141/v1/blobs \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "X-Cortex-Actor: $CORTEX_ACTOR" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf
# → { "blob_id": "blob_01HX...", "size_bytes": 48211, "content_type": "application/pdf", "sha256": "..." }

The body is the file (any Content-Type is accepted as raw bytes). The size cap is 32 MiB — larger uploads return 413. See Blobs API for the full shape.

2. Reference the blob from an experience

curl -X POST http://localhost:3141/v1/experience \
  -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_01HX..." },
    "context": { "observed_at": "2026-05-15T10:42:00Z" }
  }'

3. Extraction runs asynchronously

wait=indexed does NOT wait for extraction

Text extraction (OCR/transcription/vision) runs on a separate async pipeline, taking roughly 60–90 s. ?wait=indexed blocks on BM25/HNSW indexing of the event, not on blob extraction — so a recall immediately after the write shows a raw [blob:…] placeholder until extraction completes, then the extracted text becomes searchable.

The processors

Each modality has its own extraction integration (configure via CORTEX_IMAGE_*, CORTEX_AUDIO_*, CORTEX_DOCUMENT_*, CORTEX_VIDEO_* — see Storage & Cluster):

Modality	Default extractor	Needs a key?
Document (PDF, docx, …)	Tika / unstructured	No (local Tika)
Image	GPT-4o vision	Yes (OpenAI)
Audio	Whisper	Yes (OpenAI)
Video	ffmpeg keyframes → image processor	Yes (for the frames)

Extraction is content-only — it runs regardless of enrichment

Blob extraction (Tika/vision/whisper) is part of content processing and runs even on a content-only self-hosted instance — it is not gated behind enrichment. Only the derived Facts/Beliefs layers need enrichment. See Self-hosting defaults.

Skipping ASR with a supplied transcript

For audio you already have a transcript for, pass it directly on the experience (transcript= in the SDK) — the server uses your text and skips the Whisper call, saving the ASR cost and latency.

Deleting a blob

curl -X DELETE http://localhost:3141/v1/blobs/blob_01HX... \
  -H "Authorization: Bearer $CORTEX_TOKEN" -H "X-Cortex-Actor: $CORTEX_ACTOR"

Blob storage backends (local / S3 / GCS / Azure) are configured under [blob_store] — see Storage & Cluster.