Search

Search ranks documents from every library your key can see in one list. Each query runs a word match and a meaning match together and ranks the results as one. Responses are paginated; the API overview covers paging. Every request needs your API key as a bearer token; see Authentication.

#Search documents

GET /search/documents

Returns a ranked page of documents. Each hit is the full document, with content and edges inline, plus a relevance object that says why it matched. The library structures those documents render against arrive once each in a schemas map keyed by library id, rather than repeated on every hit: read a hit's structure from schemas[hit.library.id].

curl -G https://api.fusedframes.com/search/documents \
  -H "Authorization: Bearer ff_your_key" \
  --data-urlencode "q=refund a customer who was charged twice" \
  --data-urlencode "category=Billing"

{
  "documents": [
    {
      "id": "doc_...",
      "title": "Refund an order",
      "category": "Billing",
      "tags": ["stripe", "refunds"],
      "applications": ["Stripe"],
      "content": { ... },
      "schema": { ... },
      "library": { "id": "lib_...", "name": "Support" },
      "edges": { "outgoing": [...], "incoming": [...] },
      "relevance": {
        "signals": ["semantic", "lexical"],
        "score": 0.91,
        "semanticSimilarity": 0.88
      }
    },
    ...
  ],
  "schemas": {
    "lib_...": { "version": 1, "sections": [...] }
  },
  "total": 4,
  "matchedTotal": 9,
  "page": 1,
  "pageSize": 20,
  "facets": {
    "categories": [{ "name": "Billing", "documentCount": 4 }, ...],
    "tags": [...],
    "applications": [...],
    "libraries": [{ "id": "lib_...", "name": "Support", "documentCount": 9 }]
  },
  "lowConfidence": false
}

#What the response fields mean

relevance says why a hit ranked where it did. signals names the matches that fired: lexical for a word match, fuzzy for a near miss, semantic for a meaning match, source_recordings for a match in the recordings behind the document and fallback when the hit came from the low-confidence fallback. score blends them into one number and semanticSimilarity reports the meaning match on its own.

matchedTotal counts everything the query matched before your filters narrowed it, and facets breaks that matched set down by category, tag, application and library. To narrow a search, pick a facet value from the response and send it back as the matching filter.

#The low-confidence fallback

Search never returns an empty list. When no document matches your query well, it returns the most active documents it can see instead, sets lowConfidence: true and adds guidance with hints on what to try. Treat a low-confidence result as a suggestion, not an answer: show it as a near match at best, and use guidance to reword or narrow the query before trusting anything in the list.

Each of the four signals decides for itself what counts as a match, which is what makes that flag meaningful. The word match needs every term present, the fuzzy match has a similarity threshold, and the two meaning matches have a minimum similarity below which a document is treated as unrelated rather than merely the closest thing available. A nearest-neighbour search always has a nearest row, so without that floor every query would look like a match and lowConfidence would never fire.

#Search spends AI credit

The meaning half of every search spends AI credit. When a workspace runs out, search fails with a 402 and the code insufficient_ai_credit rather than falling back to word match alone; top up and the same query works again. Workspaces that bring their own AI provider key are not metered and never see this error.