API · Open Knowledge Graph

Overview

by Fabricio Gutierrez Juarez (fjgutierrez@ua.edu) • last updated December 12, 2025

The RuralKG API Backend provides an intelligent query processing system that automatically classifies and routes questions to the most appropriate service. This comprehensive documentation covers all available endpoints, their message formats, and practical use cases for OKN Justice teams.

Base URL

http://52.170.155.134:8001/

Authentication

All API endpoints require an API key (except /health, /docs, /openapi.json, and /).

Include your API key in every request using the X-API-Key header:

X-API-Key: your-api-key-here

Getting an API Key:

Contact fjgutierrez@ua.edu to request an API key for your team
Provide: Team name, Organization/Department, Contact email
You'll receive a unique API key that looks like: ak_prod_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

Rate Limits:

Default: 60 requests/minute, 1,000 requests/hour, 10,000 requests/day
Custom limits may be configured per team

🎯 Primary Endpoints (Recommended for Team Use)

1. `/query` - Main Query Endpoint (RECOMMENDED)

Purpose: Clean, organized endpoint for processing any type of query with automatic classification and routing.

Method: POST

Request Format:

{
  "question": "string (required)",
  "top_k": "integer (optional, default: 5)",
  "use_synthesis": "boolean (optional, default: false)"
}
  

Response Format:

{
  "success": true,
  "query": "Original question",
  "query_type": "data_query|knowledge_query|service_query",
  "routing_decision": "analyze|knowledge|search",
  "processing_time_ms": 1234.56,
  "response_data": {
    /* Service-specific response data */
  },
  "preprocessing": {
    /* Query analysis metadata */
  },
  "error": null
}
  

Example Use Cases:

Data Query Example:

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What percentage of adults have depression?",
    "top_k": 10,
    "use_synthesis": true
  }'
  

Knowledge Query Example:

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are the symptoms of anxiety disorders?",
    "use_synthesis": true
  }'
  

Service Query Example:

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Find mental health services near me in Los Angeles",
    "top_k": 5
  }'
  

2. `/classify` - Smart Router (Alternative to /query)

Purpose: Automatically classify and route queries to the appropriate endpoint.

Method: POST

Request Format:

{
  "question": "string (required)",
  "top_k": "integer (optional, default: 5)",
  "use_synthesis": "boolean (optional, default: false)",
  "county": "string (optional)",
  "state": "string (optional)"
}
  

Response Format: Same as /query endpoint.

🔍 Specialized Endpoints

3. `/preprocess` - Query Analysis

Purpose: Analyze and extract metadata from user queries.

Method: POST

Request Format:

{
  "question": "string (required)"
}
  

Response Format:

{
  "reasoning": "Explanation of query analysis",
  "should_split": false,
  "sub_queries": [],
  "original_query": "Original question",
  "query_type": "data_query|knowledge_query|service_query",
  "entities": ["entity1", "entity2"],
  "relationships": ["relationship1"],
  "location_context": "Geographic context",
  "city": "Extracted city",
  "county": "Extracted county",
  "state": "Extracted state",
  "analysis_focus": "Main focus area",
  "data_types": ["required", "data", "types"],
  "complexity_score": 7.5,
  "miles": null
}
  

Example:

curl -X POST "http://52.170.155.134:8001/preprocess" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the depression rate in California?"}'
  

4. `/analyze` - Data Query Analysis

Purpose: Analyze data queries using variable search across multiple datasets.

Method: POST

Request Format:

{
  "question": "string (required)",
  "include_synthesis": "boolean (optional, default: true)",
  "top_k": "integer (optional, default: 5, max: 20)"
}
  

Response Format:

{
  "query": "Original question",
  "query_type": "data_query",
  "detected_datasets": [1, 2, 3],
  "selected_variable": {
    "id": "var_123",
    "code": "DEPRESSION",
    "content": "Depression in past year",
    "description": "Variable description",
    "dataset": 1,
    "year": 2022,
    "similarity_score": 0.95,
    "answer_options": [
      {
        "code": "YES",
        "content": "Yes",
        "frequency": 1234,
        "percentage": 15.2
      }
    ]
  },
  "top_variables": [],
  "final_answer": "Based on the data, approximately 15.2% of adults reported having depression...",
  "reasoning": "Variable selection reasoning",
  "polars_query": "Generated Polars code",
  "error": null
}
  

