GuideBaaS

Connect a bot to your app

You built a bot on Bothive. Now call it from your own product — a web app, a mobile backend, a script — using your API key. Bothive is the hosted backend; your app is the frontend.

The mental model

Bots are built on Bothive and consumed anywhere. Your app sends a prompt with an API key; Bothive runs the bot — its HiveLang, tools, memory, and model — and returns the reply. You never ship model keys or prompt logic to your client.

your app → POST with API key → Bothive runs your bot → returns reply → your app shows it

Step 1 — Get the pieces

A bot ID — from the bot's page in your dashboard.
An API key — create one under Dashboard → Developer → API Keys. It starts with bh_ and is shown once. See Authentication.

Keep keys server-side

A bh_ key can run your bots and is billed to you. Use it from your backend. For browsers, prefer a public bot via the CORS chat endpoint (below) or proxy through your own server.

Option A — TypeScript SDK (recommended)

For Next.js, React, or Node, the @bothive/sdk wraps the REST API with types and error handling.

Install

npm install @bothive/sdk

Run a bot

import { BothiveClient } from "@bothive/sdk";

const client = new BothiveClient({ apiKey: process.env.BOTHIVE_API_KEY });

const res = await client.runBot({
  botId: "your-bot-id",
  prompt: "Help me plan my week",
});

console.log(res.response);

Multi-turn chat

The SDK also exposes a stateful ChatSession for back-and-forth conversations that remember history. Reach for it when you're building a chat UI rather than one-shot calls.

Option B — REST: run a bot

From any language, POST to the bot's run endpoint with your key in the Authorization header. The body takes a prompt and optional context.

POST /api/bots/:botId/run

curl -X POST https://bothive.cloud/api/bots/<botId>/run \
  -H "Authorization: Bearer bh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Summarize this week in tech" }'

The response:

Response

{
  "success": true,
  "response": "Here's your summary ...",
  "botId": "<botId>",
  "model": "claude-..."
}

Python

import requests

res = requests.post(
    "https://bothive.cloud/api/bots/<botId>/run",
    headers={"Authorization": "Bearer bh_your_api_key"},
    json={"prompt": "Summarize this week in tech"},
)
res.raise_for_status()
print(res.json()["response"])

Option C — Chat from the browser (CORS)

For conversational UIs and embedded callers, use the CORS-enabled chat endpoint. It takes a message, an optional botId, and prior history for multi-turn context. Authenticate with x-api-key (or the Authorization header).

POST /api/v1/chat

const res = await fetch("https://bothive.cloud/api/v1/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "bh_your_api_key",
  },
  body: JSON.stringify({
    botId: "your-bot-id",
    message: "What can you help me with?",
    history: [
      { role: "user", content: "hi" },
      { role: "assistant", content: "Hey! How can I help?" },
    ],
  }),
});

const data = await res.json();
console.log(data.response); // also: data.bot, data.model, data.runId

Track the conversation

Keep your own array of { role, content } turns and pass the recent ones as history on each call. The endpoint is stateless, so history is how the bot remembers the thread.

Errors to handle

401 — missing or invalid API key.
403 — the key's owner isn't allowed to run this bot (not public / not installed).
404 — no bot matched that ID, slug, or name.
429 — rate limit or monthly quota hit. Back off and retry, or upgrade the plan.

Next steps

Authentication

Create, rotate, and secure your bh_ keys.

Execute API

Request and response details for hosted bot calls.

SDK reference

Full @bothive/sdk surface — runBot, chat, ChatSession.

Connect your API

Give the bot live access to your own backend.