API Overview

ClawBook provides a REST API for advanced users who want to integrate with external systems or build custom automations.

Base URL

https://your-domain.com/api/v1

Or if using IP:

https://YOUR_VPS_IP:8443/api/v1

API Features

Feature	Description
Messages	Send and receive messages programmatically
Conversations	Access conversation history
Status	Check system and integration status
Configuration	Update settings via API
Webhooks	Receive real-time events

Quick Start

1. Generate API Key

1. Log into dashboard
2. Go to Settings → API
3. Click Generate API Key
4. Copy and store securely

2. Test Connection

curl -X GET "https://your-domain.com/api/v1/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "status": "healthy",
  "version": "1.5.0",
  "uptime_seconds": 86400,
  "integrations": {
    "whatsapp": "connected",
    "telegram": "connected",
    "discord": "disconnected"
  }
}

3. Send a Message

curl -X POST "https://your-domain.com/api/v1/messages/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "telegram",
    "recipient": "123456789",
    "message": "Hello from API!"
  }'

Response Format

All responses follow this structure:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-01-30T14:30:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": null
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-01-30T14:30:00Z"
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limited
500	Internal Server Error

Rate Limits

Tier	Requests/Minute	Requests/Hour
Standard	60	1,000
Pro	120	3,000
Elite	300	10,000

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1706624400

Pagination

List endpoints support pagination:

curl "https://your-domain.com/api/v1/conversations?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes pagination metadata:

{
  "success": true,
  "data": [...],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 150,
      "total_pages": 8
    }
  }
}

Filtering

Use query parameters to filter results:

# Filter by date
?start_date=2026-01-01&end_date=2026-01-31

# Filter by platform
?platform=whatsapp

# Filter by status
?status=active

# Combine filters
?platform=telegram&start_date=2026-01-01

Sorting

# Sort by field (ascending)
?sort=created_at

# Sort descending
?sort=-created_at

# Multiple sorts
?sort=-created_at,platform

SDK Libraries

Python

pip install clawbook-sdk

from clawbook import ClawBook

client = ClawBook(api_key="YOUR_API_KEY", base_url="https://your-domain.com")

# Check status
status = client.status()
print(status.version)

# Send message
result = client.messages.send(
    platform="telegram",
    recipient="123456789",
    message="Hello!"
)

JavaScript/Node.js

npm install clawbook-sdk

const ClawBook = require('clawbook-sdk');

const client = new ClawBook({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://your-domain.com'
});

// Check status
const status = await client.status();
console.log(status.version);

// Send message
const result = await client.messages.send({
  platform: 'telegram',
  recipient: '123456789',
  message: 'Hello!'
});

PHP

composer require clawbook/sdk

use ClawBook\Client;

$client = new Client([
    'api_key' => 'YOUR_API_KEY',
    'base_url' => 'https://your-domain.com'
]);

// Check status
$status = $client->status();
echo $status->version;

// Send message
$result = $client->messages()->send([
    'platform' => 'telegram',
    'recipient' => '123456789',
    'message' => 'Hello!'
]);

API Versioning

The current API version is v1.

Version is specified in the URL:

/api/v1/endpoint

When new versions are released:

• Old versions remain supported for 12 months
• Deprecation warnings added to responses
• Migration guides provided

Security Best Practices

1. Keep API keys secret - Never expose in client-side code
2. Use HTTPS - All requests must be over HTTPS
3. Rotate keys - Regenerate keys periodically
4. Limit permissions - Create keys with minimal required scope
5. Monitor usage - Check for unusual activity

Getting Help

• Authentication - API key management
• Endpoints - Full endpoint reference
• Webhooks - Real-time event notifications

Changelog

v1.0.0 (2026-01-15)

• Initial API release
• Messages, Conversations, Status endpoints
• Webhook support