Search Endpoints
The search API provides endpoints for unified search, semantic search, structural search, precedent search, discovery search, auto-complete suggestions, result explanations, and graph traversal operations.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/context-graph/search | Unified search across all modes |
| POST | /api/v1/context-graph/search/semantic | Semantic (embedding) search |
| POST | /api/v1/context-graph/search/structural | Graph-based structural search |
| POST | /api/v1/context-graph/search/precedents | Decision precedent search |
| POST | /api/v1/context-graph/search/discover | Discovery search from a seed entity |
| POST | /api/v1/context-graph/search/by-example | Search by example entity |
| GET | /api/v1/context-graph/suggest | Auto-complete suggestions |
| POST | /api/v1/context-graph/explain | Explain search results |
| GET | /api/v1/context-graph/search/analytics | Search usage analytics |
| POST | /api/v1/context-graph/traverse | Graph traversal |
| POST | /api/v1/context-graph/traverse/paths | Path finding between entities |
| POST | /api/v1/context-graph/traverse/cycles | Cycle detection |
| POST | /api/v1/context-graph/patterns/detect | Pattern detection |
| GET | /api/v1/context-graph/patterns/statistics | Graph pattern statistics |
POST /search -- Unified Search
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Natural language query or entity URN |
tenant_id | string | Yes | Tenant identifier |
mode | string | No | semantic, structural, hybrid, precedent, discovery (default: hybrid) |
scope | string | No | all, entities, decisions, relationships (default: all) |
top_k | integer | No | Number of results (default: 10) |
min_score | float | No | Minimum relevance score (default: 0.0) |
sort | string | No | relevance, recency, name (default: relevance) |
filters.entity_types | list | No | Filter by entity types |
filters.relationship_types | list | No | Filter by relationship types |
filters.max_hops | integer | No | Maximum traversal depth |
Response
{
"results": [
{
"entity_urn": "urn:matih:dataset:acme:sales_data",
"entity_type": "dataset",
"score": 0.87,
"source": "hybrid",
"entity_data": {},
"graph_context": null,
"explanation": "High semantic similarity to query terms"
}
],
"total_results": 15,
"query_time_ms": 125.4
}GET /suggest -- Auto-Complete
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | Yes | Prefix to search (minimum 2 characters) |
tenant_id | string | Yes | Tenant identifier |
types | string | No | Comma-separated suggestion types |
limit | integer | No | Maximum suggestions (default: 10) |
context_urn | string | No | Context entity for relevance boosting |
Response
{
"suggestions": [
{
"text": "customer_events",
"type": "entity",
"urn": "urn:matih:dataset:acme:customer_events",
"score": 0.95
}
],
"query_time_ms": 2.1
}POST /traverse -- Graph Traversal
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
start_urn | string | Yes | Starting entity URN |
tenant_id | string | Yes | Tenant identifier |
direction | string | No | upstream, downstream, both (default: both) |
strategy | string | No | dfs, bfs, shortest_path (default: bfs) |
max_depth | integer | No | Maximum traversal depth (default: 10) |
relationship_types | list | No | Filter by relationship types |
POST /traverse/paths -- Path Finding
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
source_urn | string | Yes | Source entity URN |
target_urn | string | Yes | Target entity URN |
tenant_id | string | Yes | Tenant identifier |
max_depth | integer | No | Maximum path length (default: 10) |