> ## Documentation Index
> Fetch the complete documentation index at: https://botcadence-a5dbc408.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Navigate to Settings">
    Go to your [Dashboard](https://app.botcadence.com/dashboard) and click on Settings
  </Step>

  <Step title="API Keys Section">
    Find the "API Keys" section
  </Step>

  <Step title="Generate Key">
    Click "Generate New Key" and save it securely
  </Step>
</Steps>

<Warning>
  Keep your API key secure! Never commit it to version control or share it publicly.
</Warning>

### Using Your API Key

Include your API key in the `Authorization` header:

```bash theme={null}
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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.botcadence.com/v1/workflows \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.botcadence.com/v1/workflows', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
  const workflows = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.botcadence.com/v1/workflows',
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )
  workflows = response.json()
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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!"
          }
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.botcadence.com/v1/workflows', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'New Workflow',
      trigger: {
        type: 'webhook',
        event: 'user.created'
      },
      actions: [{
        type: 'send_email',
        config: {
          to: '{{user.email}}',
          subject: 'Welcome!',
          body: 'Thanks for joining!'
        }
      }]
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.botcadence.com/v1/workflows',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'New Workflow',
          'trigger': {
              'type': 'webhook',
              'event': 'user.created'
          },
          'actions': [{
              'type': 'send_email',
              'config': {
                  'to': '{{user.email}}',
                  'subject': 'Welcome!',
                  'body': 'Thanks for joining!'
              }
          }]
      }
  )
  ```
</CodeGroup>

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

```bash theme={null}
GET /v1/workflows/{workflow_id}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.botcadence.com/v1/workflows/wf_123456 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.botcadence.com/v1/workflows/wf_123456', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
  const workflow = await response.json();
  ```
</CodeGroup>

### Update Workflow

Update an existing workflow.

```bash theme={null}
PATCH /v1/workflows/{workflow_id}
```

### Delete Workflow

Delete a workflow permanently.

```bash theme={null}
DELETE /v1/workflows/{workflow_id}
```

<Warning>
  This action cannot be undone. Make sure you want to permanently delete this workflow.
</Warning>

## Executions

Track and manage workflow executions.

### List Executions

Get execution history for a workflow.

```bash theme={null}
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:**

```json theme={null}
{
  "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.

```bash theme={null}
GET /v1/executions/{execution_id}
```

## Webhooks

Manage webhook endpoints for triggering workflows.

### Create Webhook

Generate a new webhook URL.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.botcadence.com/v1/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workflow_id: 'wf_123456',
      event: 'user.created'
    })
  });
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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

<Info>
  API requests are rate limited to ensure fair usage and system stability.
</Info>

| 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

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "The 'name' field is required",
    "details": {
      "field": "name",
      "issue": "required"
    }
  }
}
```

## SDKs and Libraries

<Tabs>
  <Tab title="JavaScript/TypeScript">
    ```bash theme={null}
    npm install @botcadence/sdk
    ```

    ```javascript theme={null}
    import { Botcadence } from '@botcadence/sdk';

    const client = new Botcadence('YOUR_API_KEY');
    const workflows = await client.workflows.list();
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install botcadence
    ```

    ```python theme={null}
    from botcadence import Client

    client = Client('YOUR_API_KEY')
    workflows = client.workflows.list()
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/botcadence/go-sdk
    ```

    ```go theme={null}
    import "github.com/botcadence/go-sdk"

    client := botcadence.NewClient("YOUR_API_KEY")
    workflows, err := client.Workflows.List()
    ```
  </Tab>
</Tabs>

## 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:

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/docs/quickstart">
    Get started with the basics
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/blogs/best-practices">
    Learn from our experts
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/botcadence">
    View our open source projects
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://app.botcadence.com/dashboard">
    Access your account
  </Card>
</CardGroup>

<Note>
  Need help? Contact our support team through the dashboard or check our community forums.
</Note>