API Overview
The ChordianAI API is organized around REST principles with JSON request/response bodies. The API uses standard HTTP response codes and supports Server-Sent Events (SSE) for real-time streaming.
Base URL
https://chordian-core.chordian.aiAPI Version
Current version: 1.0.0
OpenAPI Specification: https://chordian-core.chordian.ai/openapi.json
Quick Start
Get started with the ChordianAI API in your preferred programming language:
# Install the SDK
pip install requests
# Initialize the client
import requests
BASE_URL = "https://chordian-core.chordian.ai"
SERVICE_ID = "your-service-id"
# Example: Start a workflow
response = requests.post(
f"{BASE_URL}/api/workflow/start",
json={
"prompt": "Find SaaS companies in San Francisco",
"serviceId": SERVICE_ID,
"total_target": 25
},
headers={"Content-Type": "application/json"}
)
data = response.json()
print(f"Thread ID: {data['thread_id']}")Authentication
ChordianAI API uses AWS Cognito with JWT tokens for secure authentication.
ℹ️ Important: All API requests require authentication. See the Authentication Guide for complete details on obtaining and using tokens.
Quick Overview:
- Method: JWT (JSON Web Tokens) via AWS Cognito User Pools
- Token Expiration: 15 days (session JWT), 30 days (refresh token)
- Header Format:
Authorization: Bearer <your-token>
For detailed setup instructions, token refresh strategies, and error handling, visit:
Request Format
All POST/PUT requests should include:
Content-Type: application/jsonExample request:
curl -X POST https://chordian-core.chordian.ai/api/workflow/start \
-H "Content-Type: application/json" \
-d '{
"prompt": "Find SaaS companies in San Francisco with 50-200 employees",
"serviceId": "your-service-id"
}'Response Format
Responses are returned in JSON format:
{
"thread_id": "abc123",
"status": "processing",
"message": "Workflow started successfully"
}HTTP Status Codes
The API uses standard HTTP status codes:
| Code | Description |
|---|---|
200 | Success - Request completed successfully |
400 | Bad Request - Invalid request parameters |
404 | Not Found - Resource not found |
422 | Validation Error - Request validation failed |
500 | Server Error - Internal server error |
Error Responses
Error responses include detailed information:
{
"detail": [
{
"loc": ["body", "prompt"],
"msg": "field required",
"type": "value_error.missing"
}
]
}Rate Limiting
ℹ️ Info: Rate limits are applied per service ID. Contact support for rate limit details specific to your account.
Streaming Responses
Several endpoints support Server-Sent Events (SSE) for real-time updates:
/api/workflow/start- Workflow progress/api/research/stream/{thread_id}- Research progress/api/lists/csv/upload- CSV import progress
Example SSE connection:
const eventSource = new EventSource(
"https://chordian-core.chordian.ai/api/research/stream/abc123",
);
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log("Progress:", data);
};Common Parameters
Thread ID
Most workflows return a thread_id used to track and manage the workflow:
{
"thread_id": "abc123-def456-ghi789"
}Use this ID to:
- Check workflow status
- Continue workflows
- Stop running workflows
- Restore workflow state
Service ID
Required for credit tracking and rate limiting:
{
"serviceId": "your-service-id"
}Pagination
List endpoints support pagination:
GET /api/workflow/threads?limit=50&offset=0API Categories
The API is organized into these main categories:
Search APIs
Company search, people search, deep research, and agentic web crawling with asynchronous workflows and direct Atlas Search queries.
Chordian Deep Search APIs
Multi-step AI research over the web with optional live browser sessions, LLM model selection, and reference file uploads.
View Chordian Deep Search APIs →
Web and Research APIs
Web-grounded Q&A and research workflows with real-time progress over WebSocket.
Enterprise Search APIs
Chat sessions, messaging, connector administration, and project file uploads for enterprise search.
Memory APIs
Institutional knowledge graphs for departments and lists — upload data, ingest connectors, generate graphs from search results, and chat over your knowledge base.
Next Steps
- Explore Search APIs to build custom searches
- Learn about Request/Response Schemas
- Follow the Getting Started Guide