Queries a collection. Send it with no options to page through everything, or add a filter to match on document contents.

💡 Results are paginated. Keep requesting the next page_number until the response comes back with "eop": true.

Request

method is "listDocuments".

Field Type Required Description
collection String Yes The collection to query.
filter Object Optional Conditions a document must match. Omit to return everything.
sort Object Optional Field-to-direction map. -1 descending, 1 ascending.
page_size Number Optional Documents per page. Defaults to 50, capped at 200.
page_number Number Optional Page to retrieve, starting at 0.
app_id String Optional The app the collection belongs to. Defaults to the bot's own app.
reference String Optional Your id for this request. Echoed back in the response.

Filters

A filter is an object of field conditions, all of which must hold. A bare value means equality:

"filter": {
  "status": "shipped",
  "total":  { "$gte": 100 },
  "region": { "$in": ["EG", "AE"] },
  "coupon": { "$exists": false }
}

Operators

Operator Matches when the field Example
bare value equals the value {"status": "shipped"}
$eq equals the value {"status": {"$eq": "shipped"}}
$ne does not equal the value {"status": {"$ne": "cancelled"}}
$gt $gte is greater than / at least {"total": {"$gte": 100}}
$lt $lte is less than / at most {"total": {"$lt": 50}}
$in is one of the listed values {"region": {"$in": ["EG", "AE"]}}
$nin is none of the listed values {"region": {"$nin": ["US"]}}
$exists is present (true) or absent (false) {"coupon": {"$exists": false}}
$contains is an array containing the value {"items": {"$contains": "sku-1"}}
$like is a string containing the substring {"name": {"$like": "ali"}}

Nested fields use dots: {"address.city": "Cairo"}.

Notes on matching

Comparisons are typed from the value you send. {"total": {"$gte": 100}} compares numerically; {"name": {"$gte": "m"}} compares as text. Send 100, not "100", when you mean a number — quoting it gives you a string comparison where "9" sorts after "100".

$like matches substrings literally. % and _ in your value are treated as characters, not wildcards.

⚠️ Filtering scans the collection — the document body is not indexed. It stays fast on collections of hundreds to low thousands. If a collection grows large and you query it often, promote the hot field into document_id so you can fetch by id instead.

Not supported in this version: $or / $and nesting, and regular expressions. Every condition in a filter is AND-ed.

Response

listDocumentsResponse

Field Type Returned Description
method String Yes "listDocumentsResponse"
documents Array Yes This page of results. Each entry has document_id and document.
collection String Yes Echoed from the request.
page_number Number Yes The page this result represents.
eop Boolean Yes End of pages. true when there is nothing more to fetch.
app_id String Yes Echoed from the request.
reference String Optional Echoed from the request.