Search API

Search runs across the published questions in one organization. It matches question and answer text, ranks the results, and returns a highlighted snippet for each. On Pro, search is hybrid: keyword matching fused with semantic (vector) matching, so a query finds answers by intent even when the exact words are not present.

Search

curl "https://api.thefaq.app/api/v1/acme/search?q=how%20do%20I%20pay" \
  -H "Authorization: Bearer $FAQAPP_API_KEY"

Query params:

• q (required): the search text.
• limit (1–100, default 20): results per page.
• offset (default 0): rows to skip, for pagination.
• category (slug): restrict to a single category.
• lang (ISO 639-1, e.g. nl): search localized content. See Languages.
• mode (lexical | hybrid): override the automatic mode. See Modes.

Required scope: read.

Response:

{
  "data": {
    "query": "how do I pay",
    "results": [
      {
        "id": "q_8X3F",
        "slug": "accepted-payment-methods",
        "question": "What payment methods do you accept?",
        "answer": "We accept all major cards and SEPA direct debit.",
        "categorySlug": "billing",
        "categoryName": "Billing",
        "score": 0.0312,
        "highlights": "We accept all major cards and SEPA direct debit."
      }
    ],
    "total": 7,
    "fallback": null
  },
  "meta": { "pagination": { "page": 1, "limit": 20, "total": 7, "pages": 1 } }
}

Each result's id is the question id; slug, question, and answer are the matched content (translated when you pass lang). highlights is a short snippet of the answer around the match. score is a relevance score where higher is better, but its scale differs between lexical and hybrid, so don't compare scores across modes.

Modes

Search picks its mode from your plan:

• Free, Starter: keyword (lexical) search only.
• Pro and above: hybrid by default. Keyword results are fused with semantic matches, so how much does it cost can surface an Is there a free trial? answer that shares no words with the query.

Pass mode=lexical to opt out of the semantic upgrade and force keyword-only results (for example, to reproduce exact-match behavior). mode=hybrid is the Pro default and is a no-op on plans without semantic search. If semantic matching is briefly unavailable, search returns keyword results rather than failing.

On Pro, total is the size of the fused candidate set (capped), not an exact corpus count. Treat it as "results available to page through" rather than a precise match total; lexical total is exact.

Languages

Pass lang to search a localized copy of your content:

curl "https://api.thefaq.app/api/v1/acme/search?q=hoeveel%20kost%20het&lang=nl" \
  -H "Authorization: Bearer $FAQAPP_API_KEY"

When the question has a translation in that language, results come back translated. If a query has no matches in the requested language, search falls back to your default language and sets fallback to "translated_empty", so you can tell a real result set from a fallback one.

Notes

• Only published, non-deleted questions are searchable.
• Results are scoped to the organization in the path; a key only searches its own org.

Error codes

• validation_error (400): missing q, or an invalid limit, offset, or mode
• not_found (404): the category slug doesn't exist in this org