The Ontology Layer · Reference

Search

One ranked answer fused across every source for a natural-language query.

search is the workhorse: one natural-language query, fanned across every source in parallel, fused into a single ranked list. A technical reader can predict the response shape exactly from this page.

http

POST /projects/{project_id}/knowledge/search

Request body

json

{
  "query": "where do we validate a session token?",
  "sources": ["code", "docs"],
  "providers": null,
  "repo_id": null,
  "since": null,
  "top_k": 10,
  "group_by_source": false
}

Field	Type	Default	Notes
`query`	string	—	Required. Natural language.
`sources`	string[] \	null	null	Restrict to these sources; omit for all.
`providers`	string[] \	null	null	Restrict to these providers.
`repo_id`	string \	null	null	Restrict to a single repo.
`since`	string \	null	null	ISO-8601 lower bound for time-bearing sources.
`top_k`	int	10	Clamped to 1–50.
`group_by_source`	bool	false	Return `top_k` per source instead of one fused list.

Response — fused (default)

json

{
  "query": "where do we validate a session token?",
  "results": [
    {
      "source": "code",
      "provider": null,
      "ref": "code|acme__platform__main|acme__platform__src/auth/session.py",
      "title": "session.py — validate_session",
      "snippet": "def validate_session(token: str) -> Principal: ...",
      "score": 0.82,
      "url": null,
      "timestamp": null,
      "resource_uri": "ontology://acme/code/...",
      "metadata": {}
    }
  ]
}

When group_by_source is true, the payload is { "query": ..., "grouped": { "code": [ ...hits ], "docs": [ ...hits ] } } with up to top_k hits per source instead of one results array.

If nothing matches, the response includes a no_results_help object suggesting what to try next.

How results are ranked

The query is embedded once and shared with every retriever. Because sources score on incompatible scales — cosine similarity, keyword relevance, recency — the fused list is built with Reciprocal Rank Fusion, not raw scores, so the top of every source is represented fairly. See Ranking & fusion.

Each result's ref is opaque; pass it to fetch to get the full object.

Next: Fetch.