KlairoAI API
Reference

Overview

The KlairoAI REST API lets you programmatically control your AI employee — Aria — and all surrounding infrastructure. Build custom integrations, connect your own CRM, trigger automations, or stream AI responses directly in your product.

Error format

Every error response follows this consistent shape:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Bearer token is missing or invalid.",
    "status": 401
  }
}

Rate limits

Authentication

KlairoAI uses JWT (JSON Web Tokens). Exchange your credentials for a token, then include it in the Authorization header of every subsequent request.

Content-Type: application/json

{
  "email": "you@company.com",
  "password": "supersecret123"
}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-03-12T11:22:00Z",
  "user": {
    "id": "usr_01JNABCXYZ",
    "email": "you@company.com",
    "name": "Daniel Kmit",
    "plan": "growth"
  }
}

Authorization: Bearer <current_token>
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-03-13T11:22:00Z"
}

Authorization: Bearer kl_live_a1b2c3d4e5f6...

curl -X POST https://klairoai.com/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kl_live_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12345678" \
  -d '{
    "message": "Draft a follow-up email for the Smith proposal",
    "action": "chat"
  }'

curl https://klairoai.com/api/keys?action=validate \
  -H "Authorization: Bearer kl_live_YOUR_API_KEY"

{
  "valid": true,
  "user_id": "usr_01JNABCXYZ",
  "email": "you@company.com",
  "plan": "pro",
  "key_name": "Production App",
  "usage": 42,
  "limit": 1000
}

Chat with Aria

Send messages to Aria and receive intelligent AI responses. Aria has full context of your business, clients, and automations. Supports multi-turn conversations via conversation_id.

Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "Summarise the last 3 client follow-ups and suggest next steps.",
  "conversation_id": "conv_01JNXYZ987",
  "context": {
    "contact_id": "cnt_01JNABC123"
  },
  "stream": false
}

{
  "conversation_id": "conv_01JNXYZ987",
  "message_id": "msg_01JNA000XYZ",
  "role": "assistant",
  "content": "Here's a summary of the last 3 follow-ups with Acme Corp...",
  "created_at": "2026-03-11T11:22:00Z",
  "usage": {
    "prompt_tokens": 420,
    "completion_tokens": 215,
    "total_tokens": 635
  }
}

Automations

Automations are AI-powered workflows — email sequences, lead follow-ups, scheduling chains, and more. Full CRUD support plus a manual trigger endpoint for immediate execution.

Authorization: Bearer <token>

{
  "data": [
    {
      "id": "auto_01JNABC001",
      "name": "New Lead Follow-up",
      "status": "active",
      "trigger": "contact_created",
      "steps": 4,
      "last_run": "2026-03-10T09:15:00Z",
      "created_at": "2026-02-01T08:00:00Z"
    }
  ],
  "total": 12,
  "limit": 20,
  "offset": 0
}

Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Proposal Follow-up Sequence",
  "trigger": "contact_tag_added",
  "status": "active",
  "steps": [
    {
      "type": "send_email",
      "delay_hours": 24,
      "template_id": "tpl_01JN_FOLLOWUP"
    },
    {
      "type": "aria_task",
      "delay_hours": 72,
      "instruction": "Draft a personalised check-in email for this lead."
    }
  ]
}

{
  "id": "auto_01JNABC999",
  "name": "Proposal Follow-up Sequence",
  "status": "active",
  "trigger": "contact_tag_added",
  "steps": 2,
  "created_at": "2026-03-11T11:22:00Z"
}

Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "paused",
  "name": "Proposal Follow-up v2"
}

{
  "id": "auto_01JNABC999",
  "name": "Proposal Follow-up v2",
  "status": "paused",
  "updated_at": "2026-03-11T12:00:00Z"
}

DELETE /api/automations/auto_01JNABC999
Authorization: Bearer <token>

Authorization: Bearer <token>
Content-Type: application/json

{
  "contact_id": "cnt_01JNABC123",
  "variables": {
    "first_name": "Alex",
    "company": "Acme Corp"
  }
}

{
  "run_id": "run_01JNXYZ111",
  "automation_id": "auto_01JNABC999",
  "status": "queued",
  "contact_id": "cnt_01JNABC123",
  "triggered_at": "2026-03-11T11:22:00Z"
}

Notifications

Retrieve in-app notifications for your account and mark them as read. Notifications are generated by Aria, automation runs, system events, and webhook deliveries.

Authorization: Bearer <token>

