Search

POST /query finds segments. For a question whose answer is a conclusion rather than a location, use POST /ask.

application/json.

Body

Example

curl -X POST http://127.0.0.1:8077/query \
  -H "X-Core-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "man in yellow shorts walking toward the registers",
    "video_ids": ["95e110e25070fcfc"],
    "analyzer": "default_video",
    "field": "people",
    "limit": 5,
    "score_threshold": 0.5,
    "synthesize": true
  }'

{
  "query": "man in yellow shorts walking toward the registers",
  "analyzer": "default_video",
  "field": "people",
  "detail": "standard",
  "answer": "A man in a white T-shirt and yellow shorts walks down the centre aisle toward the registers [95e110e25070fcfc 77.80-83.80s].",
  "results": [ { "…": "SearchResult" } ]
}

field — which vector

Each chunk is one point carrying several named vectors.

combined covers everything; the others match one part, so a short precise match is not diluted by surrounding prose. A chunk missing that field is excluded, not matched on empty text — a video with no people cannot surface in a field=people search.

detail — how much comes back

A browser and an agent want opposite things from the same hit. Five full hits measured about 19k tokens against ~440 for the same hits at minimal.

The agent pattern: detail=minimal to choose, then GET /videos/{id}/chunks?chunk_ids=… to read the few that matter.

filters

A flat dict, validated against one spec, so a filter added to the store is reachable here immediately — no plumbing.

{
  "filters": {
    "chunk_ids": [2, 4, 7],
    "video_ids": ["95e110e25070fcfc"],
    "analyzer_ids": ["people"],
    "after": 60,
    "before": 300,
    "min_people": 2,
    "max_people": 9,
    "objects": ["shopping cart"],
    "tags": ["checkout"],
    "speakers": ["SPEAKER_00"],
    "people": ["cashier"],
    "chunk_config": "interval:30"
  }
}

video_ids and analyzer stay first-class parameters because every caller uses them; they simply join the filter dict on the way down.

score_threshold

Cosine similarity always ranks something, so without a threshold a query for absent content returns weak neighbours instead of nothing.

Measured on sample data: present content scored ≥ 0.665, absent ≤ 0.524 — so roughly 0.55–0.60 separates them. Retune per field and per embedding model; appearance queries (field=people) score lower than topic queries, around 0.51–0.54.

Set it only when the question is whether something is absent and an empty result has to mean "not present".

SearchResult

Errors