Search & embeddings

August 25, 2026·2 min read

Search & embeddings

Semantic search over a namespace's content, plus the tooling to keep it fresh: embedding health, per-document chunk inspection, and video transcript access. Semantic search ranks by meaning, not keyword overlap — a query for "half-sword techniques" can return a page titled "fighting at close range" if the content matches.

Concept

Term	Meaning
Namespace	The app whose content is embedded and searched
Chunk	A slice of a document, the unit embeddings are computed over
Health	Whether a namespace's content is embedded and how stale it is

Search a namespace

curl -sf -X POST "https://api.falcata.io/api/v1/embeddings/search" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"marozzo","query":"half-sword techniques","limit":5}' \
  | jq '.data[] | {score, title, path}'

An empty result set is not an error — it means no matching content exists, or the namespace hasn't been embedded yet (check health first).

Check embedding health

curl -sf "https://api.falcata.io/api/v1/embeddings/health?namespace=marozzo" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data'

# Is a re-embed currently running?
curl -sf "https://api.falcata.io/api/v1/embeddings/active-task?namespace=marozzo" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data'

active-task returns null in data when no job is running.

Trigger a re-embed

curl -sf -X POST "https://api.falcata.io/api/v1/embeddings/generate" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"marozzo","forceReEmbed":false}' | jq '.data'

Inspect a document's chunks

curl -sf "https://api.falcata.io/api/v1/embeddings/chunks/$KV_ID" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data'

$KV_ID is the document's storage ID, not its content slug — get it from a list-docs or search result first.

Read a video transcript

curl -sf "https://api.falcata.io/api/v1/embeddings/transcript/$VIDEO_ID" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data.segments | length'

If a transcription job stalls, requeue it:

curl -sf -X POST "https://api.falcata.io/api/v1/embeddings/transcript/$VIDEO_ID/requeue" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" -d '{}'

Everything else — smart-action requeueing and the raw document list — in the full reference.