{
  "data": [
    {
      "id": "ntf_01JNXYZ555",
      "type": "automation_completed",
      "title": "Automation run complete",
      "body": "Proposal Follow-up Sequence finished for Alex at Acme Corp.",
      "read": false,
      "metadata": {
        "automation_id": "auto_01JNABC999",
        "run_id": "run_01JNXYZ111"
      },
      "created_at": "2026-03-11T11:30:00Z"
    }
  ],
  "unread_count": 4,
  "total": 18
}

Authorization: Bearer <token>
Content-Type: application/json

{
  "ids": ["ntf_01JNXYZ555", "ntf_01JNXYZ556"]
}

// — or mark all as read —

{
  "all": true
}

{
  "updated": 2,
  "unread_count": 2
}

Contacts

Sync your leads and clients with KlairoAI. Aria uses contact context to personalise outreach, proposals, and follow-ups. All contact fields are stored as schemaless metadata.

Authorization: Bearer <token>

{
  "data": [
    {
      "id": "cnt_01JNABC123",
      "name": "Alex Johnson",
      "email": "alex@acmecorp.com",
      "company": "Acme Corp",
      "tags": ["prospect", "proposal-sent"],
      "metadata": {
        "deal_value": 12000,
        "source": "cold-email"
      },
      "created_at": "2026-02-15T08:00:00Z",
      "updated_at": "2026-03-10T14:30:00Z"
    }
  ],
  "total": 87,
  "limit": 20,
  "offset": 0
}

Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Sarah Chen",
  "email": "sarah@techstartup.io",
  "company": "TechStartup",
  "tags": ["prospect", "inbound"],
  "metadata": {
    "source": "website-form",
    "budget": "5000-10000"
  }
}

{
  "id": "cnt_01JNXYZ789",
  "name": "Sarah Chen",
  "email": "sarah@techstartup.io",
  "company": "TechStartup",
  "tags": ["prospect", "inbound"],
  "metadata": { "source": "website-form", "budget": "5000-10000" },
  "created_at": "2026-03-11T11:22:00Z"
}

Authorization: Bearer <token>
Content-Type: application/json

{
  "tags": ["client", "onboarding"],
  "metadata": {
    "deal_value": 8500,
    "signed_at": "2026-03-11"
  }
}

{
  "id": "cnt_01JNXYZ789",
  "name": "Sarah Chen",
  "tags": ["client", "onboarding"],
  "metadata": { "deal_value": 8500, "signed_at": "2026-03-11" },
  "updated_at": "2026-03-11T11:45:00Z"
}

Webhooks

KlairoAI pushes real-time events to your server when things happen — automation runs complete, contacts are created, Aria generates a response, or a message is sent. Register an HTTPS endpoint and we'll deliver signed JSON payloads instantly.

Event types

Delivery headers

Retry policy

If your endpoint returns a non-2xx response, KlairoAI retries with exponential backoff: immediate → 5 min → 30 min → 2 hours → 8 hours. After 5 attempts, the delivery is marked as failed. All delivery attempts are logged and visible in your portal.

Plan limits

Payload shape

{
  "event": "automation.run.completed",
  "event_id": "evt_01JNXYZ222",
  "created_at": "2026-03-11T11:30:00Z",
  "data": {
    "run_id": "run_01JNXYZ111",
    "automation_id": "auto_01JNABC999",
    "automation_name": "Proposal Follow-up Sequence",
    "contact_id": "cnt_01JNABC123",
    "status": "completed",
    "steps_run": 2,
    "duration_ms": 4200
  }
}

Signature verification

const crypto = require('crypto');

app.post('/webhook/klairo', express.raw({ type: '*/*' }), (req, res) => {
  const sig     = req.headers['x-klairoai-signature'];
  const secret  = process.env.KLAIRO_WEBHOOK_SECRET;
  const digest  = crypto.createHmac('sha256', secret)
                        .update(req.body)
                        .digest('hex');

  if (sig !== `sha256=${digest}`) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  console.log('Received event:', event.event);
  res.sendStatus(200);
});

Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://myapp.com/webhook/klairo",
  "events": [
    "automation.run.completed",
    "contact.created",
    "chat.message.created"
  ],
  "description": "Production webhook receiver"
}

{
  "id": "wh_01JNXYZ333",
  "url": "https://myapp.com/webhook/klairo",
  "events": ["automation.run.completed", "contact.created", "chat.message.created"],
  "secret": "whsec_K9xB2mLvQ3...",
  "status": "active",
  "created_at": "2026-03-11T11:22:00Z"
}

