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

# Deploy API

> Deploy HiveLang agent definitions programmatically — CI/CD-ready.

## POST /v1/bots/:id/deploy

The Deploy API uploads a HiveLang file to a bot and redeploys it. All connected channels immediately use the new agent definition.

Use this to:

* Build CI/CD pipelines for your agents
* Deploy agents from your build system
* Automate version management

## Request

```bash theme={null}
curl -X POST https://api.bothive.cloud/v1/bots/{bot_id}/deploy \
  -H "Authorization: Bearer bh_sk_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "hivelang": "bot SupportBot {\n  description: \"Customer support\"\n  capabilities {\n    knowledgebase.search\n  }\n  instructions {\n    You are a helpful support agent.\n  }\n}",
    "environment": "production",
    "message": "Add knowledge base search capability"
  }'
```

### Headers

| Header          | Required | Description        |
| --------------- | -------- | ------------------ |
| `Authorization` |          | `Bearer bh_sk_...` |
| `Content-Type`  |          | `application/json` |

### Request body

| Field         | Type     | Required | Description                                      |
| ------------- | -------- | -------- | ------------------------------------------------ |
| `hivelang`    | `string` |          | The full HiveLang v5 source code                 |
| `environment` | `string` | Optional | `production` or `staging`. Default: `production` |
| `message`     | `string` | Optional | Deploy message / changelog note                  |
| `env_vars`    | `object` | Optional | Environment variables to set for this deployment |

## Response

```json theme={null}
{
  "deployment_id": "dep_abc123",
  "bot_id": "bot_xyz789",
  "status": "deployed",
  "deployed_at": "2025-01-20T09:00:00Z",
  "channels": ["web", "telegram"],
  "parse_errors": [],
  "warnings": []
}
```

### Response fields

| Field           | Type       | Description                              |
| --------------- | ---------- | ---------------------------------------- |
| `deployment_id` | `string`   | Unique ID for this deployment            |
| `bot_id`        | `string`   | The bot that was deployed                |
| `status`        | `string`   | `deployed`, `failed`, or `pending`       |
| `deployed_at`   | `string`   | ISO 8601 timestamp                       |
| `channels`      | `string[]` | Channels now running the new definition  |
| `parse_errors`  | `string[]` | HiveLang parse errors (empty on success) |
| `warnings`      | `string[]` | Non-blocking warnings                    |

## TypeScript / CI example

```typescript theme={null}
import { readFileSync } from 'fs';

const hivelang = readFileSync('./bots/support-agent.hive', 'utf-8');

const response = await fetch(
  `https://api.bothive.cloud/v1/bots/${BOT_ID}/deploy`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BOTHIVE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      hivelang,
      environment: 'production',
      message: `Deploy from CI — commit ${process.env.GIT_SHA}`,
    }),
  }
);

const deployment = await response.json();

if (deployment.status === 'failed') {
  console.error('Deploy failed:', deployment.parse_errors);
  process.exit(1);
}

console.log(` Deployed ${deployment.deployment_id} to ${deployment.channels.join(', ')}`);
```

## GitHub Actions CI/CD example

```yaml theme={null}
# .github/workflows/deploy-agent.yml
name: Deploy Bothive Agent

on:
  push:
    branches: [main]
    paths:
      - 'bots/**/*.hive'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Deploy to Bothive
        env:
          BOTHIVE_API_KEY: ${{ secrets.BOTHIVE_API_KEY }}
          BOT_ID: ${{ secrets.BOTHIVE_BOT_ID }}
        run: |
          HIVELANG=$(cat bots/support-agent.hive)
          curl -X POST "https://api.bothive.cloud/v1/bots/$BOT_ID/deploy" \
            -H "Authorization: Bearer $BOTHIVE_API_KEY" \
            -H "Content-Type: application/json" \
            -d "{
              \"hivelang\": $(echo "$HIVELANG" | jq -Rs .),
              \"message\": \"Deploy from GitHub Actions - $GITHUB_SHA\"
            }"
```

## Rollback

To roll back to a previous deployment, deploy the old HiveLang source:

```bash theme={null}
# List recent deployments
curl https://api.bothive.cloud/v1/bots/{bot_id}/deployments \
  -H "Authorization: Bearer bh_sk_xxxxxxxxx"

# Roll back by redeploying a previous version's HiveLang
curl -X POST https://api.bothive.cloud/v1/bots/{bot_id}/deployments/{deployment_id}/rollback \
  -H "Authorization: Bearer bh_sk_xxxxxxxxx"
```

## Environment variables

Pass secrets and config your HiveLang bot needs at runtime:

```json theme={null}
{
  "hivelang": "bot MyBot { ... }",
  "env_vars": {
    "CUSTOM_API_URL": "https://api.yourcompany.com",
    "CUSTOM_API_KEY": "sk-xxxxxxxxxxxxx"
  }
}
```

Reference them in HiveLang with `env.VARIABLE_NAME`.

<Warning>
  Never hardcode API keys or secrets directly in your HiveLang source. Always use environment variables so secrets don't appear in deployment logs or version history.
</Warning>

## 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="HiveLang v5" icon="code" href="../concepts/hivelang" className="glass-effect" />
</CardGroup>