> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memvid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Complete REST API reference for Memvid cloud service

Access Memvid via HTTP REST API. All endpoints require authentication with an API key.

## Base URL

```
https://api.memvid.com
```

## Authentication

All protected endpoints require an API key in one of two ways:

**Option 1: Bearer Token**

```bash theme={null}
Authorization: Bearer mv2_your_api_key_here
```

**Option 2: X-API-Key Header**

```bash theme={null}
X-API-Key: mv2_your_api_key_here
```

<Info>
  **Memory-scoped keys** restrict access to a single memory and its documents/jobs.
</Info>

***

## Health & Readiness

### `GET /health`

Check API health status.

```bash theme={null}
curl https://api.memvid.com/health
```

```json theme={null}
{
  "status": "healthy",
  "version": "1.4.9",
  "timestamp": "2026-03-11T12:00:00Z"
}
```

### `GET /health/ready`

Check MongoDB and S3 connectivity. Returns 503 if degraded.

```bash theme={null}
curl https://api.memvid.com/health/ready
```

***

## Memories

A memory is a searchable container for your documents.

### `POST /v1/memories` — Create

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Papers",
    "description": "ML papers from 2024"
  }'
```

| Field         | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| `name`        | string | Yes      | 1-1000 characters             |
| `description` | string | No       | Up to 5000 characters         |
| `projectId`   | string | No       | Assign to existing project    |
| `projectName` | string | No       | Auto-create project if needed |

### `GET /v1/memories` — List All

```bash theme={null}
curl https://api.memvid.com/v1/memories \
  -H "Authorization: Bearer mv2_YOUR_KEY"
```

### `GET /v1/memories/:id` — Get One

```bash theme={null}
curl https://api.memvid.com/v1/memories/{MEMORY_ID} \
  -H "Authorization: Bearer mv2_YOUR_KEY"
```

### `DELETE /v1/memories/:id` — Delete

Deletes the memory, all its documents, and its `.mv2` file from S3.

```bash theme={null}
curl -X DELETE https://api.memvid.com/v1/memories/{MEMORY_ID} \
  -H "Authorization: Bearer mv2_YOUR_KEY"
```

Returns `204 No Content` on success.

***

## Documents

### `POST /v1/memories/:id/documents` — Add Documents

**Option A: Upload a file**

Supports PDF, DOCX, DOC, XLSX, PPTX, PPT, TXT, CSV, TSV, LOG, JSON, JSONL/NDJSON, HTML, XML, Markdown.

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/documents \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -F "file=@./report.pdf"
```

**Option B: JSON text**

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/documents \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "title": "Meeting Notes",
        "text": "We decided on React for the frontend and Postgres for the database.",
        "tags": ["meeting", "architecture"]
      }
    ]
  }'
```

**Option C: Ingest from URL**

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/documents \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'
```

**Ingestion options:**

Pass these in an `options` object alongside `documents` or `url`:

| Option           | Type   | Default                  | Description                                           |
| ---------------- | ------ | ------------------------ | ----------------------------------------------------- |
| `async`          | bool   | `false`                  | Force async processing via background worker          |
| `deduplicate`    | bool   | `false`                  | Skip documents with similar content                   |
| `enableOcr`      | bool   | `true`                   | Auto-OCR scanned/image-only PDF pages using vision AI |
| `ocrMaxPages`    | int    | `50`                     | Max pages to OCR per document (max 200)               |
| `storeSource`    | bool   | `false`                  | Store original file in S3 for later retrieval         |
| `embeddingModel` | string | `text-embedding-3-small` | Embedding model (pinned on first ingest)              |

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/documents \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -F "file=@./scanned-contract.pdf" \
  -F 'options={"enableOcr": true, "ocrMaxPages": 100}'