Example:

curl -X POST "http://52.170.155.134:8001/analyze" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How many people use marijuana in the last month?",
    "include_synthesis": true,
    "top_k": 5
  }'
  

5. `/knowledge` - Knowledge Search

Purpose: Search for knowledge using semantic search over text collection.

Method: POST

Request Format:

{
  "question": "string (required)",
  "top_k": "integer (optional, default: 5, max: 20)",
  "use_synthesis": "boolean (optional, default: true)"
}
  

Response Format:

{
  "query": "Original question",
  "query_type": "knowledge_query",
  "results": [
    {
      "id": "text_123",
      "title": "Understanding Depression",
      "content": "Depression is a common mental health condition...",
      "year": 2022,
      "dataset": 1,
      "score": 0.95,
      "source_table": "text_nsduh",
      "title_id": "depression_guide",
      "page_number": 1,
      "source_info": {
        "source_id": "text_123",
        "title_id": "depression_guide",
        "type": "definition",
        "page_number": 1
      }
    }
  ],
  "selected_result": {
    /* Same structure as results[0] */
  },
  "synthesized_answer": "Depression is a common mental health condition characterized by...",
  "total_found": 1,
  "processing_time_ms": 1250.5,
  "success": true,
  "error": null
}
  

Example:

curl -X POST "http://52.170.155.134:8001/knowledge" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are the symptoms of anxiety disorders?",
    "top_k": 5,
    "use_synthesis": true
  }'
  

6. `/search` - Service Search

Purpose: Search for mental health treatment services using AI-powered ServiceHelper.

Method: POST

Request Format:

{
  "question": "string (required)",
  "county": "string (optional)",
  "state": "string (optional)"
}
  

Response Format:

{
  "success": true,
  "answer": "I found several mental health services in your area...",
  "provider_ids": ["provider_123", "provider_456"],
  "service_ids": ["service_789", "service_012"],
  "treatment_provider_flag": true,
  "trace": [
    {
      "stage": "search",
      "message": "Searching for mental health services",
      "data": {}
    }
  ],
  "processing_time_ms": 1234.56,
  "error": null
}
  

Example:

curl -X POST "http://52.170.155.134:8001/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Find depression treatment in Los Angeles",
    "county": "Los Angeles County",
    "state": "California"
  }'
  

📡 Streaming Endpoint

7. `/classify/stream` - Real-time Processing

Purpose: Streaming version with real-time logs for long-running queries.

Method: GET

Parameters:

message: string (required) - The user's question
top_k: integer (optional, default: 10)
use_synthesis: boolean (optional, default: true)

Response: Server-Sent Events (SSE) stream

Example:

curl -N "http://52.170.155.134:8001/classify/stream?message=Find%20mental%20health%20services&top_k=5&use_synthesis=true" \
  -H "X-API-Key: YOUR_API_KEY"
  

🏥 Additional API Endpoints

8. `/api/providers/{tp_id}` - Get Provider Details

Purpose: Get treatment provider information by ID.

Method: GET

Parameters:

tp_id: integer (required) - Provider ID

Response Format:

{
  "tp_id": 123,
  "tp_name": "Provider Name",
  "tp_name_sub": "Sub Name",
  "address_line_1": "123 Main St",
  "address_line_2": "Suite 100",
  "state_code": "CA",
  "zip_code": "90210",
  "phone": "(555) 123-4567",
  "intake1": "Intake info",
  "intake2": "Additional intake",
  "intake1a": "Intake 1a",
  "intake2a": "Intake 2a",
  "latitude": 34.0522,
  "longitude": -118.2437
}
  

Example:

curl "http://52.170.155.134:8001/api/providers/123" \
  -H "X-API-Key: YOUR_API_KEY"
  

