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

# API Reference

> The Bothive REST API — execute, chat, deploy, and manage AI agents programmatically.

## Base URL

```
https://api.bothive.cloud/v1
```

## Authentication

All API requests require a Bothive API key:

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

Get your API key from: [bothive.cloud/dashboard/settings/api](https://bothive.cloud/dashboard/settings/api)

<Warning>
  Never expose your API key in client-side code, public repos, or browser environments. Always call the Bothive API from your server or backend.
</Warning>

## Core endpoints

<CardGroup cols={2}>
  <Card title="POST /v1/bots/:id/chat" icon="comments" href="./chat" className="glass-effect">
    Send a message to an agent. Supports streaming via SSE. Maintains session context via `X-Session-ID` header.
  </Card>

  <Card title="POST /v1/bots/:id/execute" icon="play" href="./execute" className="glass-effect">
    Execute an agent with a prompt — stateless, no session context. Useful for one-shot tasks and background jobs.
  </Card>

  <Card title="POST /v1/bots/:id/deploy" icon="rocket" href="./deploy" className="glass-effect">
    Deploy a HiveLang file to a bot programmatically. CI/CD-ready.
  </Card>

  <Card title="GET /v1/bots/:id/runs" icon="list" href="./chat" className="glass-effect">
    List all runs for a bot. Filter by user, status, date, or channel. Returns traces.
  </Card>
</CardGroup>

## Rate limits

| Plan       | Requests/min | Requests/day |
| ---------- | ------------ | ------------ |
| Free       | 10           | 1,000        |
| Pro        | 60           | 20,000       |
| Business   | 300          | 200,000      |
| Enterprise | Custom       | Custom       |

Rate limit headers are returned on every response:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1706745600
```

## Error codes

| Code  | Meaning           | Common cause                             |
| ----- | ----------------- | ---------------------------------------- |
| `400` | Bad Request       | Missing required field or malformed JSON |
| `401` | Unauthorized      | Missing or invalid API key               |
| `403` | Forbidden         | API key doesn't have access to this bot  |
| `404` | Not Found         | Bot ID doesn't exist                     |
| `429` | Too Many Requests | Rate limit exceeded                      |
| `500` | Server Error      | Bothive internal error — contact support |

All error responses follow this format:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded 60 requests per minute. Please slow down.",
    "retry_after": 12
  }
}
```

## SDK availability

Official SDKs:

| Language                | Package          | Status      |
| ----------------------- | ---------------- | ----------- |
| TypeScript / JavaScript | `@bothive/sdk`   | Available   |
| Python                  | `bothive-python` | Coming soon |
| Go                      | `bothive-go`     | Coming soon |

```bash theme={null}
npm install @bothive/sdk
```

```typescript theme={null}
import { BothiveClient } from '@bothive/sdk';

const client = new BothiveClient({
  apiKey: process.env.BOTHIVE_API_KEY,
});

const response = await client.bots.chat('bot_abc123', {
  message: 'What is my subscription status?',
  sessionId: 'user_xyz',
});
```

## API Playground

Try the API directly in your browser at [bothive.cloud/api-playground](https://bothive.cloud/api-playground).

The playground lets you:

* Make live API calls with your real API key
* Test different bot IDs and session IDs
* Inspect request and response payloads
* Copy curl commands

## Next reads

<CardGroup cols={3}>
  <Card title="Chat API" icon="comments" href="./chat" className="glass-effect" />

  <Card title="Execute API" icon="play" href="./execute" className="glass-effect" />

  <Card title="Deploy API" icon="rocket" href="./deploy" className="glass-effect" />
</CardGroup>