```

**Response codes:**

| Code  | Meaning                                                                   |
| ----- | ------------------------------------------------------------------------- |
| `200` | Document processed synchronously. Ready to search.                        |
| `202` | Document routed to async worker. Response includes `jobId` and `pollUrl`. |

<Info>
  **Scanned PDFs:** PDFs containing scanned images are automatically detected and processed with OCR. Small scanned PDFs (5 or fewer image pages) are handled synchronously. Larger scanned PDFs are automatically routed to the background worker and return `202` — poll the `jobId` to track progress.
</Info>

| Constraint                  | Value               |
| --------------------------- | ------------------- |
| Max file size               | 100 MB              |
| Async threshold             | 2 MB (auto)         |
| Scanned PDF async threshold | 5+ image-only pages |
| Max URL download            | 100 MB              |

### `GET /v1/memories/:id/documents` — List Documents

```bash theme={null}
curl https://api.memvid.com/v1/memories/{MEMORY_ID}/documents \
  -H "Authorization: Bearer mv2_YOUR_KEY"
```

### `DELETE /v1/memories/:id/documents/:doc_id` — Delete One

```bash theme={null}
curl -X DELETE \
  https://api.memvid.com/v1/memories/{MEMORY_ID}/documents/{DOC_ID} \
  -H "Authorization: Bearer mv2_YOUR_KEY"
```

Returns `204 No Content`.

***

## Search

### `POST /v1/memories/:id/find` — Hybrid Search

Semantic + keyword hybrid search with reranking.

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/find \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what database are we using",
    "topK": 5
  }'
```

| Field               | Type   | Default  | Description                                        |
| ------------------- | ------ | -------- | -------------------------------------------------- |
| `query`             | string | required | Search query                                       |
| `topK`              | int    | 10       | Number of results                                  |
| `options.mode`      | string | auto     | `"hybrid"`, `"semantic"`, `"lexical"`, or `"auto"` |
| `options.limit`     | int    | 10       | Number of results                                  |
| `options.highlight` | bool   | false    | Wrap matches in `<mark>` tags                      |

### `POST /v1/memories/:id/search` — Simple Search

Simplified search with sensible defaults.

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/search \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "database choice", "limit": 3}'
```

***

## Ask (RAG)

### `POST /v1/memories/:id/ask` — Ask a Question

Retrieval-augmented generation: searches your memory and generates an answer with sources.

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/ask \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What tech stack did we decide on?",
    "options": {
      "model": "gpt-4o-mini",
      "maxContextChunks": 15,
      "includeSources": true
    }
  }'
```

| Field                      | Type   | Default   | Description               |
| -------------------------- | ------ | --------- | ------------------------- |
| `question`                 | string | required  | Your question             |
| `options.model`            | string | `"gpt-4"` | LLM model ID              |
| `options.maxContextChunks` | int    | 10        | Max chunks fed to the LLM |
| `options.includeSources`   | bool   | false     | Return source documents   |

### `POST /v1/ask-once` — One-Shot Q\&A (No Memory)

Ask a question on content you provide directly. Nothing is persisted.

```bash theme={null}
curl -X POST https://api.memvid.com/v1/ask-once \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Summarize this",
    "content": "Your raw text here...",
    "model": "gpt-4o-mini"
  }'
```

***

## Structured Extraction

### `POST /v1/memories/:id/extract` — Extract Structured Data

Pull structured fields from your documents using a schema you define.

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/extract \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sections": [
      {
        "id": "parties",
        "name": "Contract Parties",
        "fields": [
          {"key": "buyer", "label": "Buyer Name"},
          {"key": "seller", "label": "Seller Name"},
          {"key": "effective_date", "label": "Effective Date", "data_type": "date"}
        ]
      }
    ],
    "context": "This is a commercial real estate lease agreement"
  }'
```

| Field                           | Type   | Required | Description                             |
| ------------------------------- | ------ | -------- | --------------------------------------- |
| `sections`                      | array  | Yes      | At least one section                    |
| `sections[].id`                 | string | Yes      | Unique section identifier               |
| `sections[].name`               | string | Yes      | Display name                            |
| `sections[].fields[].key`       | string | Yes      | Field identifier                        |
| `sections[].fields[].label`     | string | Yes      | Used as the search query                |
| `sections[].fields[].data_type` | string | No       | Type hint (e.g. `"date"`, `"currency"`) |

***

## OCR (Image-to-Text)

### `POST /v1/memories/:id/ocr` — OCR & Auto-Ingest

Extract text from images using vision LLMs, then auto-ingest the result into the memory.

**Option A: Multipart file upload**

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/ocr \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -F "file=@./screenshot.png" \
  -F "mode=fast"
```