9. `/api/places/details` - Google Places Integration

Purpose: Get place details from Google Places API.

Method: GET

Parameters:

name: string (required) - Place name
lat: float (required) - Latitude
lng: float (required) - Longitude

Response Format:

{
  "found": true,
  "name": "Place Name",
  "address": "123 Main St, City, State",
  "rating": 4.5,
  "weekday_text": ["Monday: 9:00 AM – 5:00 PM", "Tuesday: 9:00 AM – 5:00 PM"]
}
  

Example:

curl "http://52.170.155.134:8001/api/places/details?name=Mental%20Health%20Center&lat=34.0522&lng=-118.2437" \
  -H "X-API-Key: YOUR_API_KEY"
  

10. `/api/kg/*` - Knowledge Graph Endpoints

Purpose: Access knowledge graph data.

Available Endpoints:

GET /api/kg/all - Get full knowledge graph
GET /api/kg/relations/{node_id} - Get node relations

Example:

curl "http://52.170.155.134:8001/api/kg/all" \
  -H "X-API-Key: YOUR_API_KEY"
  

🏥 Health and Status Endpoints

11. `/health` - Health Check

Purpose: Check service status and dependencies.

Method: GET

Response Format:

{
  "postgres": "ok",
  "milvus": "ok",
  "openai": "disabled"
}
  

12. `/security/status` - Security Status

Purpose: Security monitoring information.

Method: GET

Response Format:

{
  "status": "active",
  "rate_limiting": "enabled",
  "security_headers": "enabled",
  "suspicious_patterns": "blocked"
}
  

13. `/` - Root Endpoint

Purpose: Service information and available endpoints.

Method: GET

Response Format:

{
  "service": "ChatNIO Backend",
  "status": "running",
  "endpoints": {
    "health": "/health",
    "query": "/query (POST - clean, organized API for team consumption)",
    "preprocess": "/preprocess",
    "classify": "/classify (smart router)",
    "classify_stream": "/classify/stream (GET - streaming version)",
    "search": "/search (AI-powered service lookup)",
    "analyze": "/analyze (data query analysis)",
    "knowledge": "/knowledge (semantic text search)",
    "api_providers": "/api/providers/{tp_id}",
    "api_places": "/api/places/details",
    "api_knowledge": "/api/kg",
    "docs": "/docs"
  }
}
  

📋 Postman Collection Examples

Collection Setup

Base URL: http://52.170.155.134:8001
Headers:
- Content-Type: application/json
- X-API-Key: YOUR_API_KEY (required for all endpoints except /health, /docs, /)

Request Examples

1. Main Query Endpoint

POST /query
{
  "question": "What percentage of adults have depression?",
  "top_k": 10,
  "use_synthesis": true
}
  

2. Data Analysis

POST /analyze
{
  "question": "How many people use marijuana in the last month?",
  "include_synthesis": true,
  "top_k": 5
}
  

3. Knowledge Search

POST /knowledge
{
  "question": "What are the symptoms of anxiety disorders?",
  "top_k": 5,
  "use_synthesis": true
}
  

4. Service Search

POST /search
{
  "question": "Find depression treatment in Los Angeles",
  "county": "Los Angeles County",
  "state": "California"
}
  

5. Query Preprocessing

POST /preprocess
{
  "question": "What is the depression rate in California?"
}
  

6. Health Check

GET /health
  

7. Get Provider Details

GET /api/providers/123
  

8. Get Place Details

GET /api/places/details?name=Mental%20Health%20Center&lat=34.0522&lng=-118.2437
  

🎯 Real-World Use Cases for OKN Teams

Use Case 1: Finding Local Mental Health Services

Question: What mental health services are available near Tuscaloosa?

API Call:

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What mental health services are available near Tuscaloosa?",
    "top_k": 5
  }'
  

Expected Response: List of mental health service providers in the Tuscaloosa area with contact information, addresses, and service details.

Use Case 2: Emergency Medical Assistance for Substance Use

Question: I consumed marijuana and I'm feeling unwell — where can I get medical assistance in Miami?

