API reference

Bothive API

Use the API when a bot needs to live inside your product, backend, marketplace, or customer workflow. The API gives you execution, sessions, traces, and production boundaries around the agent runtime.

server-sidesessionstraces

Base URL

https://bothive.cloud/api/v1

Auth

Bearer API key

Primary endpoint

POST /execute

Start here

guide

Authentication

Create server-side keys, rotate them safely, and keep secret keys out of client code.

guide

Execute

Run a deployed bot from your backend and receive a response plus trace metadata.

guide

SDK

Use helper libraries when you want less request plumbing in your application code.

guide

Connect a bot

Put the API into a real app flow: auth, sessions, rate limits, and user-facing errors.

Minimal Node example

This is the simplest shape: call Bothive from your backend, pass a bot ID and message, then return the output to your user interface.

execute.ts

const response = await fetch("https://bothive.cloud/api/v1/execute", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOTHIVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    botId: "bot_123",
    input: { message: "Create a summary for this customer" },
    sessionId: "customer_42",
  }),
});

const run = await response.json();

Production checklist

Call from your backend: Secret keys should never be embedded in frontend JavaScript or mobile apps.
Pass a stable session ID: Use session IDs for continuity, memory boundaries, rate limits, and trace lookup.
Handle structured errors: Use error codes for retries, permission messages, and support workflows.
Store the run ID: Run IDs make debugging, observability, and customer support much easier.

If you are building a public integration

Start with API authentication, then implement bot execution with stable session IDs and clear user-facing error states.