---
title: "Document operations"
sidebarTitle: "Documents"
description: "List, get, update, and delete your ingested documents"
icon: "/icons/hugeicons/files-02.svg"
---

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`.

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const { documents } = await supermemory.list("user_123", "documents", {
      limit: 10,
    });

    documents.forEach(d => {
      console.log(d.id, d.title, d.system.status);
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    page = client.list("user_123", "documents", limit=10)

    for doc in page.documents:
        print(doc.id, doc.title, doc.system.status)
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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 '{}'
    ```
  </Tab>
</Tabs>

**Response:**
```json
{
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Meeting notes",
      "type": "text",
      "metadata": { "source": "slack" },
      "system": {
        "status": "done",
        "dreamingStatus": "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](/concepts/filtering) |

<Accordion title="Pagination example">
  ```typescript
  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;
  }
  ```
</Accordion>

<Accordion title="Filter by metadata">
  ```typescript
  const { documents } = await supermemory.list("user_123", "documents", {
    filter: {
      operator: "and",
      operands: [
        { field: "status", operator: "eq", value: "reviewed" },
        { field: "priority", operator: "eq", value: "high" },
      ],
    },
  });
  ```
</Accordion>

---

## Get document

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

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    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.system.dreamingStatus);  // "dreaming" | "done"
    console.log(doc.content);
    ```
  </Tab>
  <Tab title="Python">
    ```python
    doc = client.documents.get(
        "user_123",
        "doc_abc123",
        include=["chunks", "memories"],  # optional
    )

    print(doc.system.status)  # "queued" | "processing" | "done" | "failed"
    print(doc.system.dreaming_status)  # "dreaming" | "done"
    print(doc.content)
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl "https://api.supermemory.ai/ns/user_123/document/doc_abc123?include=chunks&include=memories" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
    ```
  </Tab>
</Tabs>

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 |

### Memory generation status

`system.dreamingStatus` tracks memory generation separately from `system.status`.

| Status | Description |
|--------|-------------|
| `dreaming` | Memories for the latest content are queued, being generated, or waiting for a retry |
| `done` | Memories are generated, or the document needed none |

With the default `dreaming: "dynamic"`, Supermemory batches related documents before forming memories, so `status` can be `done` minutes before `dreamingStatus` is. If your next step reads memories or profiles, wait for `dreamingStatus` to be `done` too.

<Accordion title="Poll for completion">
  ```typescript
  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));
    }
  }
  ```
</Accordion>

---

## 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`.

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    await supermemory.documents.update("user_123", "doc_abc123", {
      content: "Updated content here",
      metadata: { version: 2, reviewed: true },
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    client.documents.update(
        "user_123",
        "doc_abc123",
        content="Updated content here",
        metadata={"version": 2, "reviewed": True},
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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}}'
    ```
  </Tab>
</Tabs>

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).

```typescript
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.

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    // 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");
    ```
  </Tab>
  <Tab title="Python">
    ```python
    # 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")
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    # 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 '{}'
    ```
  </Tab>
</Tabs>

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

<Warning>
Deletes are permanent — no recovery.
</Warning>

---

## Processing queue

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

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const { documents } = await supermemory.list("user_123", "documents", {
      limit: 100,
    });
    const processing = documents.filter(d => d.system.status !== "done" && d.system.status !== "failed");
    const dreaming = documents.filter(d => d.system.dreamingStatus === "dreaming");
    console.log(`${processing.length} documents processing, ${dreaming.length} forming memories`);
    ```
  </Tab>
  <Tab title="Python">
    ```python
    page = client.list("user_123", "documents", limit=100)
    processing = [d for d in page.documents if d.system.status not in ("done", "failed")]
    dreaming = [d for d in page.documents if d.system.dreaming_status == "dreaming"]
    print(f"{len(processing)} documents processing, {len(dreaming)} forming memories")
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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 '{}'
    ```
  </Tab>
</Tabs>

---

## Next steps

- [Memory Operations](/recall/memory-operations) — Forget memories
- [Search](/recall/search) — Query your memories
- [Ingesting Content](/ingestion/add-memories) — Add new content