API Call:

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "I consumed marijuana and I'\''m feeling unwell — where can I get medical assistance in Miami?",
    "top_k": 5
  }'
  

Expected Response: List of medical facilities and treatment providers in Miami that can assist with substance-related medical emergencies.

Use Case 3: Data Query on Driving Under the Influence

Question: Is there any data about driving under the influence of illegal substances?

API Call:

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Is there any data about driving under the influence of illegal substances?",
    "top_k": 10,
    "use_synthesis": true
  }'
  

Expected Response: Statistical data from NSDUH or other datasets showing rates, frequencies, and percentages related to driving under the influence of illegal substances.

Use Case 4: Comparative Analysis of Treatment Resources

Question: Describe the treatment resources imbalance situation between San Bernardino county and other county like Jefferson, AL

API Call:

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Describe the treatment resources imbalance situation between San Bernardino county and other county like Jefferson, AL",
    "top_k": 10,
    "use_synthesis": true
  }'
  

Expected Response: Comparative analysis of treatment resources, provider availability, and service distribution between San Bernardino County and Jefferson County, AL.

Use Case 5: Mental Health Resource Allocation Analysis

Question: What does the data suggest about mental health resource allocation between New York city and Jefferson County, AL?

API Call:

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What does the data suggest about mental health resource allocation between New York city and Jefferson County, AL?",
    "top_k": 10,
    "use_synthesis": true
  }'
  

Expected Response: Data-driven analysis comparing mental health resource allocation, provider density, and service availability between New York City and Jefferson County, AL.

Use Case 6: Trend Analysis of Marijuana Use

Question: What is current trends of marijuana used in America?

API Call:

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is current trends of marijuana used in America?",
    "top_k": 10,
    "use_synthesis": true
  }'
  

Expected Response: Statistical trends and patterns of marijuana use in America, including prevalence rates, demographic breakdowns, and temporal changes from NSDUH data.

Use Case 7: Understanding NSDUH Methodology

Question: How is the usability criteria in the NSDUH determined?

API Call:

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How is the usability criteria in the NSDUH determined?",
    "top_k": 5,
    "use_synthesis": true
  }'
  

Expected Response: Knowledge base information explaining NSDUH methodology, usability criteria determination, and data collection processes.

Use Case 8: Data Privacy and Protection Information

Question: What steps are taken to protect individual identities before data is shared or published?

API Call:

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What steps are taken to protect individual identities before data is shared or published?",
    "top_k": 5,
    "use_synthesis": true
  }'
  

Expected Response: Information about data privacy protocols, anonymization techniques, and identity protection measures used in NSDUH.

🔧 Error Handling

Common Error Responses

1. Service Unavailable

{
  "success": false,
  "error": "Database connection failed"
}
  

2. Invalid Request

{
  "success": false,
  "error": "Question parameter is required"
}
  

3. Processing Timeout

{
  "success": false,
  "error": "Request processing timeout"
}
  

4. Provider Not Found

{
  "detail": "Provider not found"
}
  

5. API Key Missing or Invalid

{
  "detail": "API key required. Please include 'X-API-Key' header with your API key."
}
  

{
  "detail": "Authentication failed: Invalid API key"
}
  

6. Rate Limit Exceeded

{
  "detail": "Rate limit exceeded. Please try again later."
}
  

📊 Rate Limits

Default rate limits (may vary per team):

Requests per minute: 60
Requests per hour: 1,000
Requests per day: 10,000

Custom rate limits can be configured per team. Contact fjgutierrez@ua.edu to request higher limits.

Rate limit headers are included in responses:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Time when the rate limit resets

If you exceed limits, you'll receive a 429 Too Many Requests response.

🚀 Quick Start Guide

1. Test Service Health

curl "http://52.170.155.134:8001/health"

2. Get Your API Key

Contact fjgutierrez@ua.edu to request an API key for your team.

3. Try Main Query Endpoint

curl -X POST "http://52.170.155.134:8001/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is depression?"}'
  

