---
title: "Convert files to memories"
method: POST
path: "/v1/default/banks/{bank_id}/files/retain"
tags: ["Files"]
---

# Convert files to memories

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

## Request

- Base URL: `https://hindsight.vectorize.io` (the document declares no server; this is the origin it was published from)
- URL: `https://hindsight.vectorize.io/v1/default/banks/{bank_id}/files/retain`
- Auth: none declared
- TypeScript: <https://skmtc.dev/vectorize/apis/hindsight-http-api/docs/v1/default/banks/:bank_id/files/retain/post.ts> (a function with typed inputs; its response is checked against the schema)

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 (parser-dependent 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.

## Path parameters

- `bank_id` string, required

## Headers

- `authorization` string, nullable

## Request body `multipart/form-data`

- BodyFileRetain
  - `files` string[], required: Files to upload and convert
  - `request` string, required: JSON string with FileRetainRequest model

## Response `200`

Successful Response

- FileRetainResponse: Response model for file upload endpoint.
  - `operation_ids` string[], required: Operation IDs for tracking file conversion operations. Use GET /v1/default/banks/{bank_id}/operations to list operations.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-04** `4fda98b75f63`: 1 warning
  - removed the optional property `detail/items/url` from the response with the `422` status
- **2026-05-15** `0d08f271b9db`: 3 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
  - added the optional property `detail/items/url` to the response with the `422` status

[Operation history](https://skmtc.dev/vectorize/apis/hindsight-http-api/changes/v1/default/banks/:bank_id/files/retain/post.md)

---

[API](https://skmtc.dev/vectorize/apis/hindsight-http-api.md) - [All operations](https://skmtc.dev/vectorize/apis/hindsight-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vectorize/apis/hindsight-http-api/revisions/45e711cd0897?raw)