> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatbotplatform.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Programmatic access to Chatbot Platform

The Chatbot Platform API provides programmatic access to all platform features, allowing you to integrate bot management, agent loops, and conversations into your applications.

## Base URL

All API requests are made to:

```
https://api.chatbotplatform.io/v1
```

## Authentication

API requests require authentication using an API key. Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Getting an API Key

<Steps>
  <Step title="Navigate to Settings">
    In the dashboard, go to your team settings.
  </Step>

  <Step title="API Keys Section">
    Click on **API Keys** in the sidebar.
  </Step>

  <Step title="Create Key">
    Click **Create API Key** and give it a name.
  </Step>

  <Step title="Copy Key">
    Copy the generated key - it won't be shown again.
  </Step>

  <Step title="Store Securely">
    Store the key in your environment variables or secrets manager.
  </Step>
</Steps>

<Callout type="warning">
  Keep your API key secret. Anyone with the key has full access to your team's resources.
</Callout>

## Making Requests

### Example: List Bots

```bash theme={null}
curl https://api.chatbotplatform.io/v1/bots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

Response:

```json theme={null}
{
  "data": [
    {
      "id": "bot_abc123",
      "name": "Support Bot",
      "description": "Customer support chatbot",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1
  }
}
```

### Example: Create Bot

```bash theme={null}
curl -X POST https://api.chatbotplatform.io/v1/bots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Bot",
    "description": "Handles sales inquiries"
  }'
```

Response:

```json theme={null}
{
  "data": {
    "id": "bot_xyz789",
    "name": "Sales Bot",
    "description": "Handles sales inquiries",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

## Available Resources

### Bots

Manage chatbot instances:

* `GET /bots` - List all bots
* `POST /bots` - Create a bot
* `GET /bots/{id}` - Get bot details
* `PATCH /bots/{id}` - Update bot
* `DELETE /bots/{id}` - Delete bot

### Integrations

Configure AI backend connections:

* `GET /bots/{bot_id}/integrations` - List integrations
* `POST /bots/{bot_id}/integrations` - Create integration
* `GET /integrations/{id}` - Get integration details
* `PATCH /integrations/{id}` - Update integration
* `DELETE /integrations/{id}` - Delete integration

### Channels

Connect to messaging platforms:

* `GET /bots/{bot_id}/channels` - List channels
* `POST /bots/{bot_id}/channels` - Create channel
* `GET /channels/{id}` - Get channel details
* `PATCH /channels/{id}` - Update channel
* `DELETE /channels/{id}` - Delete channel

### Conversations

Access conversation history:

* `GET /bots/{bot_id}/conversations` - List conversations
* `GET /conversations/{id}` - Get conversation details
* `GET /conversations/{id}/messages` - Get messages
* `DELETE /conversations/{id}` - Delete conversation

### Agent Loops

Manage autonomous workflows:

* `GET /agent-loops` - List agent loops
* `POST /agent-loops` - Create agent loop
* `GET /agent-loops/{id}` - Get details
* `POST /agent-loops/{id}/run` - Execute agent loop
* `GET /agent-loops/{id}/executions` - List executions
* `PATCH /agent-loops/{id}` - Update agent loop
* `DELETE /agent-loops/{id}` - Delete agent loop

## Pagination

List endpoints support pagination using query parameters:

```bash theme={null}
GET /bots?page=2&per_page=50
```

Parameters:

* `page` - Page number (default: 1)
* `per_page` - Items per page (default: 20, max: 100)

Response includes pagination metadata:

```json theme={null}
{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 50,
    "total": 125,
    "total_pages": 3
  }
}
```

## Filtering

Some endpoints support filtering:

```bash theme={null}
GET /conversations?user_id=user_123&status=active
```

Check endpoint-specific documentation for available filters.

## Error Handling

API errors return appropriate HTTP status codes and JSON error objects:

```json theme={null}
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Bot with ID bot_123 not found",
    "details": {
      "resource_type": "bot",
      "resource_id": "bot_123"
    }
  }
}
```

### Status Codes

| Code | Meaning               |
| ---- | --------------------- |
| 200  | Success               |
| 201  | Created               |
| 400  | Bad Request           |
| 401  | Unauthorized          |
| 403  | Forbidden             |
| 404  | Not Found             |
| 422  | Validation Error      |
| 429  | Rate Limit Exceeded   |
| 500  | Internal Server Error |

## Rate Limits

API requests are rate limited per API key:

| Plan       | Rate Limit           |
| ---------- | -------------------- |
| Free       | 60 requests/minute   |
| Pro        | 300 requests/minute  |
| Enterprise | 1000 requests/minute |

Rate limit headers are included in responses:

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 285
X-RateLimit-Reset: 1705320000
```

When rate limited, you'll receive a 429 response:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "retry_after": 45
  }
}
```

## Webhooks

The API also sends webhooks for certain events:

* Bot message received
* Integration failed
* Agent loop completed
* Channel disconnected

See [Authentication](/api-reference/authentication) for webhook signature verification.

## SDKs and Libraries

Official SDKs (coming soon):

* JavaScript/TypeScript
* Python
* Go
* Ruby

## Support

* **Documentation**: Full API reference at [docs.chatbotplatform.io/api-reference](https://docs.chatbotplatform.io/api-reference)
* **Issues**: Report bugs on [GitHub](https://github.com/Jonnx/app.chatbotplatform.io/issues)
* **Email**: [support@chatbotplatform.io](mailto:support@chatbotplatform.io)

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn about API authentication
  </Card>

  <Card title="Bot Management" icon="robot">
    API endpoints for bots (coming soon)
  </Card>

  <Card title="Agent Loops API" icon="rotate">
    Trigger agents programmatically (coming soon)
  </Card>
</CardGroup>