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, schema and edges inline, plus a relevance object that says why it matched.

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
      }
    },
    ...
  ],
  "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.

#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.