Skip to content
Supermemory Help Center
InboxAsk a human

Getting started with the Supermemory API

What Supermemory does

Supermemory is a memory API. You send it content — conversation turns, notes, documents, URLs, files — and it processes that content asynchronously into two retrievable things: document chunks you can ground on, and extracted memories (facts, with relationships between them) about the entities in that content. You then retrieve context with semantic search, or pull an always-on user profile summary.

Get an API key

Create a key at console.supermemory.ai under API Keys → Create API Key (also available in the app at Settings → API Keys). Usage and billing for API plans live in the Console.

Every request authenticates with a Bearer token in the Authorization header — this is the only supported auth header.

The minimal flow

Three steps: add content, wait for it to finish processing, then search.

  1. Add a document — send a POST to api.supermemory.ai/v3/documents with a JSON body containing content (your text or a URL), a containerTag (e.g. user_123), and optional metadata. The call returns immediately with a document id and status: queued; processing continues in the background.
  2. Wait until the document is done — GET api.supermemory.ai/v3/documents/{id} and poll until status is done.
  3. Search — send a POST to api.supermemory.ai/v4/search with q (your query), the same containerTag, searchMode, and a limit.

searchMode chooses what comes back: documents for document chunks (classic RAG), memories for extracted facts, or hybrid for both. Hybrid is the recommended default. In hybrid results, each hit carries either a memory field or a chunk field depending on its source.

SDKs

Official SDKs exist for JavaScript/TypeScript (npm install supermemory) and Python (pip install supermemory). Both read SUPERMEMORY_API_KEY from the environment by default, and the core calls are client.add(), client.search(), and client.profile() — mirroring the three endpoints above.

Beyond the direct SDKs, there are documented integrations for the Vercel AI SDK, the OpenAI SDK and Agents SDK, LangChain, LangGraph, Mastra, CrewAI, Agno, and others. Start from the Integrations section of the docs.

What you can upload

There are two entry points. add() takes strings — raw text, conversation transcripts, Markdown, code, and URLs (send a URL as the content and Supermemory fetches and extracts the page). Binary files go through the file upload method instead: PDFs (including OCR for scanned documents), Word, Excel, PowerPoint, and images. Google Docs, Sheets, and Slides are handled through the Google Drive connector rather than direct upload.

Common first-timer mistakes

  • Inconsistent containerTag between write and search. This is the most common cause of "my search returns nothing." containerTag is how content is scoped, it is singular, it goes in the JSON body (never in a header), and it must be on every write and every search. If you wrote under user_123 and searched under user123, you get an empty result set, not an error.
  • Searching before processing finishes. Adding returns queued, not done. Poll the document until its status is done before you expect results. Short text usually takes seconds; large PDFs take longer.
  • Expecting extracted memories the instant a document is done. By default, memory extraction may still be batching after document indexing completes, so document search can work while memory search is not ready yet. If you need memories immediately — a demo, a test, a first-run tutorial — pass dreaming: "instant" on the write. It bills one extra operation per document, so it is not the right default for production.
  • Guessing at endpoints. Writes go to /v3/documents, search to /v4/search, and profiles to /v4/profile. Older or invented paths and alternate auth headers such as x-api-key are not supported.

Where to go next

The Quickstart has copy-pasteable curl and SDK examples for this whole flow. The API Reference has the full endpoint list. If you are building multi-tenant, read the Container Tags page before you design your scoping — it is the hardest thing to change later.

Stuck on something the docs do not cover? Contact support with your container tag and a document ID, and we can look at what happened to a specific ingest.