DevelopersUtility APIs

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/health

Code 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"
}
FieldTypeDescription
statusstringHealth status (healthy or unhealthy)
timestampstringISO 8601 timestamp
versionstringAPI version
environmentstringEnvironment 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: ServiceRoutingRequest containing the user’s prompt
  • user_id: Current user ID from authentication

Returns:

  • ServiceRoutingResponse with service details and URL to navigate to

Raises:

  • HTTPException: If prompt is empty or routing fails
POST /api/service-routing/route

Code 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
}
FieldTypeDescription
namestringService name (list_builder, ai_search, analyze, optimize)
reasoningstringExplanation of routing decision
categorystringService category
urlstringURL to navigate to
successbooleanWhether routing was successful

Validation Error

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Service Routing Health

GET /api/service-routing/health

Returns health status for the service routing system.


Stream Management

Get Active Streams

Get all active Redis streams.

GET /api/stream/active-streams

Response

"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/companyOverview

Request Body

{
  "companyUrl": "https://example.com",
  "companyName": "Example Corp"
}
FieldTypeRequiredDescription
companyUrlstringCompany website URL
companyNamestringCompany 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/html

Request 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:

  1. Start workflow with the prompt
  2. Extract list_id from streaming response
  3. Update suggestionPrompts collection with listId
  4. Call continue_workflow with the thread_id
  5. Processes all prompts sequentially until all are exhausted.
POST /api/seed/start/company

Response

{
  "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:

  1. Start workflow with the prompt
  2. Extract list_id from streaming response
  3. Update suggestionPrompts collection with listId
  4. Call continue_workflow with the thread_id
  5. Processes all prompts sequentially until all are exhausted.
POST /api/seed/start/people

Response

{
  "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=company

Query Parameters

ParameterTypeRequiredDescription
seed_typestringFilter 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=false

Query Parameters

ParameterTypeDefaultDescription
seed_typestringallFilter by type: company or people
clear_allbooleanfalseIf 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.

  1. Health Monitoring - Regularly poll the health endpoint
  2. Service Routing - Use service routing for intelligent feature discovery
  3. Stream Cleanup - Monitor and clean up inactive streams
  4. Error Handling - Handle utility endpoint failures gracefully
  5. Caching - Cache company overview results to reduce API calls

Next Steps