Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vectorize-io/hindsight/llms.txt

Use this file to discover all available pages before exploring further.

Documents are containers for retained content. Every piece of content you retain is associated with a document — either one you name with a document_id or one Hindsight creates automatically with a random UUID. Documents give you traceability (knowing which source a memory came from), update semantics (re-retaining with the same document_id replaces the old content), and bulk deletion (removing a document removes all memories extracted from it). When you retain content, Hindsight also stores the original text chunks that were used for fact extraction. These chunks are available on demand when you need the raw source text alongside the extracted facts.
Use include_chunks=True in your recall calls to get the original text chunks alongside fact results when agents need surrounding context.

​
Retain with a document ID

Associate retained content with a stable document ID by including document_id in your retain request. Hindsight upserts the document — if a document with that ID already exists, it and all its memories are deleted before the new content is processed. 
curl -X POST "https://your-hindsight-host/v1/default/banks/my-bank/retain" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "content": "Alice presented the Q4 roadmap. The team agreed to prioritize the search feature.",
        "document_id": "meeting-2024-03-15",
        "context": "team meeting"
      }
    ]
  }'

​
Get a document

GET /v1/{tenant}/banks/{bank_id}/documents/{document_id}
Retrieves a document’s original text, metadata, and memory statistics. Useful for expanding document context after a recall operation returns memories with document references.

​
Response fields

​
id
string
required
The document ID.
​
bank_id
string
required
The memory bank this document belongs to.
​
original_text
string
required
The full original text retained into this document.
​
content_hash
string
required
Hash of the content, used for delta retain to detect unchanged chunks.
​
memory_unit_count
integer
required
Total number of memory facts extracted from this document.
​
nodes_by_fact_type
object
required
Breakdown of extracted facts by type.
​
tags
string[]
Tags attached to this document.
​
created_at
string
required
ISO 8601 creation timestamp.
​
updated_at
string
required
ISO 8601 last-updated timestamp.

​
Example

curl "https://your-hindsight-host/v1/default/banks/my-bank/documents/meeting-2024-03-15" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

​
List documents

GET /v1/{tenant}/banks/{bank_id}/documents
Lists documents in a bank with optional filtering by ID substring and tags.

​
Query parameters

​
q
string
Case-insensitive substring match on document ID. "report" matches "report-2024", "annual-report", and so on.
​
tags
string[]
Filter by document tags. Accepts multiple values.
​
tags_match
string
default:"any_strict"
How to match tags.
ModeBehaviour
any_strict (default)Document must have at least one of the specified tags. Untagged docs excluded.
anySame as any_strict but includes untagged documents.
all_strictDocument must have all specified tags. Untagged docs excluded.
allSame as all_strict but includes untagged documents.
​
limit
integer
default:"100"
Maximum number of documents to return.
​
offset
integer
default:"0"
Pagination offset.

​
Example

curl "https://your-hindsight-host/v1/default/banks/my-bank/documents?q=meeting&tags=team-a&limit=50" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

​
Update a document

PATCH /v1/{tenant}/banks/{bank_id}/documents/{document_id}
Updates mutable fields on an existing document without re-processing the content. Currently supports updating tags.
​
tags
string[]
New tags for the document. Replaces the existing tags entirely. Pass an empty list to remove all tags.
When tags change, any consolidated observations derived from the document’s memories are invalidated and queued for re-consolidation under the new tags.

​
Example

curl -X PATCH "https://your-hindsight-host/v1/default/banks/my-bank/documents/meeting-2024-03-15" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["team-a", "q1-2024"]}'

​
Delete a document

DELETE /v1/{tenant}/banks/{bank_id}/documents/{document_id}
Permanently removes the document and all memories extracted from it. Observations that were derived from those memories are also invalidated and queued for re-consolidation.
Deleting a document permanently removes all memories extracted from it. This action cannot be undone.

​
Example

curl -X DELETE "https://your-hindsight-host/v1/default/banks/my-bank/documents/meeting-2024-03-15" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

​
Upload files

POST /v1/{tenant}/banks/{bank_id}/files/retain
Upload files directly — Hindsight converts them to text and extracts memories automatically. File processing always runs asynchronously and returns operation IDs for tracking. Upload up to 10 files per request (max 100 MB total). Supported formats: PDF, DOCX, DOC, PPTX, PPT, XLSX, XLS, images (JPG, PNG, GIF — OCR), audio (MP3, WAV, FLAC — transcription), HTML, and plain text (TXT, MD, CSV, JSON, YAML).

​
Example

curl -X POST "https://your-hindsight-host/v1/default/banks/my-bank/files/retain" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -F "files=@/path/to/report.pdf" \
  -F 'request={"files_metadata": [{"context": "quarterly report"}]}'
Uploaded files are stored server-side. Configure storage via HINDSIGHT_API_FILE_STORAGE_TYPE — defaults to PostgreSQL, with S3, GCS, and Azure Blob Storage available for production.

Build docs developers (and LLMs) love

Get started for freeTalk to us