4. Explore Available Endpoints

curl "http://52.170.155.134:8001/"

5. View Interactive Documentation

Open: http://52.170.155.134:8001/docs

📞 Support

For technical support or questions about the API:

API Key Requests: fjgutierrez@ua.edu
Technical Issues: fjgutierrez@ua.edu
Service Status: Check /health endpoint
Interactive Documentation: Available at /docs
Root Information: Available at /

🔄 Changelog

Version 1.1.0 - API Key Authentication

Major Feature: API Key Authentication System

API Key Authentication - All endpoints now require API key authentication via X-API-Key header
Per-Team Rate Limiting - Custom rate limits configurable per team (default: 60/min, 1,000/hour, 10,000/day)
Usage Tracking - Automatic tracking of API usage per team
Key Management - Admin endpoints for creating, updating, and managing API keys
Secure Key Storage - API keys are hashed (SHA-256) before storage
Key Expiration - Support for time-limited API keys
Admin Authentication - Admin endpoints protected with separate admin API key
Public Endpoints - /health, /docs, /openapi.json, and / remain public (no API key required)

Version 1.0.0

Initial release of comprehensive API
Support for data, knowledge, and service queries
Automatic query classification and routing
Rich preprocessing metadata
Comprehensive error handling
Multiple specialized endpoints
Google Places integration
Knowledge graph access
Real-time streaming support

Overview

Base URL

Authentication

🎯 Primary Endpoints (Recommended for Team Use)

1. /query - Main Query Endpoint (RECOMMENDED)

2. /classify - Smart Router (Alternative to /query)

🔍 Specialized Endpoints

3. /preprocess - Query Analysis

4. /analyze - Data Query Analysis

5. /knowledge - Knowledge Search

6. /search - Service Search

📡 Streaming Endpoint

7. /classify/stream - Real-time Processing

🏥 Additional API Endpoints

8. /api/providers/{tp_id} - Get Provider Details

9. /api/places/details - Google Places Integration

10. /api/kg/* - Knowledge Graph Endpoints

🏥 Health and Status Endpoints

11. /health - Health Check

12. /security/status - Security Status

13. / - Root Endpoint

📋 Postman Collection Examples

Collection Setup

Request Examples

1. Main Query Endpoint

2. Data Analysis

3. Knowledge Search

4. Service Search

5. Query Preprocessing

6. Health Check

7. Get Provider Details

8. Get Place Details

🎯 Real-World Use Cases for OKN Teams

Use Case 1: Finding Local Mental Health Services

Use Case 2: Emergency Medical Assistance for Substance Use

Use Case 3: Data Query on Driving Under the Influence

Use Case 4: Comparative Analysis of Treatment Resources

Use Case 5: Mental Health Resource Allocation Analysis

Use Case 6: Trend Analysis of Marijuana Use

Use Case 7: Understanding NSDUH Methodology

Use Case 8: Data Privacy and Protection Information

🔧 Error Handling

Common Error Responses

1. Service Unavailable

2. Invalid Request

3. Processing Timeout

4. Provider Not Found

5. API Key Missing or Invalid

6. Rate Limit Exceeded

📊 Rate Limits

🚀 Quick Start Guide

1. Test Service Health

2. Get Your API Key

3. Try Main Query Endpoint

4. Explore Available Endpoints

5. View Interactive Documentation

📞 Support

🔄 Changelog

Version 1.1.0 - API Key Authentication

Version 1.0.0

1. `/query` - Main Query Endpoint (RECOMMENDED)

2. `/classify` - Smart Router (Alternative to /query)

3. `/preprocess` - Query Analysis

4. `/analyze` - Data Query Analysis

5. `/knowledge` - Knowledge Search

6. `/search` - Service Search

7. `/classify/stream` - Real-time Processing

8. `/api/providers/{tp_id}` - Get Provider Details

9. `/api/places/details` - Google Places Integration

10. `/api/kg/*` - Knowledge Graph Endpoints

11. `/health` - Health Check

12. `/security/status` - Security Status

13. `/` - Root Endpoint