Execute API

Authentication

Include your secret API key in the Authorization header. Do not call this endpoint directly from a browser with a secret key.

Authorization: Bearer bh_live_xxxxxxxxxxxxxxxxxxxxx

Request body

Pass the bot to run, the user message or structured input, and an optional sessionId so memory, usage limits, and traces can be grouped around the same end user.

{
  "botId": "bot_123",
  "input": {
    "message": "Help me summarize today's customer issues"
  },
  "sessionId": "customer_42",
  "metadata": {
    "source": "app-dashboard"
  }
}

Response

Successful responses include the model output and a run ID. Store the run ID when you need support, observability, retries, or audit history.

{
  "success": true,
  "runId": "run_abc123",
  "sessionId": "customer_42",
  "output": "Here are the top customer issues from today...",
  "traceUrl": "https://bothive.cloud/dashboard/runs/run_abc123"
}

Example request

curl -X POST https://bothive.cloud/api/v1/execute \
  -H "Authorization: Bearer bh_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "botId": "bot_123",
    "input": { "message": "Hello" },
    "sessionId": "customer_42"
  }'

Error shape

API failures should be handled with stable error codes, not only status text. When a run fails inside the runtime, open the trace to see what context loaded, what tool was attempted, and how to recover.