Document Operations

Manage documents after ingestion using the SDK.

List Documents

Retrieve paginated documents with filtering.

TypeScript
Python
cURL

const documents = await client.documents.list({
  limit: 10,
  containerTags: ["user_123"]
});

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

documents = client.documents.list(
    limit=10,
    container_tags=["user_123"]
)

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

curl -X POST "https://api.supermemory.ai/v3/documents/list" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10, "containerTags": ["user_123"]}'

Response:

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

Parameters

Parameter	Type	Default	Description
`limit`	number	50	Items per page (max 200)
`page`	number	1	Page number
`containerTags`	string[]	—	Filter by tags
`sort`	string	`createdAt`	Sort by `createdAt` or `updatedAt`
`order`	string	`desc`	`desc` (newest) or `asc` (oldest)

Pagination Example

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

  while (true) {
    const { memories, pagination } = await client.documents.list({
      containerTags: [containerTag],
      limit: 100,
      page
    });

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

  return all;
}

Filter by Metadata

const documents = await client.documents.list({
  containerTags: ["user_123"],
  filters: {
    AND: [
      { key: "status", value: "reviewed", negate: false },
      { key: "priority", value: "high", negate: false }
    ]
  }
});

Get Document

Get a specific document with its processing status.

TypeScript
Python
cURL

const doc = await client.documents.get("doc_abc123");

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

doc = client.documents.get("doc_abc123")

print(doc.status)
print(doc.content)

curl "https://api.supermemory.ai/v3/documents/doc_abc123" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

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(docId: string) {
  while (true) {
    const doc = await client.documents.get(docId);

    if (doc.status === "done") return doc;
    if (doc.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.

TypeScript
Python
cURL

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

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

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

Delete Documents

Permanently remove documents.

TypeScript
Python
cURL

// Single delete
await client.documents.delete("doc_abc123");

// Bulk delete by IDs
await client.documents.deleteBulk({
  ids: ["doc_1", "doc_2", "doc_3"]
});

// Bulk delete by container tag (delete all for a user)
await client.documents.deleteBulk({
  containerTags: ["user_123"]
});

# Single delete
client.documents.delete("doc_abc123")

# Bulk delete by IDs
client.documents.delete_bulk(ids=["doc_1", "doc_2", "doc_3"])

# Bulk delete by container tag
client.documents.delete_bulk(container_tags=["user_123"])

# Single delete
curl -X DELETE "https://api.supermemory.ai/v3/documents/doc_abc123" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

# Bulk delete by IDs
curl -X DELETE "https://api.supermemory.ai/v3/documents/bulk" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["doc_1", "doc_2", "doc_3"]}'

Deletes are permanent — no recovery.

Processing Queue

Check documents currently being processed.

TypeScript
Python
cURL

const response = await client.documents.listProcessing();
console.log(`${response.documents.length} documents processing`);

response = client.documents.list_processing()
print(f"{len(response.documents)} documents processing")

curl "https://api.supermemory.ai/v3/documents/processing" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

Next Steps

Memory Operations — Advanced v4 memory operations
Search — Query your memories
Ingesting Content — Add new content

Getting Started

Self-Hosting

Concepts

Using supermemory

Connectors and sync

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