API Documentation

Authorization: Bearer aivo_sk_your_api_key_here

curl -s -H 'Authorization: Bearer aivo_sk_your_api_key_here' \
  'https://aivo.bz/api/v1/calls?limit=5'

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

Base URL: https://aivo.bz/api/v1

Content-Type: application/json
Accept: application/json

curl -s -H 'Authorization: Bearer aivo_sk_...' \
  'https://aivo.bz/api/v1/calls?limit=2&status=completed'

{
  "data": [
    {
      "id": "clx1abc...",
      "callerNumber": "+5012279446",
      "from": "+5012279446",
      "to": "+5012001234",
      "direction": "inbound",
      "durationSeconds": 142,
      "status": "completed",
      "summary": "Customer asked about business hours and booked an appointment for Tuesday.",
      "aiConfidenceScore": 0.94,
      "costCents": 12,
      "startedAt": "2026-03-29T10:15:00Z",
      "endedAt": "2026-03-29T10:17:22Z",
      "createdAt": "2026-03-29T10:15:00Z"
    }
  ],
  "meta": {
    "cursor": "clx1abc...",
    "hasMore": true
  }
}

curl -s -X POST -H 'Authorization: Bearer aivo_sk_...' \
  -H 'Content-Type: application/json' \
  'https://aivo.bz/api/v1/contacts' \
  -d '{
    "name": "Maria Santos",
    "phone": "+5016123456",
    "email": "maria@example.com",
    "notes": "Prefers morning appointments"
  }'

{
  "data": {
    "id": "clx2def...",
    "name": "Maria Santos",
    "phone": "+5016123456",
    "email": "maria@example.com",
    "notes": "Prefers morning appointments",
    "createdAt": "2026-03-29T11:00:00Z",
    "updatedAt": "2026-03-29T11:00:00Z"
  }
}

curl -s -H 'Authorization: Bearer aivo_sk_...' \
  'https://aivo.bz/api/v1/appointments/available-slots?date=2026-04-01'

{
  "data": [
    { "start": "2026-04-01T09:00:00Z", "end": "2026-04-01T09:30:00Z" },
    { "start": "2026-04-01T09:30:00Z", "end": "2026-04-01T10:00:00Z" },
    { "start": "2026-04-01T10:00:00Z", "end": "2026-04-01T10:30:00Z" }
  ]
}

curl -s -X POST -H 'Authorization: Bearer aivo_sk_...' \
  -H 'Content-Type: application/json' \
  'https://aivo.bz/api/v1/messages' \
  -d '{
    "to": "+5016001234",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "type": "sms"
  }'

{
  "data": {
    "id": "msg_abc123",
    "to": "+5016001234",
    "from": "+5012279446",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "type": "sms",
    "status": "queued",
    "direction": "outbound",
    "createdAt": "2026-04-01T14:30:00Z"
  }
}

curl -s -X POST -H 'Authorization: Bearer aivo_sk_...' \
  -H 'Content-Type: application/json' \
  'https://aivo.bz/api/v1/messages' \
  -d '{
    "to": "+5016001234",
    "body": "Here is your receipt",
    "type": "mms",
    "mediaUrl": "https://aivo.bz/receipts/inv-001.pdf"
  }'

curl -s -H 'Authorization: Bearer aivo_sk_...' \
  'https://aivo.bz/api/v1/messages?direction=inbound&limit=20'

curl -s -X POST -H 'Authorization: Bearer aivo_sk_...' \
  -H 'Content-Type: application/json' \
  'https://aivo.bz/api/v1/knowledge' \
  -d '{
    "title": "Business Hours",
    "content": "We are open Monday through Friday, 8am to 5pm. Closed on weekends and public holidays.",
    "type": "faq"
  }'

curl -s -H 'Authorization: Bearer aivo_sk_...' \
  'https://aivo.bz/api/v1/business'

{
  "data": {
    "name": "Casa Maya Restaurant",
    "phone": "+5012279446",
    "timezone": "America/Belize",
    "plan": "professional",
    "businessHours": {
      "monday": { "open": "08:00", "close": "22:00" },
      "tuesday": { "open": "08:00", "close": "22:00" }
    }
  }
}

POST https://your-app.com/webhooks/aivo
Content-Type: application/json
X-AIVO-Signature: ed25519:<base64-signature>
X-AIVO-Timestamp: 1711699200

{
  "event": "call.completed",
  "timestamp": "2026-03-29T12:00:00Z",
  "data": {
    "id": "clx1abc...",
    "direction": "inbound",
    "from": "+5012279446",
    "to": "+5012001234",
    "durationSeconds": 142,
    "status": "completed",
    "summary": "Customer booked an appointment for Tuesday."
  }
}

import { verify } from "crypto";

function verifyWebhook(req: Request, publicKey: string): boolean {
  const signature = req.headers.get("X-AIVO-Signature")?.replace("ed25519:", "");
  const timestamp = req.headers.get("X-AIVO-Timestamp");
  const body = await req.text();

  if (!signature || !timestamp) return false;

  // Check timestamp freshness (5 min window)
  const age = Date.now() / 1000 - parseInt(timestamp);
  if (Math.abs(age) > 300) return false;

  // Verify Ed25519 signature
  const payload = timestamp + "." + body;
  return verify(
    null,
    Buffer.from(payload),
    { key: publicKey, format: "pem" },
    Buffer.from(signature, "base64")
  );
}

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1711699260

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}

{
  "data": [...],
  "meta": {
    "cursor": "clx1abc...",  // Pass as ?cursor= for next page
    "hasMore": true           // false when no more results
  }
}

# First page
curl -s -H 'Authorization: Bearer aivo_sk_...' \
  'https://aivo.bz/api/v1/calls?limit=20'

# Next page (use cursor from previous response)
curl -s -H 'Authorization: Bearer aivo_sk_...' \
  'https://aivo.bz/api/v1/calls?limit=20&cursor=clx1abc...'