---
title: "Query items by field"
method: POST
path: "/v1/memory/collections/{collection}/query"
tags: ["Memory"]
---

# Query items by field

`POST /v1/memory/collections/{collection}/query`

## Request

- Base URL: `https://api.zavu.dev`
- URL: `https://api.zavu.dev/v1/memory/collections/{collection}/query`
- Auth: HTTP bearer

Find items by an indexed field instead of by key, within one scope.

The field must have been declared in `indexes` when the collection was created. Querying any other field returns `400 field_not_indexed` — including every field of a collection that was auto-created by its first write, which has no indexes at all.

## Path parameters

- `collection` string, required

## Query parameters

- `scope` string: Scope as a query-string value: `contact:<contactId>`, `conversation:<conversationId>`, the literal `project`, or omitted for project scope. Only the SHAPE of the id is validated, never its existence — the partition already carries your project, so an id that matches nothing simply addresses an empty scope rather than returning 404.

## Request body

- MemoryItemQueryRequest: Look items up by an indexed field instead of by key.
  - `where` object, required: One condition on one indexed field. `between` bounds are inclusive and must be the same type.
    - `field` string, required
    - `op` 'eq' | 'beginsWith' | 'between', required
    - `value` unknown
    - `from` unknown
    - `to` unknown
  - `limit` integer
  - `cursor` string

## Response `200`

Matching items.

- object
  - `items` MemoryItem[], required
    - `key` string, required
    - `value` unknown
    - `rev` integer, required: Revision, incremented on every write. Pass it as `If-Match` on a later write to make that write conditional.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `expiresAt` string, date-time
  - `nextCursor` string, nullable

## Other responses

- `400`: Invalid body or scope, or `field_not_indexed` when the field carries no index.
- `401`: Unauthorized.
- `404`: Collection not found.

## Changes

> 80 revisions in range; 1 not diffed.

- **2026-08-26** `6e8c555e1104`: 1 info
  - removed the non-success response with the status `403`
- **2026-08-26** `83caf7165722`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/changes/v1/memory/collections/:collection/query/post.md)

---

[API](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api.md) - [All operations](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/revisions/75bc777b0ffb?raw)