Skip to main content
The /api/query endpoint accepts natural language queries and returns structured results from the knowledge graph.

​
Endpoint

POST /api/query

​
Request Body

​
query
string
required
The natural language query to process.Examples:
  • “Who owns the payment service?”
  • “What breaks if redis goes down?”
  • “What does order-service depend on?”
​
session_id
string
default:"default"
Optional session identifier for tracking conversation context.

​
Request Schema

From chat/app.py:46-48: 
class QueryRequest(BaseModel):
    query: str
    session_id: str = "default"

​
Response

​
response
string
Human-readable response formatted by the LLM.
​
query_type
string
The type of query that was executed. Possible values:
  • get_node
  • get_nodes
  • downstream
  • upstream
  • blast_radius
  • path
  • get_owner
  • get_team_assets
  • find_by_property
  • services_using_database
​
confidence
float
Confidence score from the LLM’s intent parsing (0.0 to 1.0).Lower scores indicate the query may have been ambiguous.
​
raw_result
any
Optional raw data from the query engine before LLM formatting.

​
Response Schema

From chat/app.py:51-55: 
class QueryResponse(BaseModel):
    response: str
    query_type: str
    confidence: float
    raw_result: Optional[Any] = None

​
Examples

​
Ownership Query

curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Who owns the payment service?",
    "session_id": "demo"
  }'

​
Dependency Query

curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What does order-service depend on?",
    "session_id": "demo"
  }'

​
Blast Radius Query

curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What breaks if redis-main goes down?",
    "session_id": "demo"
  }'

​
Error Handling

​
Query Parser Not Initialized

{
  "detail": "Query parser not initialized"
}
Status Code: 500 Cause: The application failed to initialize the query parser during startup. Check that:
  • Neo4j is accessible
  • GEMINI_API_KEY is valid
  • Configuration files are present

​
Query Processing Failed

{
  "detail": "Node service:invalid-service not found"
}
Status Code: 500 Cause: The requested entity doesn’t exist in the graph.

​
Implementation

From chat/app.py:143-166: 
@app.post("/api/query", response_model=QueryResponse)
async def process_query(query_request: QueryRequest):
    """Process a natural language query."""
    global query_parser
    
    if not query_parser:
        raise HTTPException(status_code=500, detail="Query parser not initialized")
    
    try:
        result = query_parser.process_query(
            query_request.query,
            query_request.session_id
        )
        
        return QueryResponse(
            response=result['response'],
            query_type=result['query_type'],
            confidence=result.get('confidence', 0.0),
            raw_result=result.get('raw_result')
        )
        
    except Exception as e:
        logger.error(f"Query processing failed: {e}")
        raise HTTPException(status_code=500, detail=str(e))

​
Query Types

The endpoint supports these query patterns:
Query TypeExampleDescription
get_owner”Who owns payment-service?”Find team ownership
downstream”What does X depend on?”Get dependencies
upstream”What depends on X?”Get dependents
blast_radius”What breaks if X fails?”Impact analysis
path”How does X connect to Y?”Find paths
get_team_assets”What does team X own?”List team assets
get_nodes”List all services”List entities

​
Best Practices

1

Be specific

Use exact service names from your configuration:
  • Good: “What does order-service depend on?”
  • Bad: “What does the order thing need?”
2

Check confidence scores

Low confidence indicates ambiguity:
if result['confidence'] < 0.5:
    print("Query may have been misunderstood")
    print("Try rephrasing with exact entity names")
3

Use session IDs

Track related queries with session IDs:
session_id = str(uuid.uuid4())

# First query
result1 = query("Who owns payment-service?", session_id)

# Follow-up query in same session
result2 = query("What does it depend on?", session_id)

Query Engine

Learn about the underlying query methods

Querying Guide

Complete guide to querying patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us