mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-23 06:59:48 +00:00
23983bffae
Fixes billing, analytics, security and legacy reference pages. - **Operations.** `rewriteQuery`, rerank/aggregate and forget-matching each bill one operation. - **Profile metering.** v5 profile is documented as 1 search query per call. - **Analytics:** - The errors response shape is fixed. - Usage `byKey` includes `tokensUsed`, and the log `output` example has the right shape. - The 90-day range limit doesn't exist. - **Smaller fixes:** - Only 2 billing endpoints need an admin. - The `credits` response shape. - The 2FA gate is in the feature table. - The security page points to the one-call namespace delete for data erasure. - Container-tag merge takes several sources. - A stale "after API deploy" note is removed. Checked against the current API and the published SDKs (TS 5.0.1, Python 5.0.0). Legacy v3/v4 docs are unchanged apart from factual fixes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
72 lines
2.8 KiB
Text
72 lines
2.8 KiB
Text
---
|
|
title: "API reference"
|
|
description: "Interactive reference for the Supermemory HTTP API: ingest, search, profiles, memories, connectors and settings."
|
|
icon: "/icons/hugeicons/plug-socket.svg"
|
|
---
|
|
|
|
<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](/v5/api-reference/overview) before then. The [migration guide](/migration/api-v5) maps every legacy call to its v5 equivalent.
|
|
</Warning>
|
|
|
|
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](/quickstart) and [Using supermemory](/ingestion/add-memories).
|
|
|
|
## Base URL
|
|
|
|
```
|
|
https://api.supermemory.ai
|
|
```
|
|
|
|
Self-hosted: use your instance URL (for example `http://localhost:6767`). See [Self-hosting](/self-hosting/overview).
|
|
|
|
## Authentication
|
|
|
|
All endpoints use a Bearer API key. Create one in the [developer console](https://console.supermemory.ai).
|
|
|
|
```bash
|
|
Authorization: Bearer sm_...
|
|
```
|
|
|
|
Details: [API keys & auth](/authentication).
|
|
|
|
## 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"`
|
|
3. **Search** — `POST /v4/search`
|
|
4. **Profiles** — `POST /v4/profile`
|
|
|
|
Full walkthrough with conversation + document examples: [Quickstart](/quickstart).
|
|
|
|
## SDKs
|
|
|
|
Official clients wrap this API:
|
|
|
|
- TypeScript: `npm install supermemory`
|
|
- Python: `pip install supermemory`
|
|
|
|
See [Supermemory SDK](/integrations/supermemory-sdk).
|
|
|
|
The API's OpenAPI generator supplies official **TypeScript / Python SDK** samples via `x-codeSamples`, plus cURL. Playground snippets use the deployed spec, so their availability depends on the API version serving it.
|
|
|
|
SDK generation is migrating off Stainless SaaS to **stlc** soon; documented OpenAPI samples will then be produced by the SDK build instead of a hand-maintained map.
|
|
|
|
## OpenAPI
|
|
|
|
Spec (live): [https://api.supermemory.ai/v3/openapi](https://api.supermemory.ai/v3/openapi)
|