Document Operations

List, get, update, and delete your ingested documents

Manage documents after ingestion using the SDK.

List Documents

Retrieve paginated documents with filtering.

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

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

Python: ```python documents = client.documents.list( limit=10, container_tags=["user_123"] )

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

cURL:bash curl -X POST " \ -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: ```typescript const doc = await client.documents.get("doc_abc123");

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

Python: ```python doc = client.documents.get("doc_abc123")

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

cURL:bash curl " \ -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:typescript await client.documents.update("doc_abc123", { content: "Updated content here", metadata: { version: 2, reviewed: true } });

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

cURL:bash curl -X PATCH " \ -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: ```typescript // 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"]
});
```

Python: ```python # 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"])
```

cURL: ```bash # Single delete curl -X DELETE "
-H "Authorization: Bearer $SUPERMEMORY_API_KEY"

# Bulk delete by IDs
curl -X DELETE " \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["doc_1", "doc_2", "doc_3"]}'
```

WARNING

Deletes are permanent — no recovery.

---

Processing Queue

Check documents currently being processed.

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

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

cURL:bash curl " \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

---

Next Steps

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