API Endpoints

Complete reference for all ClawBook API endpoints.

Status

Get System Status

Returns overall system health and component status.

GET /api/v1/status

Required Scope: read:status

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "version": "1.5.0",
    "uptime_seconds": 86400,
    "components": {
      "database": "healthy",
      "cache": "healthy",
      "ai_provider": "healthy"
    },
    "integrations": {
      "whatsapp": {
        "status": "connected",
        "phone": "+1234567890",
        "last_message": "2026-01-30T14:23:45Z"
      },
      "telegram": {
        "status": "connected",
        "bot_username": "@MyClawBot",
        "last_message": "2026-01-30T14:20:00Z"
      },
      "discord": {
        "status": "disconnected",
        "error": "Token expired"
      }
    },
    "resources": {
      "cpu_percent": 35,
      "memory_percent": 52,
      "disk_percent": 45
    }
  }
}

Messages

Send Message

Send a message to a specific platform and recipient.

POST /api/v1/messages/send

Required Scope: write:messages

Request Body:

{
  "platform": "telegram",
  "recipient": "123456789",
  "message": "Hello from API!",
  "options": {
    "parse_mode": "markdown",
    "disable_notification": false
  }
}

Parameters:

Field	Type	Required	Description
platform	string	Yes	`whatsapp`, `telegram`, `discord`
recipient	string	Yes	Platform-specific recipient ID
message	string	Yes	Message content
options	object	No	Platform-specific options

Response:

{
  "success": true,
  "data": {
    "message_id": "msg_abc123",
    "platform": "telegram",
    "recipient": "123456789",
    "status": "sent",
    "sent_at": "2026-01-30T14:30:00Z"
  }
}

Get Message

Retrieve a specific message by ID.

GET /api/v1/messages/{message_id}

Required Scope: read:messages

Response:

{
  "success": true,
  "data": {
    "id": "msg_abc123",
    "conversation_id": "conv_xyz789",
    "platform": "telegram",
    "direction": "outbound",
    "content": "Hello from API!",
    "status": "delivered",
    "created_at": "2026-01-30T14:30:00Z",
    "delivered_at": "2026-01-30T14:30:01Z"
  }
}

List Messages

Get paginated list of messages.

GET /api/v1/messages

Required Scope: read:messages

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	20	Items per page (max 100)
platform	string	all	Filter by platform
direction	string	all	`inbound` or `outbound`
start_date	string	-	ISO 8601 date
end_date	string	-	ISO 8601 date
conversation_id	string	-	Filter by conversation

Response:

{
  "success": true,
  "data": [
    {
      "id": "msg_abc123",
      "conversation_id": "conv_xyz789",
      "platform": "telegram",
      "direction": "inbound",
      "content": "What's the weather?",
      "created_at": "2026-01-30T14:25:00Z"
    },
    {
      "id": "msg_abc124",
      "conversation_id": "conv_xyz789",
      "platform": "telegram",
      "direction": "outbound",
      "content": "I don't have access to weather data...",
      "created_at": "2026-01-30T14:25:02Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 1523,
      "total_pages": 77
    }
  }
}

Conversations

List Conversations

Get paginated list of conversations.

GET /api/v1/conversations

Required Scope: read:conversations

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	20	Items per page
platform	string	all	Filter by platform
status	string	all	`active` or `archived`
start_date	string	-	ISO 8601 date
end_date	string	-	ISO 8601 date

Response:

{
  "success": true,
  "data": [
    {
      "id": "conv_xyz789",
      "platform": "telegram",
      "participant": {
        "id": "123456789",
        "name": "John Doe",
        "username": "@johndoe"
      },
      "message_count": 45,
      "last_message_at": "2026-01-30T14:25:02Z",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 89,
      "total_pages": 5
    }
  }
}

Get Conversation

Get a specific conversation with messages.

GET /api/v1/conversations/{conversation_id}

Required Scope: read:conversations

Query Parameters:

Parameter	Type	Default	Description
include_messages	boolean	false	Include recent messages
message_limit	integer	50	Max messages to include

Response:

{
  "success": true,
  "data": {
    "id": "conv_xyz789",
    "platform": "telegram",
    "participant": {
      "id": "123456789",
      "name": "John Doe",
      "username": "@johndoe"
    },
    "message_count": 45,
    "status": "active",
    "created_at": "2026-01-15T10:00:00Z",
    "messages": [
      {
        "id": "msg_abc123",
        "direction": "inbound",
        "content": "Hello!",
        "created_at": "2026-01-30T14:23:45Z"
      }
    ]
  }
}

Clear Conversation Context

Clear the AI context for a conversation.

POST /api/v1/conversations/{conversation_id}/clear

Required Scope: write:messages

Response:

{
  "success": true,
  "data": {
    "conversation_id": "conv_xyz789",
    "cleared_at": "2026-01-30T14:30:00Z",
    "messages_cleared": 45
  }
}

