What APIs Does Supermemory Expose? Complete Reference to v3 and v4 Endpoints

Supermemory exposes a strictly-typed, versioned HTTP API split between /v3 for core CRUD operations and /v4 for advanced search and memory insertion, with all schemas defined centrally in packages/lib/api.ts using Zod and @better-fetch.

Supermemory is an open-source memory layer for AI applications that provides a comprehensive REST API for document ingestion, semantic search, and external integrations. The API surface is organized into two primary versions—/v3 handles document and project management while /v4 powers search and direct memory operations—with all endpoints sharing a common base URL of https://api.supermemory.ai (configurable via NEXT_PUBLIC_BACKEND_URL).

API Versioning and Architecture

Supermemory maintains two active API versions that serve distinct functional purposes. The v3 endpoints manage traditional resource lifecycle operations including documents, projects, connections, and user settings, while the v4 endpoints specialize in semantic search and immediate memory insertion without document processing.

According to the source code in packages/lib/api.ts, the entire route surface is defined using @better-fetch schemas that bind each HTTP route to its corresponding Zod validation schemas for request and response payloads. This ensures type safety across the entire stack, from frontend hooks like use-document-mutations.ts in apps/web/hooks/ to the backend handlers.

Core API Endpoint Categories

Document and Memory Management (v3)

The v3 endpoints provide comprehensive CRUD capabilities for documents and the memories they generate, utilizing schemas such as MemoryAddSchema, ListMemoriesResponseSchema, DocumentsWithMemoriesQuerySchema, and BulkDeleteMemoriesSchema.

Key operations include:

• POST /v3/documents — Ingest a new document by URL or content using MemoryAddSchema validation
• POST /v3/documents/list — List processed documents with pagination and status filtering
• POST /v3/documents/documents/by-ids — Retrieve specific documents by ID array using DocumentsWithMemoriesQuerySchema
• GET /v3/documents/:id — Fetch a single document's details
• DELETE /v3/documents/:id — Remove an individual document
• DELETE /v3/documents/bulk — Batch delete documents validated by BulkDeleteMemoriesSchema

Semantic Search and Direct Memory Insertion (v4)

The v4 version introduces AI-native operations that bypass traditional document processing pipelines.

Semantic search via POST /v4/search accepts payloads validated by SearchRequestSchema, supporting hybrid search modes with chunkThreshold relevance controls and complex metadata filtering. Responses conform to SearchResponseSchema.

Direct memory creation via POST /v4/memories allows inserting memories immediately using MemoryAddSchema-style payloads, enabling storage of short facts or user preferences without requiring full document ingestion.

External Connections and Integrations

The connections API manages OAuth integrations with Google Drive, Notion, and OneDrive through ConnectionResponseSchema validation.

Available routes include:

• POST /v3/connections/:provider — Initiate a new third-party connection
• GET /v3/connections — List all active connections
• GET /v3/connections/:connectionId — Retrieve specific connection details
• DELETE /v3/connections/:connectionId — Terminate an integration
• POST /v3/connections/list — Filter and list connections with pagination

Projects and Container Management

Projects act as logical containers for organizing documents within Supermemory.

• GET /v3/projects — List all projects (returns ProjectSchema array)
• POST /v3/projects — Create a new project validated by CreateProjectSchema
• DELETE /v3/projects/:projectId — Remove a project using DeleteProjectSchema

Container tags, representing user-owned spaces or namespaces, can be enumerated via GET /v3/container-tags/list which returns data structured by ListContainerTagsResponseSchema.

Analytics, Settings, and Utilities

Analytics endpoints provide usage telemetry through three specialized routes:

• GET /v3/analytics/chat using AnalyticsChatResponseSchema
• GET /v3/analytics/memory using AnalyticsMemoryResponseSchema
• GET /v3/analytics/usage using AnalyticsUsageResponseSchema

Settings management uses SettingsRequestSchema and SettingsResponseSchema for the GET /v3/settings and PATCH /v3/settings operations, enabling retrieval and modification of user preferences.

Additional utility endpoints include GET /v3/mcp/has-login for Model Context Protocol session checking, GET /v3/waitlist/status returning WaitlistStatusResponseSchema, and POST /v3/emails/welcome/pro for transactional email triggers.

Schema Validation and Implementation Details

All API contracts are enforced using Zod schemas located in packages/validation/api.ts and referenced throughout packages/lib/api.ts. The @better-fetch library provides the $fetch client consumed by frontend hooks such as use-document-mutations.ts and use-memories-usage.ts, ensuring end-to-end type safety between the API specification and client implementation.

