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.3.0",
  "timestamp": "2025-01-29T12: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, XLSX, PPTX, TXT, CSV, JSON, 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"}'

Constraint	Value
Max file size	100 MB
Async threshold	2 MB (auto)
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

Large file uploads are processed asynchronously and return a job_id.

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

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

Job statuses: pending, processing, completed, failed, partial

`GET /v1/jobs` — List Jobs

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

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, DOCX, XLSX, PPTX, TXT, CSV, JSON, HTML, XML, Markdown Images (OCR): PNG, JPEG, WebP, GIF, TIFF, BMP

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