Skip to content
supermemory-new
Get started
API Reference
Documents

List documents

documents.list(DocumentListParams**kwargs) -> DocumentListResponse
POST/v3/documents/list

Retrieves a paginated list of documents with their metadata and workflow status

ParametersExpand Collapse
Deprecatedcontainer_tags: Optional[Sequence[str]]

Optional tags this document should be containerized by. This can be an ID for your user, a project ID, or any other identifier you wish to use to group documents.

filepath: Optional[str]

Filter documents by filepath. Exact match for full paths, prefix match if ending with /

filters: Optional[Filters]

Optional filters to apply to the search. Can be a JSON string or Query object.

One of the following:
class FiltersOr: …
or_: Iterable[FiltersOrOr]

Array of OR filter expressions

One of the following:
class FiltersOrOrFilterCondition: …

A single filter condition based on metadata, numeric values, array contents, or string matching

key: str
value: str
filter_type: Optional[Literal["metadata", "numeric", "array_contains", "string_contains"]]
One of the following:
"metadata"
"numeric"
"array_contains"
"string_contains"
ignore_case: Optional[Union[bool, Literal["true", "false"]]]
One of the following:
bool
Literal["true", "false"]
One of the following:
"true"
"false"
negate: Optional[Union[bool, Literal["true", "false"]]]
One of the following:
bool
Literal["true", "false"]
One of the following:
"true"
"false"
numeric_operator: Optional[Literal[">", "<", ">=", 2 more]]
One of the following:
">"
"<"
">="
"<="
"="
class FiltersOrOrOr: …
or_: Iterable[object]

OR: Array of conditions or nested expressions

class FiltersOrOrAnd: …
and_: Iterable[object]

AND: Array of conditions or nested expressions

class FiltersAnd: …
and_: Iterable[FiltersAndAnd]

Array of AND filter expressions

One of the following:
class FiltersAndAndFilterCondition: …

A single filter condition based on metadata, numeric values, array contents, or string matching

key: str
value: str
filter_type: Optional[Literal["metadata", "numeric", "array_contains", "string_contains"]]
One of the following:
"metadata"
"numeric"
"array_contains"
"string_contains"
ignore_case: Optional[Union[bool, Literal["true", "false"]]]
One of the following:
bool
Literal["true", "false"]
One of the following:
"true"
"false"
negate: Optional[Union[bool, Literal["true", "false"]]]
One of the following:
bool
Literal["true", "false"]
One of the following:
"true"
"false"
numeric_operator: Optional[Literal[">", "<", ">=", 2 more]]
One of the following:
">"
"<"
">="
"<="
"="
class FiltersAndAndOr: …
or_: Iterable[object]

OR: Array of conditions or nested expressions

class FiltersAndAndAnd: …
and_: Iterable[object]

AND: Array of conditions or nested expressions

include_content: Optional[bool]

Whether to include the content field in the response. Warning: This can make responses significantly larger.

limit: Optional[Union[str, float]]

Number of items per page

One of the following:
str
float
order: Optional[Literal["asc", "desc"]]

Sort order

One of the following:
"asc"
"desc"
page: Optional[Union[str, float]]

Page number to fetch

One of the following:
str
float
sort: Optional[Literal["createdAt", "updatedAt"]]

Field to sort by

One of the following:
"createdAt"
"updatedAt"
ReturnsExpand Collapse
class DocumentListResponse: …

List of documents

memories: List[Memory]
id: str

Unique identifier of the document.

minLength22
maxLength22
connection_id: Optional[str]

Optional ID of connection the document was created from. This is useful for identifying the source of the document.

minLength22
maxLength22
created_at: str

Creation timestamp

formatdatetime
custom_id: Optional[str]

Optional custom ID of the document. This could be an ID from your database that will uniquely identify this document.

maxLength255
filepath: Optional[str]
metadata: Union[str, float, bool, 3 more]

Optional metadata for the document. This is used to store additional information about the document. You can use this to store any additional information you need about the document. Metadata can be filtered through. Keys must be strings and are case sensitive. Values can be strings, numbers, or booleans. You cannot nest objects.

One of the following:
str
float
bool
Dict[str, object]
List[object]
status: Literal["unknown", "queued", "extracting", 5 more]

Status of the document

One of the following:
"unknown"
"queued"
"extracting"
"chunking"
"embedding"
"indexing"
"done"
"failed"
summary: Optional[str]

Summary of the document content

title: Optional[str]

Title of the document

type: Literal["text", "pdf", "tweet", 11 more]

Type of the document

One of the following:
"text"
"pdf"
"tweet"
"google_doc"
"google_slide"
"google_sheet"
"image"
"video"
"audio"
"notion_doc"
"webpage"
"onedrive"
"github_markdown"
"granola"
updated_at: str

Last update timestamp

formatdatetime
Deprecatedcontainer_tags: Optional[List[str]]

Optional tags this document should be containerized by. This can be an ID for your user, a project ID, or any other identifier you wish to use to group documents.

content: Optional[str]

Content of the document (only included when includeContent=true)

url: Optional[str]

URL of the document

List documents

import os
from supermemory import Supermemory

client = Supermemory(
    api_key=os.environ.get("SUPERMEMORY_API_KEY"),  # This is the default and can be omitted
)
documents = client.documents.list()
print(documents.memories)
{
  "memories": [
    {
      "id": "acxV5LHMEsG2hMSNb4umbn",
      "connectionId": "xxxxxxxxxxxxxxxxxxxxxx",
      "createdAt": "2025-04-15T09:30:00.000Z",
      "customId": "doc-api-rate-limits",
      "filepath": "filepath",
      "metadata": {
        "source": "bar",
        "language": "bar"
      },
      "status": "done",
      "summary": "API rate limit policy: 100 req/min free, 1000 req/min pro.",
      "title": "API Rate Limiting Policy",
      "type": "text",
      "updatedAt": "2025-04-15T09:31:00.000Z",
      "containerTags": [
        "string"
      ],
      "content": "This is the content of the document...",
      "url": "https://docs.example.com/guides/rate-limits"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalItems": 100,
    "totalPages": 10,
    "limit": 10
  }
}
Returns Examples
{
  "memories": [
    {
      "id": "acxV5LHMEsG2hMSNb4umbn",
      "connectionId": "xxxxxxxxxxxxxxxxxxxxxx",
      "createdAt": "2025-04-15T09:30:00.000Z",
      "customId": "doc-api-rate-limits",
      "filepath": "filepath",
      "metadata": {
        "source": "bar",
        "language": "bar"
      },
      "status": "done",
      "summary": "API rate limit policy: 100 req/min free, 1000 req/min pro.",
      "title": "API Rate Limiting Policy",
      "type": "text",
      "updatedAt": "2025-04-15T09:31:00.000Z",
      "containerTags": [
        "string"
      ],
      "content": "This is the content of the document...",
      "url": "https://docs.example.com/guides/rate-limits"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalItems": 100,
    "totalPages": 10,
    "limit": 10
  }
}