Configuration

The Cordia SDK is highly configurable. All options have sensible defaults so you can get started with just apiKey and botId.

All Options

Option (JS / Python)	Type	Default	Description
`apiKey / api_key`	`string / str`	required	Your bot's API key from the Cordia dashboard
`botId / bot_id`	`string / str`	required	Your bot's unique ID from the Cordia dashboard
`baseUrl / base_url`	`string / str`	`https://api.cordialane.com/api/v1`	API base URL (or set `CORDIA_API_URL` env var)
`heartbeatInterval / heartbeat_interval`	`number / int`	`30000`	Heartbeat interval in milliseconds (min: 5000)
`autoHeartbeat / auto_heartbeat`	`boolean / bool`	`true / True`	Auto-start heartbeat on client creation
`debug`	`boolean / bool`	`false / False`	Enable debug logging to console
`batchSize / batch_size`	`number / int`	`10 / 50`	Max events before auto-flush (1-100)
`flushInterval / flush_interval`	`number / int`	`5000 / 10000`	Auto-flush interval in milliseconds (min: 1000)
`maxRetries` (JS only)	`number`	`3`	Max retry attempts on failure (0-10)
`timeout` (JS only)	`number`	`10000`	Request timeout in milliseconds (min: 1000)

URL Resolution

The API base URL is resolved in this priority order:

config.baseUrl / base_url — explicitly passed in config
CORDIA_API_URL — environment variable
https://api.cordialane.com/api/v1 — default fallback

JavaScript / TypeScript

Development setup

typescript

// Option 1: Pass directly in config
const cordia = new CordiaClient({
  apiKey: 'your-key',
  botId: 'your-bot',
  baseUrl: 'https://cordlane-brain.onrender.com/api/v1',
});

// Option 2: Use environment variable
// .env file: CORDIA_API_URL=https://cordlane-brain.onrender.com/api/v1
const cordia = new CordiaClient({
  apiKey: 'your-key',
  botId: 'your-bot',
  // baseUrl will use CORDIA_API_URL automatically
});

Python

Development setup

python

# Option 1: Pass directly in config
cordia_client = cordia.CordiaClient(
    api_key="your-key",
    bot_id="your-bot",
    base_url="https://cordlane-brain.onrender.com/api/v1",
)

# Option 2: Use environment variable
import os
cordia_client = cordia.CordiaClient(
    api_key=os.getenv("CORDIA_API_KEY"),
    bot_id=os.getenv("CORDIA_BOT_ID"),
    base_url=os.getenv("CORDIA_API_URL", "https://cordlane-brain.onrender.com/api/v1"),
)

Environment Variables

Variable	Description
`CORDIA_API_URL`	Override the default API base URL
`CORDIA_API_KEY`	Your bot's API key
`CORDIA_BOT_ID`	Your bot's unique ID

Full Config Example

JavaScript / TypeScript

Full configuration

typescript

import { CordiaClient } from 'cordia';

const cordia = new CordiaClient({
  // Required
  apiKey: process.env.CORDIA_API_KEY!,
  botId: process.env.CORDIA_BOT_ID!,

  // Optional — API URL
  baseUrl: 'https://cordlane-brain.onrender.com/api/v1',

  // Optional — Heartbeat
  heartbeatInterval: 30000,  // 30 seconds
  autoHeartbeat: true,

  // Optional — Event batching
  batchSize: 10,
  flushInterval: 5000,  // 5 seconds

  // Optional — Reliability
  maxRetries: 3,
  timeout: 10000,  // 10 seconds

  // Optional — Debugging
  debug: process.env.NODE_ENV === 'development',
});

Python

Full configuration

python

import cordia
import os

cordia_client = cordia.CordiaClient(
    # Required
    api_key=os.getenv("CORDIA_API_KEY"),
    bot_id=os.getenv("CORDIA_BOT_ID"),

    # Optional — API URL
    base_url="https://cordlane-brain.onrender.com/api/v1",

    # Optional — Heartbeat
    heartbeat_interval=30000,  # 30 seconds
    auto_heartbeat=True,

    # Optional — Event batching
    batch_size=10,
    flush_interval=5000,  # 5 seconds

    # Optional — Debugging
    debug=True,
)
# Don't forget to call start() to initialize the background tasks
cordia_client.start(bot.loop)

⚠️Validation

The SDK validates all config options on initialization. If you pass invalid values (e.g., negative batch size), it will throw a descriptive error at startup rather than failing silently later.

Installation

Commands