AI

Generate Response

Generate an AI response without sending to a platform.

POST /api/v1/ai/generate

Required Scope: write:messages

Request Body:

{
  "message": "What is the capital of France?",
  "context": [
    {"role": "user", "content": "Hi"},
    {"role": "assistant", "content": "Hello! How can I help?"}
  ],
  "options": {
    "model": "claude-3-5-sonnet",
    "max_tokens": 500,
    "temperature": 0.7
  }
}

Response:

{
  "success": true,
  "data": {
    "response": "The capital of France is Paris.",
    "model": "claude-3-5-sonnet-20241022",
    "tokens": {
      "input": 45,
      "output": 12
    },
    "latency_ms": 1250
  }
}

Get AI Status

Check AI provider status and usage.

GET /api/v1/ai/status

Required Scope: read:status

Response:

{
  "success": true,
  "data": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20241022",
    "status": "available",
    "usage": {
      "today": {
        "requests": 145,
        "input_tokens": 50000,
        "output_tokens": 25000,
        "cost_usd": 0.75
      },
      "month": {
        "requests": 3500,
        "input_tokens": 1250000,
        "output_tokens": 620000,
        "cost_usd": 18.50
      }
    }
  }
}

Integrations

List Integrations

Get status of all integrations.

GET /api/v1/integrations

Required Scope: read:status

Response:

{
  "success": true,
  "data": [
    {
      "platform": "whatsapp",
      "status": "connected",
      "details": {
        "phone": "+1234567890",
        "name": "My WhatsApp"
      },
      "connected_at": "2026-01-15T10:00:00Z"
    },
    {
      "platform": "telegram",
      "status": "connected",
      "details": {
        "bot_username": "@MyClawBot",
        "bot_id": "7123456789"
      },
      "connected_at": "2026-01-10T08:00:00Z"
    }
  ]
}

Reconnect Integration

Trigger reconnection for a platform.

POST /api/v1/integrations/{platform}/reconnect

Required Scope: admin:settings

Response:

{
  "success": true,
  "data": {
    "platform": "whatsapp",
    "status": "reconnecting",
    "message": "Reconnection initiated. Check status in 30 seconds."
  }
}

Admin

Get Settings

Retrieve current configuration.

GET /api/v1/admin/settings

Required Scope: admin:settings

Update Settings

Update configuration settings.

PATCH /api/v1/admin/settings

Required Scope: admin:settings

Request Body:

{
  "ai": {
    "temperature": 0.8,
    "max_tokens": 2000
  },
  "rate_limits": {
    "messages_per_minute": 15
  }
}

Get Statistics

Get usage statistics.

GET /api/v1/admin/stats

Required Scope: admin:settings

Query Parameters:

Parameter	Type	Default	Description
period	string	7d	`1d`, `7d`, `30d`, `90d`
group_by	string	day	`hour`, `day`, `week`

Response:

{
  "success": true,
  "data": {
    "period": {
      "start": "2026-01-23T00:00:00Z",
      "end": "2026-01-30T00:00:00Z"
    },
    "totals": {
      "messages": 5432,
      "conversations": 89,
      "tokens": 1500000,
      "cost_usd": 15.00
    },
    "by_platform": {
      "whatsapp": 2500,
      "telegram": 1932,
      "discord": 1000
    },
    "timeline": [
      {"date": "2026-01-24", "messages": 750},
      {"date": "2026-01-25", "messages": 820}
    ]
  }
}

Error Codes

Code	Description
`INVALID_REQUEST`	Malformed request body
`INVALID_PARAMETER`	Invalid parameter value
`MISSING_PARAMETER`	Required parameter missing
`RESOURCE_NOT_FOUND`	Requested resource doesn't exist
`PLATFORM_NOT_CONNECTED`	Target platform not connected
`AI_PROVIDER_ERROR`	Error from AI provider
`RATE_LIMIT_EXCEEDED`	Too many requests
`INTERNAL_ERROR`	Unexpected server error

Next Steps

Authentication - API key management
Webhooks - Real-time event notifications

Status​

Get System Status​

Messages​

Send Message​

Get Message​

List Messages​

Conversations​

List Conversations​

Get Conversation​

Clear Conversation Context​

AI​

Generate Response​

Get AI Status​

Integrations​

List Integrations​

Reconnect Integration​

Admin​

Get Settings​

Update Settings​

Get Statistics​

Error Codes​

Next Steps​

Status

Get System Status

Messages

Send Message

Get Message

List Messages

Conversations

List Conversations

Get Conversation

Clear Conversation Context

AI

Generate Response

Get AI Status

Integrations

List Integrations

Reconnect Integration

Admin

Get Settings

Update Settings

Get Statistics

Error Codes

Next Steps