Skip to content
DashboardGet API key

Query items by field

View .md
POST

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.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

  • collectionstringrequired

    Collection name.

Query parameters

  • scopestring

    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

application/json

  • whereobjectrequired

    One condition on one indexed field. between bounds are inclusive and must be the same type.

    5 properties
    • fieldstringrequired
    • opstringrequired
      One ofeqbeginsWithbetween
    • valueany

      The value to match. Used by eq (string, number or boolean) and beginsWith (string).

    • fromany

      Lower bound, for between.

    • toany

      Upper bound, for between.

  • limitinteger
    Default50
    Limitsmin 1 · max 100
  • cursorstring

Responses

200Matching items.
  • itemsobject[]required
    6 properties
    • keystringrequired
    • valueany

      The stored JSON. Any JSON value.

    • revintegerrequired

      Revision, incremented on every write. Pass it as If-Match on a later write to make that write conditional.

    • createdAtstring<date-time>required
    • updatedAtstring<date-time>required
    • expiresAtstring<date-time>
  • nextCursorstringnullable
400Invalid body or scope, or `field_not_indexed` when the field carries no index.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
404Collection not found.
  • codestringrequired
  • messagestringrequired
  • detailsobject