API Reference

Complete API documentation for integrating Cordiul with your applications.

Authentication

Programmatic requests use an API key in the Authorization header. Endpoints that support API keys also accept Clerk session (browser) auth.

Header:Authorization: Bearer YOUR_API_KEYprogrammatic

header

Authorization: Bearer ck_live_xxxxxxxxxxxx

Create and manage keys under Settings → API Keys. Supported endpoints (e.g. List calls) accept this Bearer token for server-to-server or script access.

Base URL

url

https://your-domain.com/api

Endpoints

POST

Create API Key

Creates a new API key for authentication. API keys are used to authenticate requests to the API.

Endpoint:POST /api/api-keys

Request Body

json

{
  "name": "My API Key",
  "permissions": ["calls:read", "calls:write"]
}

Code Examples

bash

curl --request POST \
  --url 'https://your-domain.com/api/api-keys' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My API Key",
  "permissions": [
    "calls:read",
    "calls:write"
  ]
}'

Response

json

{
  "success": true,
  "data": {
    "id": "key_123",
    "name": "My API Key",
    "key": "sk_live_...",
    "created_at": "2024-01-09T20:00:00Z"
  }
}

GET

Get All API Keys

List all API keys for the current user.

Endpoint:GET /api/api-keys

Code Examples

bash

curl --request GET \
  --url 'https://your-domain.com/api/api-keys' \
  --header 'x-api-key: YOUR_API_KEY' \

Response

json

{
  "success": true,
  "data": {
    "keys": [
      {
        "id": "key_123",
        "name": "My API Key",
        "created_at": "2024-01-09T20:00:00Z",
        "last_used_at": "2024-01-09T21:00:00Z"
      }
    ]
  }
}

POST

Create Call

Create a new call. This endpoint initiates a call to the specified phone number.

Endpoint:POST /api/calls/create

Request Body

contact_idrequiredstring - Contact ID

phone_numberrequiredstring - Phone number in E.164 format

from_numberoptionalstring - Phone number to call from

json

{
  "contact_id": "contact_123",
  "phone_number": "+1234567890",
  "from_number": "+0987654321"
}

Code Examples

bash

curl --request POST \
  --url 'https://your-domain.com/api/calls/create' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "contact_id": "contact_123",
  "phone_number": "+1234567890",
  "from_number": "+0987654321"
}'

Response

json

{
  "success": true,
  "data": {
    "id": "call_123",
    "status": "initiating",
    "contact_id": "contact_123",
    "phone_number": "+1234567890",
    "created_at": "2024-01-09T20:00:00Z"
  }
}

GET

Get All Calls

Retrieve a list of calls with optional filtering by status, contact, or date range.

Endpoint:GET /api/calls/list

Query Parameters

limitoptionalnumber - Number of results (default: 50, max: 5000)

statusoptionalstring - Filter by call status

contact_idoptionalstring - Filter by contact ID

Code Examples

bash

curl --request GET \
  --url 'https://your-domain.com/api/calls/list?limit=50&status=completed' \
  --header 'x-api-key: YOUR_API_KEY' \

Response

json

{
  "success": true,
  "data": {
    "calls": [
      {
        "id": "call_123",
        "status": "completed",
        "contact_id": "contact_123",
        "phone_number": "+1234567890",
        "duration": 120,
        "created_at": "2024-01-09T20:00:00Z"
      }
    ],
    "total": 1
  }
}

Response Format

All API responses follow a consistent format:

json

{
  "success": true,
  "data": { ... },
  "error": null
}

Error Codes

400 Bad Request

Invalid request parameters or missing required fields

401 Unauthorized

Missing or invalid API key

403 Forbidden

API key doesn't have required permissions

404 Not Found

Resource not found

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Server error - please try again later