Skip to main content
POST
Filter, rank and page documents

Authorizations

Authorization
string
header
required

An organization API key. Keys carry a role (read_write or read_only) and may be restricted to a namespace prefix such as acme/*, or to one namespace such as acme/prod/tenant_1. A prefix matches on a / boundary: acme/prod/tenant_1* covers acme/prod/tenant_1 and everything under acme/prod/tenant_1/, never acme/prod/tenant_12.

Path Parameters

ns
string
required

The namespace name, with any / sent as %2F. Up to 256 bytes. / separates levels of the hierarchy, as in acme/prod/tenant_123.

Required string length: 1 - 256
Pattern: ^[A-Za-z0-9._:/-]+$

Body

application/json
filters
object

[field, op, value], ["And" | "Or", [filters]] or ["Not", filter].

rank_by
tuple

One field and a direction. Ties are broken by id.

top_k
integer
Required range: 1 <= x <= 1000
cursor
string | null

The previous page's next_cursor. Valid for 10 minutes; pins the manifest so pages are consistent.

include
object
answers
enum<string>
default:any

fresh_only excludes rows whose included answers are not fresh.

Available options:
any,
fresh_only
consistency
enum<string>
default:strong

eventual may serve a cached manifest up to 60 seconds old.

Available options:
strong,
eventual

Response

One page of rows.

rows
object[]
required
next_cursor
string | null
required
more
boolean
required

True when rows beyond top_k matched.

usage
object
required

What this response billed (§6.1).