Search and Filter Governed Answers

Before you begin

Audience: Consultant, technical writer, support engineer, API consumer

The retrieval API searches only APPROVED answers. If you are looking for an answer that is in draft, under validation, disputed, or retired, you must query the registry directly (see step 4). You do not need a specific answer ID to use this task — retrieval is designed for open-ended discovery.

Steps

1. Run a semantic search

Send a GET request to the retrieval search endpoint with your query string:

curl -s "http://localhost:8000/v1/retrieval/search?q=webhook+payload+size+limit"

Optional query parameters:

Parameter	Type	Description
`q`	string (required)	The search query — natural language or technical terms
`customer_scope`	string	Restrict results to a specific customer context
`horn_type`	string	Filter by Horn information type: `fact`, `concept`, `procedure`, etc.
`limit`	integer	Number of results to return; range 1–50; default 10

Example with all optional parameters:

curl -s "http://localhost:8000/v1/retrieval/search?q=webhook+payload+size+limit&customer_scope=acme-corp&horn_type=fact&limit=5"

Note: Retrieval search uses Weaviate vector similarity as the primary retrieval method. If fewer than 2 vector matches are returned, the service automatically falls back to PostgreSQL full-text search. Very specific technical terms, version numbers, or product-specific strings may not match semantically but will be found via the text fallback. You do not need to do anything special to trigger the fallback — it is automatic.

2. Interpret the results

Results are returned as an array sorted by relevance_score descending (highest confidence first):

{
  "results": [
    {
      "answer_id": "ans-2a3b4c5d",
      "answer_text": "The maximum payload size for a webhook delivery in the v3 API is 5 MB. Payloads exceeding this limit are rejected with HTTP 413.",
      "horn_type": "fact",
      "relevance_score": 0.94,
      "source": "weaviate"
    },
    {
      "answer_id": "ans-6e7f8a9b",
      "answer_text": "Webhook retry behavior is governed by the delivery_attempts setting in your webhook configuration.",
      "horn_type": "fact",
      "relevance_score": 0.71,
      "source": "registry"
    }
  ]
}

Key fields to evaluate:

Field	Meaning
`relevance_score`	Similarity or match confidence; higher is better
`source: "weaviate"`	Retrieved via semantic vector search — higher confidence match
`source: "registry"`	Retrieved via PostgreSQL full-text fallback — term-based match

Results with source: "registry" are still valid approved answers; the distinction tells you how they were found, not whether they are authoritative.

3. Refine weak results

If the top results have low relevance_score values or do not address your question:

Narrow horn_type — if you need a procedure, filter for procedure to suppress concept and fact results.
Rephrase the query — use more specific terminology, or include context that would appear in the answer text rather than the question.
Increase the limit — a broader result set may surface a relevant answer further down the ranked list.
Try a registry direct query — see step 4.

Note: Search returns only APPROVED answers. Answers in SUPERSEDED, DISPUTED, PENDING_VALIDATION, or RETIRED states are not returned. If you are looking for a known answer that does not appear in search results, check its status directly in the registry using the answer_id.

4. Query the registry directly for advanced filtering

When you need filters beyond what retrieval search provides — such as filtering by assertion_subtype, lifecycle state, or review due date — query the registry endpoint:

curl -s "http://localhost:8000/v1/registry/answers?horn_type=fact&customer_scope=acme-corp&status=approved&review_due_before=2026-09-01"

Available registry filter parameters:

Parameter	Description
`horn_type`	Filter by Horn information type
`assertion_subtype`	Filter by assertion subtype within a Horn type
`customer_scope`	Restrict to a specific customer context
`status`	Filter by lifecycle status (`approved`, `disputed`, `superseded`, etc.)
`review_due_before`	ISO 8601 date — return answers whose `review_due` is on or before this date
`search_text`	Full-text filter applied against `answer_text`

Example — find all approved FACT answers due for review this quarter:

curl -s "http://localhost:8000/v1/registry/answers?horn_type=fact&status=approved&review_due_before=2026-09-30"

Note: Retrieval search and readout generation are distinct tools with different purposes. Retrieval search is for ad-hoc lookup of individual answers. Readouts are scoped, structured documents generated for meeting preparation and post-meeting coverage analysis. Use retrieval for day-to-day questions; use readouts for structured pre-meeting or post-meeting workflows.

Result

You have a ranked list of approved answers relevant to your query. High-scoring weaviate results are semantically matched to your question. Lower-scoring or registry-sourced results are term-matched fallbacks that may still be relevant. For answers that do not appear in search, the registry direct query provides complete lifecycle visibility.