Route reference

Semantic concept search

GET/v1/search/conceptssearch:read

Finds concept candidates from loose wording, questions, themes, or partial ideas. Use it for discovery.

When to use it

  • A user types a theme or problem rather than an exact concept name.
  • You need ranked candidates for a search UI, assistant, or recommendation step.
  • You plan to call the concept detail route after a user selects a result.

Request

query
Required search text.
top_k
Optional result count, 1 through 50. Defaults to 10.
field_id_filter
Optional field ID used to narrow concept results.

Response

items[]
Concept candidates with id, canonical_name, definition, field IDs, and score.
score
Retrieval relevance for ranking, not truth or importance.
meta.vector_search
Whether semantic matching was available for this request.

How output is produced

  • Compares the query against the public concept search surface using semantic and text signals when available.
  • Narrows by field when field_id_filter is supplied.
  • Projects each result into a compact concept shape suitable for selection UIs.

Trust and caution

  • Use this for discovery, not as a final claim that a concept applies.
  • If semantic matching is unavailable for a request, results may rely more on text overlap.
  • A narrow field filter can hide useful adjacent concepts.
Request example
curl "https://api.agentecology.com/v1/search/concepts?query=adaptive%20coordination&top_k=5" \
  -H "X-API-Key: ae_live_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "User-Agent: your-product/1.0"
Response example
{
  "items": [
    {
      "id": "concept_adaptive_coordination",
      "canonical_name": "Adaptive coordination",
      "definition": "Coordination that changes as local conditions change.",
      "field_ids": ["field_organizational_design"],
      "field_id": "field_organizational_design",
      "score": 0.82
    }
  ],
  "count": 1,
  "source": "concepts",
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-05-26T17:30:00Z",
    "vector_search": true,
    "metered": true
  }
}