scriptoriumadmin/supermemory
1
0
Fork 0
mirror of https://github.com/supermemoryai/supermemory.git synced 2026-10-01 02:01:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(api): add versioned V5 API reference

Browse source 
Add a workflow-organized reference under apps/docs/v5/api-reference,
covering ingest, search, content management, namespaces, organization,
and profiles, plus an overview explaining base URL, authentication, and
the Legacy-vs-Latest versioning model.

Operations, parameters, and response shapes are grounded in the in-repo
schemas and client surface (packages/validation/api.ts,
packages/validation/schemas.ts, packages/lib/api.ts) and the
conversations client in packages/tools. Register the new pages in the
docs.json navigation as a "V5 API Reference" anchor.
This commit is contained in:
Aswin-Ram-K 2026-09-23 03:24:55 -05:00
parent 0e12f0b3a6
commit 4aed36c217
8 changed files with 1313 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
apps/docs/docs.json
View file

@ -259,7 +259,7 @@
]
},
{
"anchor": "API Reference",
"anchor": "Legacy API Reference",
"icon": "unplug",
"openapi": "https://api.supermemory.ai/v4/openapi",
"pages": [
@ -356,6 +356,26 @@
]
}
]
},
{
"anchor": "V5 API Reference",
"icon": "book-open",
"openapi": "https://api.supermemory.ai/v4/openapi",
"pages": [
"v5/api-reference/overview",
{
"group": "Workflow reference",
"icon": "sparkles",
"pages": [
"v5/api-reference/ingest",
"v5/api-reference/search",
"v5/api-reference/content-management",
"v5/api-reference/namespaces",
"v5/api-reference/organization",
"v5/api-reference/profiles"
]
}
]
}
],
"tab": "Developer Platform"

265
apps/docs/v5/api-reference/content-management.mdx Normal file
View file

