Getting Started

This guide will walk you through making your first API calls to the ChordianAI platform.

Prerequisites

Before you begin, you’ll need:

  • API credentials (contact ChordianAI team)
  • A service ID for credit tracking
  • Basic knowledge of REST APIs and JSON

Step 1: Verify API Access

First, verify that the API is accessible:

curl https://chordian-core.chordian.ai/api/health

You should receive a response like:

{
  "status": "healthy",
  "timestamp": "2025-02-07T08:09:47Z",
  "version": "1.0.0",
  "environment": "production"
}

✅ Success: If you receive this response, the API is working correctly!

Step 2: Start Your First Workflow

Let’s create a simple company search workflow:

import requests
 
response = requests.post(
    'https://chordian-core.chordian.ai/api/workflow/start',
    json={
        'prompt': 'Find SaaS companies in San Francisco with 50-200 employees',
        'serviceId': 'your-service-id'
    }
)
 
data = response.json()
print(f"Thread ID: {data['thread_id']}")

Understanding the Response

The API will return a streaming response. The first message will include:

{
  "thread_id": "wf_abc123def456",
  "status": "processing",
  "message": "Workflow started successfully"
}

Save the thread_id - you’ll need it to check status and continue the workflow.

Step 3: Monitor Workflow Status

Check the status of your workflow:

curl https://chordian-core.chordian.ai/api/workflow/status/wf_abc123def456

Response:

{
  "thread_id": "wf_abc123def456",
  "current_step": "criteria_extraction",
  "criteria": [
    {
      "name": "Industry",
      "value": "SaaS",
      "column_name": "industry",
      "description": "Software as a Service companies"
    },
    {
      "name": "Location",
      "value": "San Francisco",
      "column_name": "location",
      "description": "Company headquarters location"
    },
    {
      "name": "Employee Count",
      "value": "50-200",
      "column_name": "employee_count",
      "description": "Number of employees"
    }
  ],
  "total_target": 25
}

Step 4: Continue the Workflow

After reviewing the extracted criteria, continue the workflow:

import requests
 
response = requests.post(
    'https://chordian-core.chordian.ai/api/workflow/continue',
    json={
        'thread_id': 'wf_abc123def456',
        'total_target': 50,
        'current_criteria': [
            {
                'name': 'Industry',
                'value': 'SaaS',
                'column_name': 'industry'
            },
            {
                'name': 'Location',
                'value': 'San Francisco',
                'column_name': 'location'
            },
            {
                'name': 'Employee Count',
                'value': '50-200',
                'column_name': 'employee_count'
            }
        ]
    }
)

Step 5: Get Results

Poll the status endpoint to monitor progress:

# Check status every few seconds
curl https://chordian-core.chordian.ai/api/workflow/status/wf_abc123def456

When current_step is "completed", you’ll have access to the results in table_structure:

{
  "thread_id": "wf_abc123def456",
  "current_step": "completed",
  "table_structure": {
    "columns": [
      {
        "id": "company_name",
        "header": "Company Name",
        "type": "fixed"
      },
      {
        "id": "website",
        "header": "Website",
        "type": "fixed"
      },
      {
        "id": "industry",
        "header": "Industry",
        "type": "dynamic"
      }
    ],
    "rows": [
      {
        "id": "row_1",
        "cells": {
          "company_name": {
            "value": "Acme SaaS Inc",
            "status": "completed"
          },
          "website": {
            "value": "https://acmesaas.com",
            "status": "completed"
          },
          "industry": {
            "value": "SaaS",
            "status": "completed"
          }
        }
      }
    ],
    "current_count": 50,
    "total_target": 50
  }
}

Complete Example (JavaScript)

Here’s a complete example using JavaScript:

const API_BASE = 'https://chordian-core.chordian.ai';
const SERVICE_ID = 'your-service-id';
 
async function runWorkflow() {
  // 1. Start workflow
  const startResponse = await fetch(`${API_BASE}/api/workflow/start`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      prompt: 'Find SaaS companies in San Francisco with 50-200 employees',
      serviceId: SERVICE_ID
    })
  });
 
  const startData = await startResponse.json();
  const threadId = startData.thread_id;
  console.log('Workflow started:', threadId);
 
  // 2. Wait for criteria extraction
  await new Promise(resolve => setTimeout(resolve, 3000));
 
  // 3. Get status
  const statusResponse = await fetch(
    `${API_BASE}/api/workflow/status/${threadId}`
  );
  const status = await statusResponse.json();
  console.log('Extracted criteria:', status.criteria);
 
  // 4. Continue workflow
  const continueResponse = await fetch(`${API_BASE}/api/workflow/continue`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      thread_id: threadId,
      total_target: 50,
      current_criteria: status.criteria
    })
  });
 
  console.log('Workflow continued');
 
  // 5. Poll for completion
  let completed = false;
  while (!completed) {
    await new Promise(resolve => setTimeout(resolve, 5000));
    
    const checkResponse = await fetch(
      `${API_BASE}/api/workflow/status/${threadId}`
    );
    const checkStatus = await checkResponse.json();
    
    console.log(`Progress: ${checkStatus.table_structure?.current_count || 0}/${checkStatus.total_target}`);
    
    if (checkStatus.current_step === 'completed') {
      completed = true;
      console.log('Results:', checkStatus.table_structure);
    }
  }
}
 
runWorkflow().catch(console.error);

Next Steps

Now that you’ve completed your first workflow, explore:

Common Issues

** Warning:** Rate Limiting: If you receive 429 errors, you’re hitting rate limits. Slow down your requests.

Issue: 422 Validation Error

Cause: Missing or invalid request parameters

Solution: Check that all required fields are included and properly formatted

Issue: Workflow Stuck

Cause: Workflow may be waiting for user input

Solution: Check the current_step - if it’s waiting for continuation, call the continue endpoint

Issue: Empty Results

Cause: Criteria may be too restrictive

Solution: Broaden your search criteria or increase total_target

Need Help?