DevelopersOverview

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.ai

API 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/json

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

CodeDescription
200Success - Request completed successfully
400Bad Request - Invalid request parameters
404Not Found - Resource not found
422Validation Error - Request validation failed
500Server 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=0

API 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.

View Search APIs →

Enterprise Search APIs

Chat sessions, messaging, connector administration, and project file uploads for enterprise search.

View Enterprise Search APIs →

Memory APIs

Institutional knowledge graphs for departments and lists — upload data, ingest connectors, generate graphs from search results, and chat over your knowledge base.

View Memory APIs →

Next Steps