**Option B: JSON with base64**

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/ocr \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageBase64": "/9j/4AAQ...",
    "options": {
      "mode": "accurate",
      "languageHints": ["en", "es"]
    }
  }'
```

| Limit               | Value                           |
| ------------------- | ------------------------------- |
| Max image file size | 20 MB                           |
| Max base64 payload  | 27 MB                           |
| Supported formats   | PNG, JPEG, WebP, GIF, TIFF, BMP |

***

## Projects

Projects group memories together.

### `POST /v1/projects` — Create

```bash theme={null}
curl -X POST https://api.memvid.com/v1/projects \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q1 Research"}'
```

### `GET /v1/projects` — List All

```bash theme={null}
curl https://api.memvid.com/v1/projects \
  -H "Authorization: Bearer mv2_YOUR_KEY"
```

### `GET /v1/projects/:id` — Get One

```bash theme={null}
curl https://api.memvid.com/v1/projects/{PROJECT_ID} \
  -H "Authorization: Bearer mv2_YOUR_KEY"
```

### `PUT /v1/projects/:id` — Update

```bash theme={null}
curl -X PUT https://api.memvid.com/v1/projects/{PROJECT_ID} \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q2 Research"}'
```

### `DELETE /v1/projects/:id` — Delete

```bash theme={null}
curl -X DELETE https://api.memvid.com/v1/projects/{PROJECT_ID} \
  -H "Authorization: Bearer mv2_YOUR_KEY"
```

***

## Account

### `GET /v1/account` — Account Info & Usage

Returns your organization details, plan limits, and current usage.

```bash theme={null}
curl https://api.memvid.com/v1/account \
  -H "Authorization: Bearer mv2_YOUR_KEY"
```

***

## Jobs

Documents that exceed the sync processing threshold are handled by a background worker. The add documents endpoint returns `202` with a `jobId` you can poll.

**What triggers async processing:**

* Files larger than 2 MB
* Scanned PDFs with more than 5 image-only pages (OCR required)
* Explicit `options.async: true`

### `GET /v1/jobs/:id` — Check Job Status

```bash theme={null}
curl https://api.memvid.com/v1/jobs/{JOB_ID} \
  -H "Authorization: Bearer mv2_YOUR_KEY"
```

```json theme={null}
{
  "id": "69b17fa2dacb7d03814fb49b",
  "memoryId": "69b03bb1a62c98d88403ceca",
  "jobType": "documentingestion",
  "status": "completed",
  "progress": 100,
  "message": "Finalizing...",
  "result": {
    "documentsAdded": 1,
    "chunksCreated": 74,
    "documentIds": ["69b180c9b225e959e6b1b0a1"],
    "totalBytes": 1318799,
    "processingMs": 295779
  },
  "createdAt": "2026-03-11T14:43:46.602Z",
  "startedAt": "2026-03-11T14:43:46.616Z",
  "completedAt": "2026-03-11T14:48:42.408Z"
}
```

**Job statuses:** `pending` → `processing` → `completed`, `failed`, or `partial`

| Field       | Description                                                       |
| ----------- | ----------------------------------------------------------------- |
| `status`    | Current job state                                                 |
| `progress`  | 0–100 percentage                                                  |
| `message`   | Human-readable progress description                               |
| `result`    | Present when completed — includes document IDs and chunk count    |
| `error`     | Present when failed — error description                           |
| `isPartial` | `true` if job completed with partial results (e.g. quota reached) |

<Tip>
  Poll every 5–10 seconds. Scanned PDFs typically take 2–8 minutes depending on page count. Text-only large files usually finish in under a minute.
</Tip>

### `GET /v1/jobs` — List Jobs

```bash theme={null}
curl "https://api.memvid.com/v1/jobs?status=processing&limit=10" \
  -H "Authorization: Bearer mv2_YOUR_KEY"
