Hindsight Cloud Docs

Appearance

Convert files to memories ​

POST /v1/default/banks/{bank_id}/files/retain

Upload files (PDF, DOCX, etc.), convert them to markdown, and retain as memories.

This endpoint handles file upload, conversion, and memory creation in a single operation.

Features:

  • Supports PDF, DOCX, PPTX, XLSX, images (with OCR), audio (with transcription)
  • Automatic file-to-markdown conversion using pluggable parsers
  • Files stored in object storage (PostgreSQL by default, S3 for production)
  • Each file becomes a separate document with optional metadata/tags
  • Always processes asynchronously — returns operation IDs immediately

The system automatically:

  1. Stores uploaded files in object storage
  2. Converts files to markdown
  3. Creates document records with file metadata
  4. Extracts facts and creates memory units (same as regular retain)

Use the operations endpoint to monitor progress.

Request format: multipart/form-data with:

  • files: One or more files to upload
  • request: JSON string with FileRetainRequest model

Parser selection:

  • Set parser in the request body to override the server default for all files.
  • Set parser inside a files_metadata entry for per-file control.
  • Pass a list (e.g. ['iris', 'markitdown']) to define an ordered fallback chain — each parser is tried in sequence until one succeeds.
  • Falls back to the server default (HINDSIGHT_API_FILE_PARSER) if not specified.
  • Only parsers enabled on the server may be requested; others return HTTP 400.

Authentication required — include an Authorization: Bearer hsk_... header. See Authentication for details.

Path Parameters ​

NameTypeRequiredDescription
bank_idstringYes

Request Body ​

Content-Type: multipart/form-data

json
{
  "files": [
    "string"
  ],
  "request": "Request"
}

Example Request ​

bash
curl -X POST 'https://api.hindsight.vectorize.io/v1/default/banks/your-bank-id/files/retain' \
  -H 'Authorization: Bearer hsk_your_api_key'

Responses ​

200 — Successful Response

json
{
  "operation_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ]
}

422 — Validation Error

json
{
  "detail": [
    {
      "loc": [
        null
      ],
      "msg": "Message",
      "type": "Error Type",
      "input": null,
      "ctx": {},
      "url": "URL"
    }
  ]
}

Source: /v1/default/banks/{bank_id}/files/retain