API Reference

Complete API documentation for developers

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

1. Navigate to Settings

   Go to your Dashboard and click on Settings

2. API Keys Section

   Find the “API Keys” section

3. 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

curl -X GET https://api.botcadence.com/v1/workflows \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "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

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!"
        }
      }
    ]
  }'

Parameters:

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

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

Query Parameters:

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)

Response:

{
  "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

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"
  }'

Response:

{
  "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

Rate Limit Headers:

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 Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The 'name' field is required",
    "details": {
      "field": "name",
      "issue": "required"
    }
  }
}

SDKs and Libraries

JavaScript/TypeScript

npm install @botcadence/sdk

import { BotCadence } from '@botcadence/sdk';

const client = new BotCadence('YOUR_API_KEY');
const workflows = await client.workflows.list();

Python

pip install botcadence

from botcadence import Client

client = Client('YOUR_API_KEY')
workflows = client.workflows.list()

Go

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

Quick Start

Get started with the basics

Best Practices

Learn from our experts

GitHub

View our open source projects

Dashboard

Access your account

Need help? Contact our support team through the dashboard or check our community forums.