```

| Query Parameter | Type   | Default | Description                                                       |
| --------------- | ------ | ------- | ----------------------------------------------------------------- |
| `status`        | string | —       | Filter by status (`pending`, `processing`, `completed`, `failed`) |
| `memoryId`      | string | —       | Filter by memory                                                  |
| `limit`         | int    | 20      | Max results (1–100)                                               |

***

## Corrections

Store priority-boosted corrections that surface first in search results.

### `POST /v1/memories/:id/correct` — Add Single Correction

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/correct \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "statement": "The capital of France is Paris, not London.",
    "topics": ["geography", "France"],
    "boost": 2.0
  }'
```

### `POST /v1/memories/:id/corrections` — Add Multiple Corrections

```bash theme={null}
curl -X POST https://api.memvid.com/v1/memories/{MEMORY_ID}/corrections \
  -H "Authorization: Bearer mv2_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "corrections": [
      {
        "statement": "Water boils at 100°C at sea level.",
        "topics": ["science", "physics"]
      }
    ]
  }'
```

***

## Endpoints Summary

| Method | Endpoint                             | Description                 |
| ------ | ------------------------------------ | --------------------------- |
| GET    | `/health`                            | Health check                |
| GET    | `/health/ready`                      | Readiness check             |
| GET    | `/v1/account`                        | Account info, usage, limits |
| POST   | `/v1/memories`                       | Create a memory             |
| GET    | `/v1/memories`                       | List memories               |
| GET    | `/v1/memories/:id`                   | Get memory details          |
| DELETE | `/v1/memories/:id`                   | Delete memory               |
| POST   | `/v1/memories/:id/documents`         | Add documents               |
| GET    | `/v1/memories/:id/documents`         | List documents              |
| DELETE | `/v1/memories/:id/documents/:doc_id` | Delete one document         |
| POST   | `/v1/memories/:id/find`              | Hybrid search               |
| POST   | `/v1/memories/:id/search`            | Simple search               |
| POST   | `/v1/memories/:id/ask`               | RAG question answering      |
| POST   | `/v1/ask-once`                       | One-shot Q\&A (no memory)   |
| POST   | `/v1/memories/:id/extract`           | Structured data extraction  |
| POST   | `/v1/memories/:id/ocr`               | OCR & auto-ingest           |
| POST   | `/v1/memories/:id/correct`           | Add single correction       |
| POST   | `/v1/memories/:id/corrections`       | Add multiple corrections    |
| GET    | `/v1/jobs/:id`                       | Check async job status      |
| GET    | `/v1/jobs`                           | List jobs                   |
| POST   | `/v1/projects`                       | Create project              |
| GET    | `/v1/projects`                       | List projects               |
| GET    | `/v1/projects/:id`                   | Get project                 |
| PUT    | `/v1/projects/:id`                   | Update project              |
| DELETE | `/v1/projects/:id`                   | Delete project              |

***

## Supported File Types

**Documents:** PDF (including scanned), DOCX, DOC, XLSX, PPTX, PPT, TXT, CSV, TSV, LOG, JSON, JSONL/NDJSON, HTML, XML, Markdown

**Images (OCR endpoint):** PNG, JPEG, WebP, GIF, TIFF, BMP

<Info>
  Scanned PDFs are automatically detected and processed with OCR — no special configuration needed. Legacy formats (`.doc`, `.ppt`) are converted through the same pipeline as their modern counterparts.
</Info>

***

## Limits

| Limit                | Free Plan | Starter Plan  |
| -------------------- | --------- | ------------- |
| Storage              | 50 MB     | 25 GB         |
| Memories             | 1         | 5             |
| Queries              | Unlimited | 250,000/month |
| Max file size        | 100 MB    | 100 MB        |
| Max image size (OCR) | 20 MB     | 20 MB         |
| Request timeout      | 5 minutes | 10 minutes    |
| Request body limit   | 150 MB    | 150 MB        |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/python-sdk/overview">
    Use the Python SDK for easier integration
  </Card>

  <Card title="Node.js SDK" icon="node-js" href="/node-sdk/overview">
    TypeScript-first SDK with full types
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/index">
    Command-line interface
  </Card>

  <Card title="Error Reference" icon="circle-exclamation" href="/errors/reference">
    Error codes and solutions
  </Card>
</CardGroup>