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

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

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

Python

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

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

cURL

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: JSON.stringify({
    AND: [
      { key: "status", value: "reviewed" },
      { key: "priority", value: "high" }
    ]
  })
});

---

Get Document

Get a specific document with its processing status.

TypeScript

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

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

Python

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

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

cURL

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. Triggers reprocessing.

TypeScript

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

Python

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

cURL

curl -X PUT "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

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

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

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

Python

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

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

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

cURL

# 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 POST "https://api.supermemory.ai/v3/documents/bulk-delete" \
  -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

const response = await fetch("https://api.supermemory.ai/v3/documents/processing", {
  headers: { "Authorization": `Bearer ${API_KEY}` }
});

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

cURL

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