REST API - Memvid

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

Authorization: Bearer mv2_your_api_key_here

Option 2: X-API-Key Header

X-API-Key: mv2_your_api_key_here

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

Health & Readiness

`GET /health`

Check API health status.

curl https://api.memvid.com/health

{
  "status": "healthy",
  "version": "1.4.9",
  "timestamp": "2026-03-11T12:00:00Z"
}

`GET /health/ready`

Check MongoDB and S3 connectivity. Returns 503 if degraded.

curl https://api.memvid.com/health/ready

Memories

A memory is a searchable container for your documents.

`POST /v1/memories` — Create

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

curl https://api.memvid.com/v1/memories \
  -H "Authorization: Bearer mv2_YOUR_KEY"

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

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.

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.

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

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

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)

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`.

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.

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

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

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.

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.

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.

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.

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.

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

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

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

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

curl https://api.memvid.com/v1/projects \
  -H "Authorization: Bearer mv2_YOUR_KEY"

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

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

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

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

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.

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

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

{
  "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)

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.

`GET /v1/jobs` — List Jobs

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

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

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

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.

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

Python SDK

Use the Python SDK for easier integration

Node.js SDK

TypeScript-first SDK with full types

CLI Reference

Command-line interface

Error Reference

Error codes and solutions

API Reference

​Base URL

​Authentication

​Health & Readiness

​GET /health

​GET /health/ready

​Memories

​POST /v1/memories — Create

​GET /v1/memories — List All

​GET /v1/memories/:id — Get One

​DELETE /v1/memories/:id — Delete

​Documents

​POST /v1/memories/:id/documents — Add Documents

​GET /v1/memories/:id/documents — List Documents

​DELETE /v1/memories/:id/documents/:doc_id — Delete One

​Search

​POST /v1/memories/:id/find — Hybrid Search

​POST /v1/memories/:id/search — Simple Search

​Ask (RAG)

​POST /v1/memories/:id/ask — Ask a Question

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

​Structured Extraction

​POST /v1/memories/:id/extract — Extract Structured Data

​OCR (Image-to-Text)

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

​Projects

​POST /v1/projects — Create

​GET /v1/projects — List All

​GET /v1/projects/:id — Get One

​PUT /v1/projects/:id — Update

​DELETE /v1/projects/:id — Delete

​Account

​GET /v1/account — Account Info & Usage

​Jobs

​GET /v1/jobs/:id — Check Job Status

​GET /v1/jobs — List Jobs

​Corrections

​POST /v1/memories/:id/correct — Add Single Correction

​POST /v1/memories/:id/corrections — Add Multiple Corrections

​Endpoints Summary

​Supported File Types

​Limits

​Next Steps

Python SDK

Node.js SDK

CLI Reference

Error Reference

Base URL

Authentication

Health & Readiness

`GET /health`

`GET /health/ready`

Memories

`POST /v1/memories` — Create

`GET /v1/memories` — List All

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

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

Documents

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

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

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

Search

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

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

Ask (RAG)

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

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

Structured Extraction

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

OCR (Image-to-Text)

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

Projects

`POST /v1/projects` — Create

`GET /v1/projects` — List All

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

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

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

Account

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

Jobs

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

`GET /v1/jobs` — List Jobs

Corrections

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

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

Endpoints Summary

Supported File Types

Limits

Next Steps