# Query items by field

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

`POST https://api.zavu.dev/v1/memory/collections/{collection}/query`

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.

## Parameters

- `collection` (path, string, required): Collection name.
- `scope` (query, string): Which scope to address: `contact:<contactId>`, `conversation:<conversationId>`, or omitted for the project scope. Note the asymmetry with `POST /v1/memory` and `POST /v1/memory/search`, which take the scope in the request BODY as `scope` plus `contactId`/`conversationId`. Every other Memory endpoint takes it here.

## Body

- `where` (object, required): One condition on one indexed field. `between` bounds are inclusive and must be the same type.
  - `field` (string, required)
  - `op` (string, required) One of: `eq`, `beginsWith`, `between`.
  - `value` (any): The value to match. Used by `eq` (string, number or boolean) and `beginsWith` (string).
  - `from` (any): Lower bound, for `between`.
  - `to` (any): Upper bound, for `between`.
- `limit` (integer)
- `cursor` (string)

## Responses

### 200

Matching items.

- `items` (object[], required)
  - `key` (string, required)
  - `value` (any): The stored JSON. Any JSON value.
  - `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)

### 400

Invalid body or scope, or `field_not_indexed` when the field carries no index.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 404

Collection not found.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X POST "https://api.zavu.dev/v1/memory/collections/collection_abc123/query" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "where": {
    "field": "status",
    "op": "eq",
    "value": "shipped"
  }
}'
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.memory.collections.items.query("collection_abc123", {
  where: {
    field: "status",
    op: "eq",
    value: "shipped",
  },
});

console.log(result);
```