Route reference

Concept text search

GET/v1/knowledge/concepts/searchsearch:read

Finds concepts when the user already knows the exact or near-exact words. Use it for deterministic lookup flows.

When to use it

  • Autocomplete or admin review where semantic expansion would be too broad.
  • A user searches for a known phrase and expects literal matches.
  • You want to cross-check a semantic result against stored concept wording.

Request

query
Required text to look up.
top_k
Optional result count, 1 through 50. Defaults to 10.

Response

items[]
Concept records with public concept fields when present.
count
Number of returned records.
meta.query
The submitted query for reconciliation.

How output is produced

  • Performs an exact-text lookup over concept names and definitions in the public knowledge surface.
  • Returns concept fields through the public concept response shape.
  • Does not compute a semantic score.

Trust and caution

  • This can miss relevant concepts when the user's wording differs.
  • Use semantic concept search for exploration and text search for known wording.
  • Do not treat result order as confidence ranking.
Request example
curl "https://api.agentecology.com/v1/knowledge/concepts/search?query=coordination&top_k=5" \
  -H "X-API-Key: ae_live_YOUR_KEY" \
  -H "Accept: application/json"
Response example
{
  "items": [
    {
      "id": "concept_adaptive_coordination",
      "canonical_name": "Adaptive coordination",
      "definition": "Coordination that changes as local conditions change.",
      "aliases": ["adaptive coordination", "local coordination"],
      "practical_applications": ["distributed teams", "responsive operations"]
    }
  ],
  "count": 1,
  "source": "concepts",
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-26T17:30:00Z",
    "query": "coordination",
    "metered": true
  }
}