Query stored documents

POST
/v1/agents/{id}/store/{collection}/query

Finds documents by the fields the manifest marks indexed: equality on any of them, ordered by one, a page at a time. A field that is not indexed is refused with 422 field_not_indexed; a field kept as a hash can be matched but not ordered.

Requires an API key with the workspace:read scope.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

id*string

The agent id.

collection*string

The collection id.

Request Body

application/json
  1. body
where?

Equality on indexed fields; every one must match.

orderBy?

An indexed field to order by, and asc or desc.

limit?integer

How many documents, 1-100. Default 50.

Range1 <= value <= 100
Default50
cursor?string

The nextCursor of the previous page.

Lengthlength <= 512

Response Body

The matching documents and the cursor of the next page

application/json
  1. response
documents*array<>
nextCursor*string|null
Example Request
curl -X POST "https://api.vlayers.ai/v1/agents/$AGENT_ID/store/$COLLECTION/query" \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "where": {      "status": "open"    },    "limit": 20  }'
Example Response
{  "documents": [    {      "collection": "orders",      "id": "order-1001",      "value": {        "status": "open",        "total": 42      },      "updatedAt": "2026-10-20T15:04:05.000Z"    }  ],  "nextCursor": null}