HTTP API Reference

The Bothive API provides a RESTful interface to interact with your autonomous agents programmatically. Use it to trigger runs, manage deployments, and retrieve execution logs.

Authentication

Authenticate requests by including your API key in the Authorization header.

Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Production keys start with bh_live_

Test keys start with bh_test_

Authorization Header

Authorization: Bearer bh_live_abc123...

Base URL

All API requests should be made to the following base URL. We support HTTPS only.

API Endpoint

https://api.bothive.cloud/v1

Execute Bot

POST /bots/:id/run

Triggers a synchronous execution of a specific bot. This endpoint handles the full lifecycle: authenticating the request, spinning up the Hivelang runtime, executing the bot logic, and returning the final response.

Parameters

bot_idREQ

string

The unique identifier (slug) of the bot.

promptREQ

string

The input message for the bot to process.

context

object

Optional JSON object to pass custom variables.

user_id

string

Optional ID to track end-user sessions.

curl -X POST https://api.bothive.cloud/v1/bots/marketing-bot/run \
  -H "Authorization: Bearer bh_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Generating a Q4 marketing plan",
    "context": { "budget": 5000 }
  }'

Response Details

{
  "success": true,
  "botId": "marketing-bot",
  "response": "Here is a drafted Q4 marketing plan focusing on paid social...",
  "model": "hivelang-runtime",
  "executionTime": "1240ms"
}

Health Check

GET /health

Check the operational status of the API. Useful for automated monitoring or liveliness probes.

Request

curl https://api.bothive.cloud/health

HTTP API Reference

Authentication

Base URL

Execute Bot

Parameters

Health Check

Confused? Ask HiveMind.