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, and deep research with asynchronous workflows and direct Atlas Search queries.
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