@ -0,0 +1,265 @@
---
title: "Content management"
sidebarTitle: "Content management"
description: "List, inspect, update, and delete ingested documents and the memories extracted from them."
icon: "file-text"
---
Once content is ingested, these operations cover its lifecycle: check processing status, list and filter documents, update them, and delete them — either as documents or as extracted memories.
## Get a document
`GET /v3/documents/{id}`
Returns a single document, including its processing `status`.
```bash
curl "https://api.supermemory.ai/v3/documents/{id}" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY"
```
The `status` field moves through the pipeline: `unknown`, `queued`, `extracting`, `chunking`, `embedding`, `indexing`, `done`, or `failed`. Poll until `done` before searching or reading profiles.
## List documents
`POST /v3/documents/list`
Paginated list of documents, filterable by container and status.
```bash
curl -X POST "https://api.supermemory.ai/v3/documents/list" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{"limit": 10, "page": 1, "containerTags": ["user_123"]}'
```
### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| `limit` | number | Items per page |
| `page` | number | Page number |
| `status` | string | Filter by processing status |
| `containerTags` | string[] | Filter by container tags |
The response carries a `memories` array plus `pagination` with `currentPage`, `limit`, `totalItems`, and `totalPages`.
## List documents with memories
`POST /v3/documents/documents`
Returns documents together with the memory entries extracted from each one — useful for reviewing what the pipeline produced.
```bash
curl -X POST "https://api.supermemory.ai/v3/documents/documents" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{"page": 1, "limit": 10, "containerTags": ["sm_project_default"]}'
```
### Parameters
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `page` | number | 1 | Page number |
| `limit` | number | 10 | Items per page (max 1000) |
| `sort` | string | `createdAt` | Sort by `createdAt` or `updatedAt` |
| `order` | string | `desc` | `asc` or `desc` |
| `containerTags` | string[] | — | Filter documents by container tags |
| `sources` | string[] | — | Filter by document source (OR logic), e.g. `["claude-code", "codex"]` |
### Response
```json
{
"documents": [
{
"id": "doc_xyz789",
"customId": "mem_abc123",
"title": "Introduction to Machine Learning",
"type": "text",
"status": "done",
"metadata": { "category": "technology" },
"chunkCount": 10,
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"memoryEntries": []
}
],
"pagination": {
"currentPage": 1,
"limit": 10,
"totalItems": 100,
"totalPages": 10
}
}
```
## List documents by id
`POST /v3/documents/documents/by-ids`
Fetch a specific set of documents in one call.
| Parameter | Type | Description |
| --- | --- | --- |
| `ids` | string[] | Document ids to fetch |
| `by` | string | Match on `id` or `customId` |
| `containerTags` | string[] | Restrict the lookup to these containers |
## List processing documents
`GET /v3/documents/processing`
Everything currently moving through the pipeline, with a `totalCount`.
```bash
curl "https://api.supermemory.ai/v3/documents/processing?containerTags=sm_project_default" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY"
```
## Update a document
`PATCH /v3/documents/{id}`
Update content or metadata. Updating `content` re-runs processing.
| Parameter | Type | Description |
| --- | --- | --- |
| `content` | string | New content (re-processes the document) |
| `customId` | string | Replace the custom id |
| `metadata` | object | Replace metadata |
| `containerTag` | string | Re-containerize the document |
| `entityContext` | string | Extraction context for this container (max 1500 chars) |
## Delete a document
`DELETE /v3/documents/{id}`
Deletes a document by `id` or `customId`. Returns no content on success.
```bash
curl -X DELETE "https://api.supermemory.ai/v3/documents/{id}" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY"
```
## Bulk delete
`DELETE /v3/documents/bulk`
Delete many documents in one call, by ids or by container.
| Parameter | Type | Description |
| --- | --- | --- |
| `ids` | string[] | Document ids to delete (1–100) |
| `containerTags` | string[] | Delete everything in these containers (1–100) |
Provide at least one of the two.
```json
{
"success": true,
"deletedCount": 2,
"errors": [{ "id": "doc_3", "error": "Not found" }]
}
```
## Create memories directly
`POST /v4/memories`
Write extracted memories without going through the document pipeline. Use this when you already know the exact facts to store.
```bash
curl -X POST "https://api.supermemory.ai/v4/memories" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"memories": [
{ "content": "John prefers dark mode", "isStatic": false, "metadata": { "source": "user_preference" } },
{ "content": "John is from Seattle", "isStatic": true }
],
"containerTag": "user_123"
}'
```
| Parameter | Type | Description |
| --- | --- | --- |
| `memories` | array | 1–100 memory objects |
| `memories[].content` | string | The memory text (max 10,000 chars) |
| `memories[].isStatic` | boolean | `true` for permanent traits; defaults to `false` |
| `memories[].metadata` | object | Key-value metadata |
| `containerTag` | string | Container these memories belong to |
The response returns a `documentId` for traceability plus the created `memories` entries.
## List memories
`POST /v4/memories/list`
Paginated listing with sort control.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `containerTags` | string[] | — | Filter by container |
| `limit` | number | 10 | Items per page (max 1100) |
| `page` | number | 1 | Page number |
| `sort` | string | `createdAt` | `createdAt` or `updatedAt` |
| `order` | string | `desc` | `asc` or `desc` |
| `filters` | string | — | JSON-encoded metadata filters |
## Update a memory
`PATCH /v4/memories`
Update a memory's content. The update creates a new version rather than overwriting history — search results expose that through `version` and the `context` field.
## Forget a memory
`DELETE /v4/memories`
Soft-delete a single memory. Excluded from search results but preserved in the database.
| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | Memory id to forget |
| `content` | string | Exact content match, as an alternative to `id` |
| `containerTag` | string | Container the memory belongs to |
| `reason` | string | Optional reason, recorded as `forgetReason` |
## Forget by match
`POST /v4/memories/forget-matching`
Forget a set of memories by natural-language match, or by explicit ids.
| Parameter | Type | Description |
| --- | --- | --- |
| `query` | string | What to forget, in natural language (one of `query`/`ids`) |
| `ids` | string[] | Exact memory ids to forget, skipping semantic search |
| `containerTag` | string | Container to scope the operation to |
| `dryRun` | boolean | Preview the matches without deleting |
| `maxForget` | number | Safety cap in query mode (1–500, default 100) |
| `reason` | string | Reason recorded as `forgetReason` on each memory |
<Warning>
Use `dryRun: true` first, then send the returned ids back as `ids` to delete exactly the set you reviewed. Applying with a `query` re-runs the match, so the result can drift if the container changed in between.
</Warning>
## Get a file URL
`GET /v3/documents/{id}/file-url`
Returns a presigned URL for a document uploaded through the file endpoint.
## Inspect chunks
`GET /v3/documents/{id}/chunks`
Returns the RAG chunks generated for a document — useful when debugging retrieval quality.
## Next steps
- [Memory operations](/recall/memory-operations) — narrative guide to memory CRUD and forgetting
- [Document operations](/ingestion/document-operations) — narrative guide to document lifecycle
- [Namespaces](/v5/api-reference/namespaces) — container tag lifecycle

242
apps/docs/v5/api-reference/ingest.mdx Normal file
View file

