API Reference

Execute API

Programmatically run bots and tools via the Execute API.

Endpoint

POST /api/v1/execute

Authentication

Include your API key in the Authorization header.

Header

Authorization: Bearer bh_sk_xxxxxxxxxxxxxxxxxxxxx

Request Body

request.json

{
  "botId": "optional-bot-id",
  "steps": [
    {
      "agentId": "general.respond",
      "input": { "prompt": "Explain quantum computing" }
    },
    {
      "agentId": "integrations.notion.createPage",
      "input": { "title": "Quantum Computing Notes" }
    }
  ]
}

Response

response.json

{
  "runId": "run_abc123",
  "transcript": [
    { "role": "agent", "agentId": "general.respond", "content": "..." },
    { "role": "agent", "agentId": "integrations.notion.createPage", "content": "..." }
  ],
  "output": "Created page: https://notion.so/..."
}

Available Agents

Common agents you can use in the agentId field:

Agent ID	Description
`general.respond`	Generate text responses using AI
`coding.analyze`	Analyze and review code
`integrations.google.search`	Search the web
`integrations.notion.createPage`	Create Notion pages

Example: cURL

Terminal

curl -X POST https://bothive.cloud/api/v1/execute \
  -H "Authorization: Bearer bh_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"steps": [{"agentId": "general.respond", "input": {"prompt": "Hello"}}]}'