Browse Records | Captain

import json
import requests
BASE_URL = "https://acme.captain.dev"
API_KEY = "your_search_key"
INDEX = "products"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
response = requests.post(
    f"{BASE_URL}/v1/indexes/{INDEX}/browse",
    headers=headers,
    json={
        "filter": 'category = "Hiking Boots"',
        "sort": [{"field": "price", "order": "asc"}],
        "k": 3,
        "facet_keys": ["brand"],
    },
    timeout=30.0,
)
print(json.dumps(response.json(), indent=2))

{
  "hits": [
    {
      "id": "sku-10482",
      "title": "Moab 3 Mid Waterproof Hiking Boot",
      "brand": "Merrell",
      "category": "Hiking Boots",
      "price": 139,
      "rating": 4.6,
      "image_url": "https://cdn.acme.example/img/sku-10482.jpg"
    },
    {
      "id": "sku-11020",
      "title": "Targhee III Waterproof Mid Boot",
      "brand": "KEEN",
      "category": "Hiking Boots",
      "price": 150,
      "rating": 4.4,
      "image_url": "https://cdn.acme.example/img/sku-11020.jpg"
    },
    {
      "id": "sku-10517",
      "title": "X Ultra 4 Mid GTX Hiking Boot",
      "brand": "Salomon",
      "category": "Hiking Boots",
      "price": 165,
      "rating": 4.5,
      "image_url": "https://cdn.acme.example/img/sku-10517.jpg"
    }
  ],
  "total": 42,
  "facets": {
    "brand": [
      {
        "value": "Merrell",
        "count": 14
      },
      {
        "value": "Salomon",
        "count": 11
      },
      {
        "value": "KEEN",
        "count": 9
      },
      {
        "value": "Columbia",
        "count": 8
      }
    ]
  },
  "facets_exact": true,
  "timing": {
    "engine_ms": 6.2,
    "stages": {
      "qdrant": 4.1,
      "facets": 1.3,
      "payload": 0.6
    }
  }
}

List records with filters, sort, pages and facets and no query text, for category and listing pages.

Authentication

AuthorizationBearer

A search key, issued by Captain. Sent as Authorization: Bearer <key>.

AuthorizationBearer

A scoped key for one end user, minted from an issuer key that Captain issues. Sent as Authorization: Bearer <key>.

Path parameters

indexstringRequiredformat: "^[a-z0-9][a-z0-9_-]{0,47}$"

index name

Request

This endpoint expects an object.

filtersmap from strings to anyOptional

field -> value (exact), or list (any of). Also price_min, price_max, rating_min, t_<field>min / t<field>_max for typed numbers (flexible schema), attributes.<key> for attribute values. On an Object Search index a filterable field is named as the settings name it: a value or a list of values, or, on a number or date field, a range {gte, gt, lte, lt}. A bare date as lte covers that whole day (lte 2003-12-31 keeps filings made on the 31st). The filter expression (filter) says the same and more

kintegerOptional<=100Defaults to 24

pageintegerOptionalDefaults to 0

facet_keyslist of stringsOptional

the facets to count, by field name (as the answer names them). On an Object Search index a date facet, or a number facet with more than 1,000 distinct values, has no value counts and is refused (400); capabilities.fields.facet_counts lists the ones that count

facet_limitintegerOptional

filterstringOptional

sortlist of objectsOptional

exact over every match

fieldsboolean or list of stringsOptional

facet_queryobjectOptional

as in search

facet_statsbooleanOptional

as in search

Response headers

X-Captain-Applied-Seqinteger

the last update seq search had applied when this request started; the answer reflects at least that much (GET .../updates applied_seq). Not on 401 or 403, nor for an index this server does not have

X-Captain-Index-IncarnationstringOptional

the index's incarnation, an opaque string: it changes only when the index is deleted and created again (whose seqs start again at 1), or restored from a backup (whose seqs continue from the backup's). Sent with X-Captain-Applied-Seq

Response

results

hitslist of objectsOptional

totalintegerOptional

matching records (with group_by too: records, not groups)

groupedobjectOptional

present when results are grouped: the ranking, collapsed by the field's value. A grouped search reads the 100 most relevant records, and further down the top 1,000 when k x size x 4 needs more; depth says how many it read

facetsmap from strings to lists of objectsOptional

facets_exactbooleanOptional

facet_set_sizeintegerOptional

query_idstringOptional

query_understandingobjectOptional

what the engine understood. Keys appear only when they apply; keys not listed here are diagnostics and may change

constraints_removedintegerOptional

constraints: strict: hits removed because a parsed quantity failed. hits [] with this > 0 means nothing meets the query's quantities

sortobjectOptional

search with sort: which field and over what set

pageobjectOptional

search with page or per_page

facet_queryobjectOptional

facet_statsmap from strings to objectsOptional

requestobjectOptional

timingobjectOptional