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

# API reference

> Interactive reference for the Supermemory HTTP API: ingest, search, profiles, memories, connectors and settings.

> [!WARNING]
>
> This is the legacy v3/v4 reference. v3 and v4 are deprecated and will be shut down on **December 31, 2026**. Move to [v5](https://supermemory.ai/docs/v5/api-reference/overview.md) before then. The [migration guide](https://supermemory.ai/docs/migration/api-v5.md) maps every legacy call to its v5 equivalent.

This is the **contract-level** reference for Supermemory: methods, paths, parameters, and the playground.

For narrative guides (when to use what, patterns, SDKs), start with the [Quickstart](https://supermemory.ai/docs/quickstart.md) and [Using supermemory](https://supermemory.ai/docs/ingestion/add-memories.md).

## Base URL

```
https://api.supermemory.ai
```

Self-hosted: use your instance URL (for example `http://localhost:6767`). See [Self-hosting](https://supermemory.ai/docs/self-hosting/overview.md).

## Authentication

All endpoints use a Bearer API key. Create one in the [developer console](https://console.supermemory.ai).

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
Authorization: Bearer sm_...
```

Details: [API keys & auth](https://supermemory.ai/docs/authentication.md).

## Mental model

| Group | What it does |
| - | - |
| **Ingest** | Add documents, files, batches, and conversations into the pipeline |
| **Documents** | Get status, list, update, delete, chunks, and file URLs |
| **Search** | Semantic recall — memories, documents, or hybrid |
| **Profiles** | Static + dynamic facts for a container (user / entity) |
| **Memories** | Create, list, update, and forget extracted memory entries |
| **Container tags** | Multi-tenant settings, merge, and delete for a container |
| **Connections** | OAuth connectors (Drive, Notion, Gmail, …) and sync |
| **Settings** | Org-level customization, buckets, and reset |

Same `containerTag` scopes ingest, search, and profiles — one engine, multiple ways out.

## Suggested order

1. **Ingest** — `POST /v3/documents` (SDK: `client.add`)
2. **Documents** — `GET /v3/documents/{id}` until `status: "done"` for searchable content, and `dreamingStatus: "done"` before you read memories or profiles
3. **Search** — `POST /v4/search`
4. **Profiles** — `POST /v4/profile`

Full walkthrough with conversation + document examples: [Quickstart](https://supermemory.ai/docs/quickstart.md).

## SDKs

The current `supermemory` SDKs (5.x) call the [v5 API](https://supermemory.ai/docs/v5/api-reference/overview.md), not these endpoints. To call v3/v4 through an SDK, pin a release from before 5.0.0:

* TypeScript: `npm install supermemory@4`
* Python: `pip install "supermemory<5"`

See [Supermemory SDK](https://supermemory.ai/docs/integrations/supermemory-sdk.md).

The API's OpenAPI generator supplies **TypeScript / Python SDK** samples via `x-codeSamples`, plus cURL. On this legacy reference they use the pre-5 SDK methods. Playground snippets use the deployed spec, so their availability depends on the API version serving it.

## OpenAPI

Spec (live): [https://api.supermemory.ai/v3/openapi](https://api.supermemory.ai/v3/openapi)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.