Utility APIs
Utility APIs provide supporting functionality including health checks, service routing, stream management, and company overview generation.
Health Check
Check the health status of the API.
GET /api/healthCode Examples
import requests
response = requests.get('https://chordian-core.chordian.ai/api/health')
health_data = response.json()
print(f"Status: {health_data['status']}")
print(f"Version: {health_data['version']}")Response
{
"status": "healthy",
"timestamp": "2025-02-07T08:09:47Z",
"version": "1.0.0",
"environment": "production"
}| Field | Type | Description |
|---|---|---|
status | string | Health status (healthy or unhealthy) |
timestamp | string | ISO 8601 timestamp |
version | string | API version |
environment | string | Environment name |
Service Routing
Route a user prompt to the appropriate service based on its content and intent.
This endpoint analyzes the user’s prompt using an AI agent and determines which service (list_builder, ai_search, analyze, optimize) would be most appropriate.
Arguments:
request:ServiceRoutingRequestcontaining the user’s promptuser_id: Current user ID from authentication
Returns:
ServiceRoutingResponsewith service details and URL to navigate to
Raises:
HTTPException: If prompt is empty or routing fails
POST /api/service-routing/routeCode Examples
import requests
response = requests.post(
'https://chordian-core.chordian.ai/api/service-routing/route',
headers={'Authorization': f'Bearer {token}'},
json={'prompt': 'Find tech companies in Austin'}
)
routing_result = response.json()
print(f"Service: {routing_result['name']}")
print(f"Reasoning: {routing_result['reasoning']}")
print(f"Navigate to: {routing_result['url']}")Request Body
{
"prompt": "Find tech companies in Austin"
}Response
{
"name": "list_builder",
"reasoning": "User wants to search for companies matching specific criteria",
"category": "Company Search",
"url": "/list-builder",
"success": true
}| Field | Type | Description |
|---|---|---|
name | string | Service name (list_builder, ai_search, analyze, optimize) |
reasoning | string | Explanation of routing decision |
category | string | Service category |
url | string | URL to navigate to |
success | boolean | Whether routing was successful |
Validation Error
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}Service Routing Health
GET /api/service-routing/healthReturns health status for the service routing system.
Stream Management
Get Active Streams
Get all active Redis streams.
GET /api/stream/active-streamsResponse
"string"Check Stream Status
Check if a specific stream is active and get its details.
GET /api/stream/stream-status/{stream_key}Response
{
"stream_key": "workflow:abc123",
"active": true,
"length": 150,
"first_entry_id": "1675775000000-0",
"last_entry_id": "1675776000000-0",
"age_seconds": 1000
}Company Overview
Generate Company Overview
Generate company overview from website analysis (without HTML).
POST /api/company/companyOverviewRequest Body
{
"companyUrl": "https://example.com",
"companyName": "Example Corp"
}| Field | Type | Required | Description |
|---|---|---|---|
companyUrl | string | ✅ | Company website URL |
companyName | string | ✅ | Company name |
Response
{
"company_name": "Example Corp",
"website": "https://example.com",
"description": "Example Corp is a leading provider of...",
"industry": "Technology",
"products": ["Product A", "Product B"],
"key_people": [
{
"name": "John Doe",
"title": "CEO"
}
],
"headquarters": "San Francisco, CA",
"founded": "2015"
}Generate HTML Report
Generate an HTML report from company data.
POST /api/company/companyOverview/htmlRequest Body
{
"companyData": {
"company_name": "Example Corp",
"website": "https://example.com",
"description": "...",
"industry": "Technology"
}
}Response
{
"html": "<html><body><h1>Example Corp</h1>...</body></html>",
"success": true
}Seed Workflows
Seed workflows are used to populate the system with initial data.
Start Company Seed
Start workflows for all prompts in listbuilder_prompt array.
Steps for each prompt:
- Start workflow with the prompt
- Extract list_id from streaming response
- Update suggestionPrompts collection with listId
- Call continue_workflow with the thread_id
- Processes all prompts sequentially until all are exhausted.
POST /api/seed/start/companyResponse
{
"success": true,
"message": "Processed 10 prompts",
"total_prompts": 10,
"successful": 5,
"failed": 0,
"skipped": 5,
"results": [
{
"index": 0,
"prompt_id": "prompt_abc123",
"list_id": "list_xyz789",
"status": "skipped",
"reason": "Already completed",
"current_status": null
}
],
"status": "completed"
}Start People Seed
Start workflows for all prompts in people_prompts array.
Steps for each prompt:
- Start workflow with the prompt
- Extract list_id from streaming response
- Update suggestionPrompts collection with listId
- Call continue_workflow with the thread_id
- Processes all prompts sequentially until all are exhausted.
POST /api/seed/start/peopleResponse
{
"success": true,
"message": "Processed 16 prompts",
"total_prompts": 16,
"successful": 0,
"failed": 0,
"skipped": 16,
"results": [
{
"index": 0,
"prompt_id": "promp t_abc123",
"list_id": "list_xyz789",
"status": "skipped",
"reason": "Already completed",
"current_status": null
}
],
"status": "completed"
}Get Seed Statuses
Get status of all seed workflows.
Returns: Dictionary with summary and list of all workflow statuses
GET /api/seed/status?seed_type=companyQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
seed_type | string | ❌ | Filter by type: company or people |
Response
{
"success": true,
"summary": {
"total": 0,
"pending": 0,
"processing": 0,
"list_created": 0,
"people_workflow_started, processing": 0,
"completed": 0,
"failed": 0,
"skipped": 0
},
"statuses": [],
"count": 0
}Validation Error
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}Clear Seed Statuses
Clear Redis objects with seed workflow statuses.
DELETE /api/seed/status?seed_type=company&clear_all=falseQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
seed_type | string | all | Filter by type: company or people |
clear_all | boolean | false | If true, clear all statuses; if false, clear only completed |
Response
{
"success": true,
"message": "Cleared 0 completed statuses",
"deleted_count": 0,
"cleared_type": "completed statuses",
"deleted_keys": []
}Validation Error
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}Root Endpoint
Basic API information endpoint.
GET / Response
{
"name": "custom-agent-search",
"version": "version",
"environment": "environment_type",
"docs_url": "docs_url",
"health_url": "health_url"
}Best Practices
? Info: Health Checks: Implement health check monitoring in your application to detect API issues early.
- Health Monitoring - Regularly poll the health endpoint
- Service Routing - Use service routing for intelligent feature discovery
- Stream Cleanup - Monitor and clean up inactive streams
- Error Handling - Handle utility endpoint failures gracefully
- Caching - Cache company overview results to reduce API calls
Next Steps
- Explore Request/Response Schemas
- Learn about Workflow APIs
- Follow the Getting Started Guide