@ -0,0 +1,242 @@
---
title: "Ingest"
sidebarTitle: "Ingest"
description: "Add documents, files, batches, and conversations into the processing pipeline."
icon: "download"
---
Ingest is how content enters Supermemory. Every ingest call returns an id immediately; extraction, chunking, and embedding happen asynchronously in the background.
## Add a document
`POST /v3/documents`
Accepts plaintext, a URL, or structured content. The content type is detected from the URL's response format.
<CodeGroup>
```bash cURL
curl -X POST "https://api.supermemory.ai/v3/documents" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"content": "This is a detailed article about machine learning concepts...",
"containerTag": "user_123",
"customId": "mem_abc123",
"metadata": { "category": "technology" }
}'
```
```typescript Typescript
const response = await fetch("https://api.supermemory.ai/v3/documents", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
content: "This is a detailed article about machine learning concepts...",
containerTag: "user_123",
customId: "mem_abc123",
metadata: { category: "technology" },
}),
});
```
```python Python
import os, requests
response = requests.post(
"https://api.supermemory.ai/v3/documents",
headers={
"Authorization": f"Bearer {os.environ['SUPERMEMORY_API_KEY']}",
"Content-Type": "application/json",
},
json={
"content": "This is a detailed article about machine learning concepts...",
"containerTag": "user_123",
"customId": "mem_abc123",
"metadata": {"category": "technology"},
},
)
```
</CodeGroup>
### Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | string | one of | Plaintext, or a URL to a website, PDF, image, or video |
| `containerTag` | string | no | Tag to containerize this memory by — a user id, project id, or any grouping identifier |
| `customId` | string | no | Your own id for this memory; makes re-sends upsert instead of duplicate |
| `metadata` | object | no | Flat key-value pairs (strings, numbers, booleans). Keys are case sensitive; nested objects are not supported |
| `entityContext` | string | no | Context that guides how memories are extracted for this container (max 1500 chars) |
<Note>
`customId` is the idempotency handle. Use a stable value (conversation id, document id) so re-sending the same content updates the existing document rather than creating a second one.
</Note>
### Response
```json
{
"id": "acxV5LHMEsG2hMSNb4umbn",
"status": "queued"
}
```
Poll [`GET /v3/documents/{id}`](/v5/api-reference/content-management#get-a-document) until `status` reaches `done` before relying on search or profiles.
## Upload a file
`POST /v3/documents/file`
Send binary content as `multipart/form-data`. Use this for local files that are not reachable by URL.
```bash
curl -X POST "https://api.supermemory.ai/v3/documents/file" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--form "file=@./report.pdf" \
--form "containerTag=user_123"
```
The uploaded file can be read back later through the presigned URL on the document — see [Content management](/v5/api-reference/content-management#get-a-file-url).
## Batch ingest
`POST /v3/documents/batch`
Add many documents in one request.
<CodeGroup>
```bash cURL
curl -X POST "https://api.supermemory.ai/v3/documents/batch" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"documents": [
{ "content": "Batch doc 1" },
{ "content": "Batch doc 2", "containerTags": ["user_123"] }
],
"containerTag": "user_123"
}'
```
```typescript Typescript
const response = await fetch("https://api.supermemory.ai/v3/documents/batch", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
documents: [
{ content: "Batch doc 1" },
{ content: "Batch doc 2", containerTags: ["user_123"] },
],
containerTag: "user_123",
}),
});
```
</CodeGroup>
### Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `documents` | array | yes | 1–600 document objects |
| `documents[].content` | string | yes | The document content or URL |
| `documents[].containerTags` | string[] | no | Per-document tags for this document |
| `documents[].metadata` | object | no | Per-document metadata |
| `documents[].entityContext` | string | no | Per-document extraction context (max 1500 chars) |
| `containerTag` | string | no | Default container for documents that do not set their own |
| `metadata` | object | no | Default metadata for the batch |
| `entityContext` | string | no | Default extraction context for the batch |
### Response
Per-document results, so a partial failure does not fail the whole batch:
```json
{
"results": [
{ "id": "doc_1", "status": "queued" },
{ "id": "doc_2", "status": "failed", "error": "Unsupported content type" }
],
"success": 1,
"failed": 1
}
```
<Warning>
Check `failed` and the per-result `error` field. A batch request returns `200` even when individual documents fail.
</Warning>
## Add a conversation
`POST /v4/conversations`
Ingest a chat session as structured, turn-aware messages rather than a single text blob. The service diffs against the previous state of the same conversation and appends what is new.
<CodeGroup>
```bash cURL
curl -X POST "https://api.supermemory.ai/v4/conversations" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"conversationId": "conv-123",
"messages": [
{ "role": "user", "content": "Hello!" },
{ "role": "assistant", "content": "Hi there!" }
],
"containerTags": ["user_123"]
}'
```
```typescript Typescript
await fetch("https://api.supermemory.ai/v4/conversations", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
conversationId: "conv-123",
messages: [
{ role: "user", content: "Hello!" },
{ role: "assistant", content: "Hi there!" },
],
containerTags: ["user_123"],
}),
});
```
</CodeGroup>
### Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `conversationId` | string | yes | Stable id for the conversation; used for diffing across sends |
| `messages` | array | yes | Structured turns |
| `messages[].role` | string | yes | `user`, `assistant`, `system`, or `tool` |
| `messages[].content` | string \| array | yes | Text, or an array of content parts for multi-modal turns |
| `messages[].name` | string | no | Participant name |
| `messages[].tool_calls` | array | no | Tool calls made in this turn |
| `messages[].tool_call_id` | string | no | Id linking a tool result back to its call |
| `containerTags` | string[] | no | Tags this conversation belongs to |
| `metadata` | object | no | Metadata attached to the ingested conversation |
<Info>
Keep `conversationId` stable for the lifetime of a chat. Re-sending the growing transcript with the same id lets the service store only the new turns instead of duplicating the whole history.
</Info>
## Next steps
- [Content management](/v5/api-reference/content-management) — poll status and manage what you ingested
- [Search](/v5/api-reference/search) — recall the indexed content
- [Add memories](/ingestion/add-memories) — narrative ingest guide

166
apps/docs/v5/api-reference/namespaces.mdx Normal file
View file

@ -0,0 +1,166 @@
---
title: "Namespaces"
sidebarTitle: "Namespaces"
description: "Container tag and project lifecycle — settings, listing, and deletion."
icon: "tags"
---
A `containerTag` is the namespace that scopes everything in Supermemory: ingest, search, and profiles all key off it. These operations manage the tags themselves and the projects that group them.
## List container tags
`GET /v3/container-tags/list`
Returns every container tag available to the organization as a flat array.
```bash
curl "https://api.supermemory.ai/v3/container-tags/list" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY"
```
Each entry carries the tag identity plus an `isNova` flag, which is `true` when the tag starts with `sm_project_`:
```json
[
{
"id": "space_abc123",
"name": "My Project",
"containerTag": "sm_project_my_project",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"isExperimental": false,
"isNova": true
}
]
```
## Read container tag settings
`GET /v3/container-tags/{containerTag}`
Returns the settings attached to one tag.
## Update container tag settings
`PATCH /v3/container-tags/{containerTag}`
Set a display name and an entity context for a tag.
```bash
curl -X PATCH "https://api.supermemory.ai/v3/container-tags/sm_project_default" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Research Notes",
"entityContext": "This project contains research papers about machine learning."
}'
```
| Parameter | Type | Description |
| --- | --- | --- |
| `name` | string | Display name (1–100 chars). Does not change the tag identifier |
| `entityContext` | string \| null | Extraction context for this container (max 1500 chars) |
| `memoryFilesystemPaths` | string[] \| null | Filesystem paths associated with this container |
The response echoes the tag with its `updatedAt` timestamp:
```json
{
"containerTag": "sm_project_default",
"name": "Research Notes",
"entityContext": "This project contains research papers about machine learning.",
"memoryFilesystemPaths": null,
"updatedAt": "2025-01-15T10:30:00.000Z"
}
```
## Delete a container tag
`DELETE /v3/container-tags/{containerTag}`
Deletes a container and everything in it. Returns counts so you can confirm what was removed.
```json
{
"success": true,
"containerTag": "user_123",
"deletedDocumentsCount": 42,
"deletedMemoriesCount": 118
}
```
<Warning>
This is destructive and scoped to the tag. Deleting a container removes its documents and memories. There is no undo.
</Warning>
## List projects
`GET /v3/projects`
Projects are the user-created containers behind `sm_project_*` tags.
```bash
curl "https://api.supermemory.ai/v3/projects" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY"
```
```json
{
"projects": [
{
"id": "proj_abc123",
"name": "My Awesome Project",
"containerTag": "sm_project_my_awesome_project",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"isExperimental": false,
"documentCount": 42,
"emoji": "📁"
}
]
}
```
## Create a project
`POST /v3/projects`
| Parameter | Type | Description |
| --- | --- | --- |
| `name` | string | Project name (1–100 chars) |
| `emoji` | string | Optional emoji icon (max 10 chars) |
The `containerTag` is derived from the name in the form `sm_project_{name}`.
## Delete a project
`DELETE /v3/projects/{projectId}`
Deleting a project requires deciding what happens to its documents.
| Parameter | Type | Description |
| --- | --- | --- |
| `action` | string | `move` or `delete` |
| `targetProjectId` | string | Required when `action` is `move` |
```bash
curl -X DELETE "https://api.supermemory.ai/v3/projects/proj_abc123" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{"action": "move", "targetProjectId": "proj_xyz789"}'
```
```json
{
"success": true,
"message": "Project deleted successfully",
"documentsAffected": 10,
"memoriesAffected": 5
}
```
## Next steps
- [Container tags](/concepts/container-tags) — the multi-tenancy model
- [Filtering](/concepts/filtering) — metadata filters within a namespace
- [Multi-tenancy examples](/concepts/multi-tenancy-examples) — common layouts

127
apps/docs/v5/api-reference/organization.mdx Normal file
View file

@ -0,0 +1,127 @@
---
title: "Organization"
sidebarTitle: "Organization"
description: "Organization settings, analytics, and data reset."
icon: "settings"
---
Organization-level operations configure how Supermemory behaves for your whole org: extraction customization, connector credentials, usage analytics, and the destructive reset.
## Read settings
`GET /v3/settings`
Returns the current organization settings.
```bash
curl "https://api.supermemory.ai/v3/settings" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY"
```
## Update settings
`PATCH /v3/settings`
Update any subset of the settings below. Omitted fields are left unchanged.
```bash
curl -X PATCH "https://api.supermemory.ai/v3/settings" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"shouldLLMFilter": true,
"filterPrompt": "Ignore marketing newsletters and automated notifications."
}'
```
### Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| `shouldLLMFilter` | boolean | Enable LLM-based filtering of ingested content |
| `filterPrompt` | string \| null | Prompt steering what the filter should drop |
| `includeItems` | string[] \| null | Content categories to always include |
| `excludeItems` | string[] \| null | Content categories to always exclude |
| `workspacePrompt` | string \| null | Org-wide context prompt (max 1500 chars) |
| `googleDriveCustomKeyEnabled` | boolean | Use your own Google Drive OAuth app |
| `googleDriveClientId` | string \| null | Google Drive client id |
| `googleDriveClientSecret` | string \| null | Google Drive client secret |
| `notionCustomKeyEnabled` | boolean | Use your own Notion OAuth app |
| `notionClientId` | string \| null | Notion client id |
| `notionClientSecret` | string \| null | Notion client secret |
| `onedriveCustomKeyEnabled` | boolean | Use your own OneDrive OAuth app |
| `onedriveClientId` | string \| null | OneDrive client id |
| `onedriveClientSecret` | string \| null | OneDrive client secret |
The response returns the `orgId`, the `orgSlug`, and the `updated` settings.
## Suggest buckets
`POST /v3/settings/suggest-buckets`
Generates suggested profile buckets from your organization's existing content. See [Buckets](/user-profiles/buckets) for how buckets organize a profile.
## Reset organization data
`POST /v3/settings/reset`
<Warning>
Destructive and organization-wide. This deletes connections, documents, memory rows, and extra spaces. It cannot be undone.
</Warning>
| Parameter | Type | Description |
| --- | --- | --- |
| `confirmation` | string | Confirmation string required to proceed |
```bash
curl -X POST "https://api.supermemory.ai/v3/settings/reset" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{"confirmation": "RESET"}'
```
The response reports exactly what was removed:
```json
{
"success": true,
"deletedConnections": 3,
"deletedDocumentBatches": 12,
"deletedDocumentsApprox": 480,
"deletedMemoryRows": 1290,
"deletedExtraSpaces": 2,
"clearedDefaultSpaceContext": true,
"settingsReset": true
}
```
## Usage analytics
`GET /v3/analytics/usage`
Request counts grouped by type and API key, plus hourly breakdowns.
| Parameter | Type | Description |
| --- | --- | --- |
| `from` | string | Start of the period (ISO 8601) |
| `to` | string | End of the period (ISO 8601) |
| `period` | string | Shorthand alternative to `from`: `24h`, `7d`, `30d`, or `all` |
| `page` | number | Page number (default 1) |
| `limit` | number | Items per page (default 20, max 100) |
```bash
curl "https://api.supermemory.ai/v3/analytics/usage?period=24h" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY"
```
The response contains `usage` (per request type), `byKey` (per API key, with `lastUsed`), `hourly` counts, `totalMemories`, and `pagination`.
<Info>
Analytics are read-only and scoped to your organization. For the full breakdown of the analytics surface — including error and log endpoints — see [Analytics](/overview/analytics).
</Info>
## Next steps
- [Customization](/concepts/customization) — what the settings above control
- [Analytics](/overview/analytics) — full analytics reference
- [Buckets](/user-profiles/buckets) — profile organization

138
apps/docs/v5/api-reference/overview.mdx Normal file
View file

@ -0,0 +1,138 @@
---
title: "V5 API Reference"
sidebarTitle: "Overview"
description: "What V5 is, how it is versioned, and how to authenticate against it."
icon: "code"
---
**V5** is the current generation of the Supermemory HTTP API. It keeps the resource model you already know — documents, memories, profiles, container tags — and organizes the operations by **workflow** instead of by internal service.
This section is the contract-level reference. Every operation listed here is grouped by the job it does, with the request and response shapes the API actually accepts.
## Base URL
```
https://api.supermemory.ai
```
Self-hosted deployments use your own instance URL (for example `http://localhost:6767`). See [Self-hosting](/self-hosting/overview).
Operations in this reference are versioned by path segment. The paths on these pages carry their own version prefix — for example `POST /v4/search` — so you always know which contract you are calling.
## Authentication
Every request is authenticated with a Bearer API key:
```bash
Authorization: Bearer $SUPERMEMORY_API_KEY
```
Create and rotate keys in the [developer console](https://console.supermemory.ai). Full details, including self-hosted keys: [API keys & auth](/authentication).
<CodeGroup>
```bash cURL
curl -X POST "https://api.supermemory.ai/v4/search" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{"q": "machine learning", "containerTag": "user_123"}'
```
```typescript Typescript
import Supermemory from 'supermemory';
const client = new Supermemory({
apiKey: process.env.SUPERMEMORY_API_KEY,
});
const results = await client.search({
q: "machine learning",
containerTag: "user_123",
});
```
```python Python
from supermemory import Supermemory
client = Supermemory()
results = client.search.memories(
q="machine learning",
container_tag="user_123",
)
```
</CodeGroup>
## Legacy and Latest
The API is versioned by path prefix. Two reference sections are published side by side, and each documents a mix of prefixes:
- **[Legacy API Reference](/api-reference/overview)** — the reference generated from the OpenAPI document below, covering the long-served operations. Calls keep working; new capabilities are not added there.
- **V5 API Reference** (this section) — the workflow-organized reference. Each operation carries its own path prefix, so `POST /v3/search` and `POST /v4/search` both appear here.
<Note>
The version prefix is part of the path, not a header. Pin the prefix you were written against — `POST /v3/documents` and `POST /v4/search` are separate contracts, and a change to one does not silently change the other.
</Note>
| Prefix | Used by |
| --- | --- |
| `/v3` | Documents, ingest, document/SuperRAG search, connections, settings, container tags, usage analytics |
| `/v4` | Memory search, profiles, memories, conversations |
When you start a new integration, follow the workflow pages in this section; each names the exact prefix it calls. Existing integrations can keep calling the prefixes they were written against until they are ready to migrate.
## Operations by workflow
The groups below mirror how you use the API, in the order you typically call it.
| Workflow | What it covers |
| --- | --- |
| [Ingest](/v5/api-reference/ingest) | Add documents, files, batches, and conversations into the pipeline |
| [Search](/v5/api-reference/search) | Semantic recall over memories, document chunks, or both |
| [Content management](/v5/api-reference/content-management) | List, inspect, update, and delete ingested documents |
| [Namespaces](/v5/api-reference/namespaces) | `containerTag` lifecycle — settings, projects, and deletion |
| [Organization](/v5/api-reference/organization) | Org-level settings, analytics, and reset |
| [Profiles](/v5/api-reference/profiles) | Static and dynamic facts for a container |
| [Connections](/api-reference/connections) | Create, sync, and manage external connectors — see the Legacy reference |
<Note>
Connection operations are managed through the [Connections reference](/api-reference/connections) in the Legacy API Reference: `POST /v3/connections/{provider}`, `POST /v3/connections/list`, `GET /v3/connections`, `GET /v3/connections/{connectionId}`, `DELETE /v3/connections/{connectionId}`, `GET /v3/connections/{connectionId}/sync-runs`, and `POST /v3/connections/{provider}/import`.
</Note>
## Suggested reading order
1. **[Ingest](/v5/api-reference/ingest)** — `POST /v3/documents` returns an id immediately.
2. **[Content management](/v5/api-reference/content-management)** — poll `GET /v3/documents/{id}` until `status: "done"`.
3. **[Search](/v5/api-reference/search)** — recall what was indexed.
4. **[Profiles](/v5/api-reference/profiles)** — read the compacted view of a container.
Everything is scoped by `containerTag`, the same key across ingest, search, and profiles. See [Container tags](/concepts/container-tags) for the multi-tenancy model.
## SDKs
The official clients wrap these operations:
- TypeScript: `npm install supermemory`
- Python: `pip install supermemory`
See [Supermemory SDK](/integrations/supermemory-sdk). Narrative guides — when to use which operation, and end-to-end patterns — live under [Using supermemory](/using-supermemory) and the [Quickstart](/quickstart).
## Errors
Failures return a JSON body with an `error` message and an optional `details` string:
```json
{
"error": "Invalid request parameters",
"details": "Query must be at least 1 character long"
}
```
## OpenAPI
The operations on these pages are backed by the generated OpenAPI document that also drives the [Legacy API Reference](/api-reference/overview):
- Spec (live): [https://api.supermemory.ai/v4/openapi](https://api.supermemory.ai/v4/openapi)
That document describes the version-prefixed operations the API serves. This reference reorganizes the same operations by workflow, so you can read them in the order you call them.

136
apps/docs/v5/api-reference/profiles.mdx Normal file
View file

@ -0,0 +1,136 @@
---
title: "Profiles"
sidebarTitle: "Profiles"
description: "Read the static and dynamic profile Supermemory maintains for a container."
icon: "id-card"
---
A profile is a compact summary of what Supermemory knows about an entity — usually a user, but any container works. It combines long-lived *static* facts with recent *dynamic* context, and is maintained automatically as you ingest content.
## Get a profile
`POST /v4/profile`
Returns the profile for a `containerTag`. Add `q` to get search results in the same response.
<CodeGroup>
```bash cURL
curl -X POST "https://api.supermemory.ai/v4/profile" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{"containerTag": "user_123", "q": "deployment errors"}'
```
```typescript Typescript
const response = await fetch("https://api.supermemory.ai/v4/profile", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
containerTag: "user_123",
q: "deployment errors",
}),
});
const { profile } = await response.json();
```
```python Python
import os, requests
response = requests.post(
"https://api.supermemory.ai/v4/profile",
headers={
"Authorization": f"Bearer {os.environ['SUPERMEMORY_API_KEY']}",
"Content-Type": "application/json",
},
json={"containerTag": "user_123", "q": "deployment errors"},
)
```
</CodeGroup>
### Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `containerTag` | string | yes | Container to read the profile for |
| `q` | string | no | Search query; adds search results to the response |
| `threshold` | number | no | Filter search results by relevance score (0–1) |
| `filters` | object | no | Metadata filters applied to the profile and search results |
| `include` | string[] | no | Sections to return — any of `static`, `dynamic`, `buckets`. Omit for all |
| `buckets` | string[] | no | Restrict the `buckets` section to specific keys |
### Response
```json
{
"profile": {
"static": [
"User is a software engineer",
"User specializes in Python and React",
"User prefers dark mode interfaces"
],
"dynamic": [
"User is working on Project Alpha",
"User recently started learning Rust"
]
}
}
```
| Field | Type | Description |
| --- | --- | --- |
| `profile.static` | string[] | Long-lived facts about the entity |
| `profile.dynamic` | string[] | Recent context and episodes |
When you pass `q`, the response also carries `searchResults` with the matching memories.
<Info>
Static facts are the durable identity traits — role, expertise, standing preferences. Dynamic entries are the recent, changing context. Inject both into an agent's system prompt for personalized responses.
</Info>
## Build agent context
The common pattern is to fetch the profile once per turn and inject it into the prompt:
```typescript
async function buildContext(containerTag: string, message: string) {
const response = await fetch("https://api.supermemory.ai/v4/profile", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ containerTag, q: message }),
});
const { profile, searchResults } = await response.json();
return [
"User Profile:",
...profile.static,
"",
"Recent Context:",
...profile.dynamic,
"",
"Relevant Memories:",
...searchResults.results.map((r) => r.memory),
].join("\n");
}
```
## Profile buckets
`POST /v4/profile/buckets`
Returns the profile organized by custom buckets instead of the flat static/dynamic split. Buckets are configured per organization — see [Buckets](/user-profiles/buckets).
## Next steps
- [User profiles](/recall/user-profiles) — narrative guide with SDK examples
- [User profiles concept](/concepts/user-profiles) — how profiles are built and maintained
- [Buckets](/user-profiles/buckets) — organizing a profile by topic

218
apps/docs/v5/api-reference/search.mdx Normal file
View file

@ -0,0 +1,218 @@
---
title: "Search"
sidebarTitle: "Search"
description: "Semantic recall over memories, document chunks, or both."
icon: "search"
---
Search reads back what ingest wrote. Two contracts are available: the memory-oriented `POST /v4/search`, and the document/SuperRAG-oriented `POST /v3/search`.
## Search memories
`POST /v4/search`
Returns extracted memory entries ranked by similarity to the query.
<CodeGroup>
```bash cURL
curl -X POST "https://api.supermemory.ai/v4/search" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"q": "machine learning concepts",
"containerTag": "user_123",
"limit": 10
}'
```
```typescript Typescript
const response = await fetch("https://api.supermemory.ai/v4/search", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
q: "machine learning concepts",
containerTag: "user_123",
limit: 10,
}),
});
```
```python Python
import os, requests
response = requests.post(
"https://api.supermemory.ai/v4/search",
headers={
"Authorization": f"Bearer {os.environ['SUPERMEMORY_API_KEY']}",
"Content-Type": "application/json",
},
json={
"q": "machine learning concepts",
"containerTag": "user_123",
"limit": 10,
},
)
```
</CodeGroup>
### Parameters
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `q` | string | required | Search query (minimum 1 character) |
| `containerTag` | string | — | Scope results to one container |
| `limit` | number | 10 | Maximum results (1–100) |
| `threshold` | number | 0.6 | Similarity cutoff (0–1). Higher returns fewer, more precise results |
| `filters` | object | — | Metadata filters (`AND`/`OR` structure) |
| `rerank` | boolean | false | Re-score results for relevance |
| `rewriteQuery` | boolean | false | Rewrite the query before searching; adds roughly 400 ms of latency |
| `include` | object | — | Opt in to extra context per result |
`include` accepts three booleans, all defaulting to `false`:
| Field | Description |
| --- | --- |
| `documents` | Attach the source documents behind each memory |
| `summaries` | Attach document summaries |
| `relatedMemories` | Attach parent/child memory versions |
### Response
```json
{
"results": [
{
"id": "mem_abc123",
"memory": "John prefers machine learning over traditional programming",
"metadata": { "source": "conversation", "confidence": 0.9 },
"updatedAt": "2025-01-15T10:30:00.000Z",
"similarity": 0.89,
"version": 3
}
],
"timing": 245,
"total": 5
}
```
| Field | Type | Description |
| --- | --- | --- |
| `results[].id` | string | Memory entry id |
| `results[].memory` | string | The memory content |
| `results[].metadata` | object \| null | Memory metadata |
| `results[].updatedAt` | string | Last update timestamp |
| `results[].similarity` | number | Similarity between query and memory (0–1) |
| `results[].version` | number \| null | Version of this memory entry |
| `results[].context` | object | Present when related versions exist — `parents` and `children` arrays |
| `results[].documents` | array | Present when `include.documents` is set |
| `timing` | number | Execution time in milliseconds |
| `total` | number | Number of results returned |
## Search documents
`POST /v3/search`
Document- and chunk-oriented search, for when you want the raw source content rather than extracted facts.
```bash
curl -X POST "https://api.supermemory.ai/v3/search" \
--header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"q": "machine learning concepts",
"containerTags": ["user_123"],
"limit": 10
}'
```
### Parameters
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `q` | string | required | Search query (minimum 1 character) |
| `containerTags` | string[] | — | Scope results to one or more containers |
| `docId` | string | — | Restrict the search to a single document (max 255 chars) |
| `limit` | number | 10 | Maximum results (1–100) |
| `chunkThreshold` | number | 0 | Chunk selection sensitivity (0–1). `0` returns the most chunks |
| `documentThreshold` | number | 0 | Deprecated — currently no effect on search; ignored |
| `filters` | object | — | Metadata filters (`AND`/`OR` structure) |
| `rerank` | boolean | false | Re-score results for relevance |
| `rewriteQuery` | boolean | false | Rewrite the query before searching |
| `onlyMatchingChunks` | boolean | true | Return only matching chunks instead of including neighbouring chunks as context |
| `includeFullDocs` | boolean | false | Include full document content in each result |
| `includeSummary` | boolean | false | Include the document summary in each result |
### Response
```json
{
"results": [
{
"documentId": "doc_xyz789",
"title": "Introduction to Machine Learning",
"type": "web",
"score": 0.95,
"chunks": [
{
"content": "Machine learning is a subset of artificial intelligence...",
"isRelevant": true,
"score": 0.85
}
],
"metadata": { "category": "technology" },
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z"
}
],
"timing": 92,
"total": 5
}
```
Each result carries the document identity plus the chunks that matched. `summary` and `content` appear only when requested through `includeSummary` and `includeFullDocs`.
## Filtering
Both search operations accept the same `filters` object. Filter on metadata keys you set at ingest time.
```json
{
"filters": {
"AND": [
{ "key": "group", "negate": false, "value": "jira_users" },
{
"filterType": "numeric",
"key": "timestamp",
"negate": false,
"numericOperator": ">",
"value": "1742745777"
}
]
}
}
```
See [Organizing & Filtering](/concepts/filtering) for the full filter syntax.
## Choosing an operation
| Use | Operation |
| --- | --- |
| Facts, preferences, and context extracted from content | `POST /v4/search` |
| Raw document chunks and SuperRAG context | `POST /v3/search` |
| Both at once, through the SDK | `client.search({ searchMode: "hybrid" })` |
<Info>
The TypeScript SDK exposes a unified `client.search({ q, searchMode })` where `searchMode` is `"memories"`, `"documents"`, or `"hybrid"`. The HTTP contract stays split across the two paths above.
</Info>
## Next steps
- [Profiles](/v5/api-reference/profiles) — the compacted view of a container
- [Search guide](/recall/search) — patterns and query optimization
- [SuperRAG](/concepts/super-rag) — how document retrieval is assembled