API Reference
Complete reference documentation for the BotCadence API. Build powerful integrations and automate your workflows programmatically.
Authentication
All API requests require authentication using an API key.
Getting Your API Key
API Keys Section
Find the “API Keys” section
Generate Key
Click “Generate New Key” and save it securely
Keep your API key secure! Never commit it to version control or share it publicly.
Using Your API Key
Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Base URL
All API requests should be made to:
https://api.botcadence.com/v1
Workflows
Manage your automation workflows programmatically.
List Workflows
Retrieve all workflows in your account.
curl -X GET https://api.botcadence.com/v1/workflows \
-H "Authorization: Bearer YOUR_API_KEY"
{
"data": [
{
"id": "wf_123456",
"name": "Welcome Email",
"status": "active",
"created_at": "2025-12-30T10:00:00Z",
"updated_at": "2025-12-30T12:00:00Z"
}
],
"total": 1,
"page": 1,
"per_page": 20
}
Create Workflow
Create a new automation workflow.
curl -X POST https://api.botcadence.com/v1/workflows \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "New Workflow",
"trigger": {
"type": "webhook",
"event": "user.created"
},
"actions": [
{
"type": "send_email",
"config": {
"to": "{{user.email}}",
"subject": "Welcome!",
"body": "Thanks for joining!"
}
}
]
}'
| Parameter | Type | Required | Description |
|---|
name | string | Yes | Workflow name |
trigger | object | Yes | Trigger configuration |
actions | array | Yes | List of actions to execute |
status | string | No | Initial status (default: “draft”) |
Get Workflow
Retrieve a specific workflow by ID.
GET /v1/workflows/{workflow_id}
curl -X GET https://api.botcadence.com/v1/workflows/wf_123456 \
-H "Authorization: Bearer YOUR_API_KEY"
Update Workflow
Update an existing workflow.
PATCH /v1/workflows/{workflow_id}
Delete Workflow
Delete a workflow permanently.
DELETE /v1/workflows/{workflow_id}
This action cannot be undone. Make sure you want to permanently delete this workflow.
Executions
Track and manage workflow executions.
List Executions
Get execution history for a workflow.
GET /v1/workflows/{workflow_id}/executions
| Parameter | Type | Description |
|---|
status | string | Filter by status (success, failed, running) |
from | datetime | Start date for filtering |
to | datetime | End date for filtering |
page | integer | Page number (default: 1) |
per_page | integer | Results per page (default: 20, max: 100) |
{
"data": [
{
"id": "exec_789012",
"workflow_id": "wf_123456",
"status": "success",
"started_at": "2025-12-30T14:30:00Z",
"completed_at": "2025-12-30T14:30:05Z",
"duration_ms": 5000
}
],
"total": 150,
"page": 1,
"per_page": 20
}
Get Execution Details
Retrieve detailed information about a specific execution.
GET /v1/executions/{execution_id}
Webhooks
Manage webhook endpoints for triggering workflows.
Create Webhook
Generate a new webhook URL.
curl -X POST https://api.botcadence.com/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wf_123456",
"event": "user.created"
}'
{
"id": "hook_345678",
"url": "https://api.botcadence.com/webhooks/hook_345678",
"workflow_id": "wf_123456",
"event": "user.created",
"created_at": "2025-12-30T10:00:00Z"
}
Rate Limits
API requests are rate limited to ensure fair usage and system stability.
| Plan | Requests per minute | Requests per day |
|---|
| Free | 60 | 1,000 |
| Pro | 300 | 10,000 |
| Enterprise | Custom | Custom |
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1735574400
Error Handling
The API uses standard HTTP status codes and returns detailed error messages.
Status Codes
| Code | Description |
|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
{
"error": {
"code": "invalid_request",
"message": "The 'name' field is required",
"details": {
"field": "name",
"issue": "required"
}
}
}
SDKs and Libraries
JavaScript/TypeScript
Python
Go
npm install @botcadence/sdk
import { BotCadence } from '@botcadence/sdk';
const client = new BotCadence('YOUR_API_KEY');
const workflows = await client.workflows.list();
from botcadence import Client
client = Client('YOUR_API_KEY')
workflows = client.workflows.list()
go get github.com/botcadence/go-sdk
import "github.com/botcadence/go-sdk"
client := botcadence.NewClient("YOUR_API_KEY")
workflows, err := client.Workflows.List()
Webhooks Security
Verify webhook signatures to ensure requests are from BotCadence.
Signature Verification
Each webhook request includes a signature in the X-BotCadence-Signature header:
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const hmac = crypto.createHmac('sha256', secret);
const digest = hmac.update(payload).digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(digest)
);
}
Support
Need help? Contact our support team through the dashboard or check our community forums.
