Document operations

Manage documents after ingestion using the SDK. Every call is scoped to one namespace (what v3/v4 called a container tag).

List documents

Retrieve paginated documents with filtering. One list call serves documents, chunks, and memories; pick with type.

TypeScript
Python
cURL

const { documents } = await supermemory.list("user_123", "documents", {
  limit: 10,
});

documents.forEach(d => {
  console.log(d.id, d.title, d.system.status);
});

page = client.list("user_123", "documents", limit=10)

for doc in page.documents:
    print(doc.id, doc.title, doc.system.status)

curl -X POST "https://api.supermemory.ai/ns/user_123/list/documents?limit=10" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Meeting notes",
      "type": "text",
      "metadata": { "source": "slack" },
      "system": {
        "status": "done",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "chunks": [],
  "memories": [],
  "pagination": {
    "currentPage": 1,
    "limit": 10,
    "totalItems": 25,
    "totalPages": 3
  }
}

Every response contains documents, chunks, memories, and pagination. Only the array for the requested type is filled.

Parameters

namespace and type are required. Pagination and sorting are query parameters (top-level keys in the SDK); filter goes in body.

Parameter	Type	Default	Description
`type`	string	required	`documents`, `chunks`, or `memories`
`limit`	number	10	Items per page
`page`	number	1	Page number
`sort`	string	`createdAt`	Sort by `createdAt`, `updatedAt`, or `position`
`order`	string	`desc`	`desc` (newest) or `asc` (oldest)
`body.filter`	object	—	Metadata filter. See Organizing & Filtering

Pagination example

async function getAllDocuments(namespace: string) {
  const all = [];
  let page = 1;

  while (true) {
    const { documents, pagination } = await supermemory.list(namespace, "documents", {
      limit: 100,
      page,
    });

    all.push(...documents);
    if (page >= pagination.totalPages) break;
    page++;
  }

  return all;
}

Filter by metadata

const { documents } = await supermemory.list("user_123", "documents", {
  filter: {
    operator: "and",
    operands: [
      { field: "status", operator: "eq", value: "reviewed" },
      { field: "priority", operator: "eq", value: "high" },
    ],
  },
});

Get document

Get a specific document with its processing status. Pass include to include its chunks and memories.

TypeScript
Python
cURL

const doc = await supermemory.documents.get("user_123", "doc_abc123", {
  include: ["chunks", "memories"], // optional
});

console.log(doc.system.status);  // "queued" | "processing" | "done" | "failed"
console.log(doc.content);

doc = client.documents.get(
    "user_123",
    "doc_abc123",
    include=["chunks", "memories"],  # optional
)

print(doc.system.status)  # "queued" | "processing" | "done" | "failed"
print(doc.content)

curl "https://api.supermemory.ai/ns/user_123/document/doc_abc123?include=chunks&include=memories" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

The id may be the Supermemory document ID or the id you supplied at ingestion. It resolves only inside the namespace in the path.

Processing status

Status	Description
`queued`	Waiting to process
`extracting`	Extracting content (OCR, transcription)
`chunking`	Breaking into searchable pieces
`embedding`	Creating vector representations
`done`	Ready for search
`failed`	Processing failed

Poll for completion

async function waitForProcessing(namespace: string, id: string) {
  while (true) {
    const doc = await supermemory.documents.get(namespace, id);

    if (doc.system.status === "done") return doc;
    if (doc.system.status === "failed") throw new Error("Processing failed");

    await new Promise(r => setTimeout(r, 2000));
  }
}

Update document

Update a document’s content or metadata. Content changes trigger full reprocessing; metadata-only changes (e.g. updating accepted, version) do not reindex. The body accepts any non-empty subset of content, metadata, supportingContext, group, or date.

TypeScript
Python
cURL

await supermemory.documents.update("user_123", "doc_abc123", {
  content: "Updated content here",
  metadata: { version: 2, reviewed: true },
});

client.documents.update(
    "user_123",
    "doc_abc123",
    content="Updated content here",
    metadata={"version": 2, "reviewed": True},
)

curl -X PATCH "https://api.supermemory.ai/ns/user_123/document/doc_abc123" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content here", "metadata": {"version": 2}}'

For file-backed documents use documents.updateFile (PATCH: partial, file optional, metadata merges key by key) or documents.replaceWithFile (POST: full replace, file required, omitted metadata keys are cleared).

await supermemory.documents.updateFile("user_123", "doc_abc123", {
  metadata: JSON.stringify({ reviewed: true }),
});

await supermemory.documents.replaceWithFile("user_123", "doc_abc123", {
  file,
  metadata: JSON.stringify({ revision: 2 }),
});

Delete documents

Permanently remove documents. One call deletes 1 to 100 documents by Supermemory or caller-defined ID.

TypeScript
Python
cURL

// One or many
const { count, errors } = await supermemory.documents.delete("user_123", {
  ids: ["doc_1", "doc_2", "doc_3"],
});

// Delete a whole namespace (all content for a user)
await supermemory.namespaces.delete("user_123");

# One or many
result = client.documents.delete("user_123", ids=["doc_1", "doc_2", "doc_3"])
print(result.count, result.errors)

# Delete a whole namespace (all content for a user)
client.namespaces.delete("user_123")

# One or many
curl -X DELETE "https://api.supermemory.ai/ns/user_123/document" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["doc_1", "doc_2", "doc_3"]}'

# Delete a whole namespace
curl -X DELETE "https://api.supermemory.ai/ns/user_123" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Inspect both count and per-ID errors; HTTP success can include partial failures.

Deletes are permanent — no recovery.

Processing queue

There is no separate processing endpoint. List documents and read system.status on each item.

TypeScript
Python
cURL

const { documents } = await supermemory.list("user_123", "documents", {
  limit: 100,
});
const processing = documents.filter(d => d.system.status !== "done" && d.system.status !== "failed");
console.log(`${processing.length} documents processing`);

page = client.list("user_123", "documents", limit=100)
processing = [d for d in page.documents if d.system.status not in ("done", "failed")]
print(f"{len(processing)} documents processing")

curl -X POST "https://api.supermemory.ai/ns/user_123/list/documents?limit=100" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Next steps

Memory Operations — Forget memories
Search — Query your memories
Ingesting Content — Add new content

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

List documents

Parameters

Get document

Processing status

Update document

Delete documents

Processing queue

Next steps

​List documents

​Parameters

​Get document

​Processing status

​Update document

​Delete documents

​Processing queue

​Next steps

List documents

Parameters

Get document

Processing status

Update document

Delete documents

Processing queue

Next steps