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

> Explore the Supermemory API with this complete reference to v3 and v4 endpoints. Discover core CRUD operations and advanced search functionalities for your AI memory management.

- Repository: [supermemory/supermemory](https://github.com/supermemoryai/supermemory)
- Tags: api-reference
- Published: 2026-03-25

---

**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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts) and referenced throughout [`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/api.ts). The `@better-fetch` library provides the `$fetch` client consumed by frontend hooks such as [`use-document-mutations.ts`](https://github.com/supermemoryai/supermemory/blob/main/use-document-mutations.ts) and [`use-memories-usage.ts`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/references/api-reference.md), which mirrors the machine-readable schema definitions in [`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/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

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

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

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

```

### Perform Semantic Search

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

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

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

```

### Retrieve Usage Analytics

```bash
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`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts)** and bound to routes in **[`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/apps/web/hooks/use-document-mutations.ts)** and **[`apps/web/hooks/use-memories-usage.ts`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts) to enforce type safety on all API contracts. In [`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/use-document-mutations.ts) implement this header automatically when making requests to endpoints such as `POST /v3/documents` or `DELETE /v3/documents/:id`.