diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 0d41141c..d7fa0921 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -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"
diff --git a/apps/docs/v5/api-reference/content-management.mdx b/apps/docs/v5/api-reference/content-management.mdx
new file mode 100644
index 00000000..95e904e0
--- /dev/null
+++ b/apps/docs/v5/api-reference/content-management.mdx
@@ -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 |
+
+
+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.
+
+
+## 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
diff --git a/apps/docs/v5/api-reference/ingest.mdx b/apps/docs/v5/api-reference/ingest.mdx
new file mode 100644
index 00000000..a65c7a4a
--- /dev/null
+++ b/apps/docs/v5/api-reference/ingest.mdx
@@ -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.
+
+
+
+```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"},
+ },
+)
+```
+
+
+
+### 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) |
+
+
+`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.
+
+
+### 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.
+
+
+
+```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",
+ }),
+});
+```
+
+
+
+### 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
+}
+```
+
+
+Check `failed` and the per-result `error` field. A batch request returns `200` even when individual documents fail.
+
+
+## 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.
+
+
+
+```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"],
+ }),
+});
+```
+
+
+
+### 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 |
+
+
+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.
+
+
+## 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
diff --git a/apps/docs/v5/api-reference/namespaces.mdx b/apps/docs/v5/api-reference/namespaces.mdx
new file mode 100644
index 00000000..a523430f
--- /dev/null
+++ b/apps/docs/v5/api-reference/namespaces.mdx
@@ -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
+}
+```
+
+
+This is destructive and scoped to the tag. Deleting a container removes its documents and memories. There is no undo.
+
+
+## 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
diff --git a/apps/docs/v5/api-reference/organization.mdx b/apps/docs/v5/api-reference/organization.mdx
new file mode 100644
index 00000000..abe0c17e
--- /dev/null
+++ b/apps/docs/v5/api-reference/organization.mdx
@@ -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`
+
+
+Destructive and organization-wide. This deletes connections, documents, memory rows, and extra spaces. It cannot be undone.
+
+
+| 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`.
+
+
+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).
+
+
+## Next steps
+
+- [Customization](/concepts/customization) — what the settings above control
+- [Analytics](/overview/analytics) — full analytics reference
+- [Buckets](/user-profiles/buckets) — profile organization
diff --git a/apps/docs/v5/api-reference/overview.mdx b/apps/docs/v5/api-reference/overview.mdx
new file mode 100644
index 00000000..2b80a585
--- /dev/null
+++ b/apps/docs/v5/api-reference/overview.mdx
@@ -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).
+
+
+
+```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",
+)
+```
+
+
+
+## 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.
+
+
+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.
+
+
+| 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 |
+
+
+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`.
+
+
+## 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.
diff --git a/apps/docs/v5/api-reference/profiles.mdx b/apps/docs/v5/api-reference/profiles.mdx
new file mode 100644
index 00000000..f451071a
--- /dev/null
+++ b/apps/docs/v5/api-reference/profiles.mdx
@@ -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.
+
+
+
+```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"},
+)
+```
+
+
+
+### 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.
+
+
+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.
+
+
+## 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
diff --git a/apps/docs/v5/api-reference/search.mdx b/apps/docs/v5/api-reference/search.mdx
new file mode 100644
index 00000000..29cb2551
--- /dev/null
+++ b/apps/docs/v5/api-reference/search.mdx
@@ -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.
+
+
+
+```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,
+ },
+)
+```
+
+
+
+### 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" })` |
+
+
+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.
+
+
+## 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