Authorization: Bearer <token>

{
  "data": [
    {
      "id": "wh_01JNXYZ333",
      "url": "https://myapp.com/webhook/klairo",
      "events": ["automation.run.completed", "contact.created"],
      "status": "active",
      "last_delivery": "2026-03-11T11:30:00Z",
      "created_at": "2026-03-11T11:22:00Z"
    }
  ]
}

DELETE /api/webhooks/wh_01JNXYZ333
Authorization: Bearer <token>

{
  "id": 42
}

{
  "ok": true,
  "delivered": true,
  "statusCode": 200,
  "responseBody": "OK"
}

GET /api/webhooks?action=deliveries&id=42
Authorization: Bearer <token>

{
  "deliveries": [
    {
      "id": 1,
      "webhook_id": 42,
      "event": "automation.run",
      "status_code": 200,
      "attempt_count": 1,
      "delivered_at": "2026-03-15T08:00:00Z",
      "created_at": "2026-03-15T08:00:00Z"
    }
  ]
}

Usage Analytics

Retrieve aggregated usage statistics for your KlairoAI account — message volume, automation runs, contact activity, and API call counts. Data is available by day, week, or month.

Authorization: Bearer <token>

curl https://api.klairoai.com/v1/analytics?period=month&from=2026-03-01 \
  -H "Authorization: Bearer <token>"

{
  "period": "month",
  "from": "2026-03-01",
  "to": "2026-03-31",
  "summary": {
    "chat_messages": 1842,
    "automation_runs": 314,
    "contacts_created": 57,
    "api_calls": 2987,
    "webhooks_delivered": 289
  },
  "daily": [
    {
      "date": "2026-03-11",
      "chat_messages": 63,
      "automation_runs": 11,
      "contacts_created": 2,
      "api_calls": 98
    }
  ],
  "quota": {
    "plan": "growth",
    "chat_limit_daily": 5000,
    "chat_used_today": 63,
    "api_limit_per_minute": 300
  }
}

Current User

Retrieve profile and plan information for the authenticated user. Useful for verifying tokens and checking plan limits in your integration.

Authorization: Bearer <token>

curl https://api.klairoai.com/v1/users/me \
  -H "Authorization: Bearer <token>"

{
  "id": "usr_01JNABCXYZ",
  "name": "Daniel Kmit",
  "email": "daniel@mycompany.com",
  "avatar_url": "https://klairoai.com/avatars/usr_01JNABCXYZ.jpg",
  "plan": {
    "id": "growth",
    "label": "Growth",
    "status": "active",
    "renews_at": "2026-04-01T00:00:00Z"
  },
  "quota": {
    "chat_limit_daily": 5000,
    "api_limit_per_minute": 300,
    "automations_max": 50
  },
  "created_at": "2026-01-15T09:00:00Z",
  "last_seen_at": "2026-03-11T11:00:00Z"
}

Error Codes

All errors follow a consistent JSON shape. The code field is a machine-readable string you can use to handle errors programmatically.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Slow down and retry after 1 minute.",
    "status": 429,
    "retry_after": 60
  }
}

Rate Limits

Rate limits are applied per account. When exceeded, you'll receive a 429 Too Many Requests response with a Retry-After header indicating seconds until the limit resets.

Rate limit headers

Every response includes these headers so you can track consumption:

SDKs & Libraries

Official KlairoAI SDKs are in active development. Until they ship, use the REST API directly — it's fully documented above and works with any HTTP client.

Using the API today — Node.js example

const KLAIRO_TOKEN = process.env.KLAIRO_API_TOKEN;
const BASE = 'https://api.klairoai.com/v1';

async function chatWithAria(message) {
  const res = await fetch(`${BASE}/chat`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${KLAIRO_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ message })
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error.message);
  }

  return res.json();
}

const reply = await chatWithAria('Summarise today\'s leads.');
console.log(reply.content);

Python example

import os, requests

TOKEN = os.environ["KLAIRO_API_TOKEN"]
BASE  = "https://api.klairoai.com/v1"

def chat_with_aria(message: str) -> dict:
    r = requests.post(
        f"{BASE}/chat",
        headers={"Authorization": f"Bearer {TOKEN}"},
        json={"message": message},
        timeout=30
    )
    r.raise_for_status()
    return r.json()

reply = chat_with_aria("List all automations currently active.")
print(reply["content"])