Search & Retrieval

All retrieval goes through one endpoint: GET /v1/query. It supports four distinct modes selected by query parameter.

Full-Text Search — ?token=

curl -sS "$TUPSHAR_HOST/v1/query?token=quarterly+planning" \
  -H "Authorization: Bearer $TUPSHAR_KEY"

How it works:

1. The input string is normalized by the v1 analyzer (lowercased, tokenized) into up to 32 terms.
2. Each term is looked up independently in the BM25 index.
3. Any document matching at least one term is a candidate (OR semantics).
4. Candidates are ranked by summed BM25 score — term frequency, inverse document frequency, and document length normalization.

Results carry id, filename, tags, updated_at, and score. There is no excerpt or snippet in the response.

What full-text search does NOT do:

• No phrase search — "quarterly planning" is not treated as a phrase; both terms are OR-matched independently.
• No AND operator — there is no way to require all terms to appear.
• No negation — -term syntax does not exist.
• No semantic/embedding search — matching is purely lexical (keyword). Documents with synonyms or paraphrases of your query will not match unless they share tokens.
• No excerpt or highlighting — the response does not include snippets of matching text.

Because matching is OR-based, adding more terms broadens results. Use fewer, more specific terms to narrow.

Filename Search — ?filename=

Match documents by filename with three strategies:

# All documents whose filename starts with "notes/"
curl -sS "$TUPSHAR_HOST/v1/query?filename=notes/&match=prefix" \
  -H "Authorization: Bearer $TUPSHAR_KEY"

Tag Search — ?tag=

Return all documents carrying a specific tag (case-insensitive). Control ordering with ?sort=:

• sort=updated — most recently updated first (default)
• sort=accessed — most recently accessed first

curl -sS "$TUPSHAR_HOST/v1/query?tag=meeting&sort=accessed" \
  -H "Authorization: Bearer $TUPSHAR_KEY"

Property Search — ?property=

Filter by property existence or exact value:

# All documents with a "project" property (any value)
curl -sS "$TUPSHAR_HOST/v1/query?property=project" \
  -H "Authorization: Bearer $TUPSHAR_KEY"

# Documents where project == "tupshar"
curl -sS "$TUPSHAR_HOST/v1/query?property=project=tupshar" \
  -H "Authorization: Bearer $TUPSHAR_KEY"

Property matches are exact-value comparisons, not substring or prefix matches.

Choosing a Mode

For full request and response shapes, see HTTP API.