The human-readable API documentation is maintained in skills/supermemory/references/api-reference.md, which mirrors the machine-readable schema definitions in packages/lib/api.ts.

Practical Usage Examples

The following cURL examples demonstrate common operations against the Supermemory API using Bearer token authentication. The base URL defaults to https://api.supermemory.ai/v3 for v3 endpoints and https://api.supermemory.ai/v4 for v4 endpoints.

Ingest a Document via URL

curl -X POST https://api.supermemory.ai/v3/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "https://example.com/article",
    "containerTag": "user_123",
    "entityContext": "Technical article about API design",
    "metadata": {
      "source": "blog",
      "category": "technical",
      "tags": ["api","design"]
    }
  }'

List Documents with Pagination

curl -X POST https://api.supermemory.ai/v3/documents/list \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":20,"page":1,"status":"done","containerTags":["user_123"]}'

Delete a Specific Document

curl -X DELETE https://api.supermemory.ai/v3/documents/DOCUMENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Perform Semantic Search

curl -X POST https://api.supermemory.ai/v4/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I authenticate users?",
    "searchMode": "hybrid",
    "chunkThreshold": 0.5,
    "filters": {
      "metadata": { "type": "documentation", "category": "security" },
      "numeric": { "rating": { "$gte": 4.0 } }
    }
  }'

Insert Direct Memories

curl -X POST https://api.supermemory.ai/v4/memories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "containerTag": "user_123",
    "memories": [
      { "content": "User prefers dark mode", "isStatic": true },
      { "content": "User completed the React tutorial", "isStatic": false }
    ]
  }'

List Container Tags

curl -X GET https://api.supermemory.ai/v3/container-tags/list \
  -H "Authorization: Bearer YOUR_API_KEY"

Retrieve Usage Analytics

curl -X GET "https://api.supermemory.ai/v3/analytics/usage?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

Summary

• Supermemory exposes two API versions: /v3 for core CRUD operations (documents, projects, connections) and /v4 for semantic search and direct memory insertion
• All endpoints are strictly typed using Zod schemas defined in packages/validation/api.ts and bound to routes in packages/lib/api.ts via @better-fetch
• The API requires Bearer token authentication and defaults to https://api.supermemory.ai (override via NEXT_PUBLIC_BACKEND_URL)
• Key schemas include MemoryAddSchema for document creation, SearchRequestSchema for querying, and ConnectionResponseSchema for integrations
• Frontend consumption patterns are demonstrated in apps/web/hooks/use-document-mutations.ts and apps/web/hooks/use-memories-usage.ts

Frequently Asked Questions

What is the difference between v3 and v4 endpoints in Supermemory?

The v3 endpoints handle traditional resource management—including documents, projects, external connections, and user settings—while the v4 endpoints specialize in AI-native operations like semantic search (POST /v4/search) and direct memory creation (POST /v4/memories) without requiring document ingestion. According to the source code in packages/lib/api.ts, v4 specifically targets workflows that need immediate memory insertion or hybrid vector search capabilities using schemas like SearchRequestSchema and SearchResponseSchema.

How does Supermemory validate API requests and responses?

Supermemory uses Zod schemas defined in packages/validation/api.ts to enforce type safety on all API contracts. In packages/lib/api.ts, these schemas are bound to HTTP routes using the @better-fetch library, creating a centralized apiSchema object that validates requests against schemas such as MemoryAddSchema for documents and SettingsRequestSchema for user preferences. This ensures that frontend hooks like use-document-mutations.ts and backend handlers operate on strictly typed data structures.

Can I self-host the Supermemory API?

Yes, Supermemory is fully open-source and designed for self-hosting. The API base URL defaults to https://api.supermemory.ai/v3 but can be overridden using the NEXT_PUBLIC_BACKEND_URL environment variable, as configured in the $fetch.baseURL setting within packages/lib/api.ts. This allows you to point the frontend to your own instance when running the infrastructure locally or on private servers.

What authentication method does the Supermemory API require?

All Supermemory API endpoints require Bearer token authentication passed via the Authorization header in the format Authorization: Bearer YOUR_API_KEY. The API examples in the repository documentation demonstrate this pattern consistently across v3 and v4 endpoints, and frontend hooks like use-document-mutations.ts implement this header automatically when making requests to endpoints such as POST /v3/documents or DELETE /v3/documents/:id.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}