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.
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.
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.The recommended production path
Your server calls POST /api/v1/chat with the bot ID, a customer message, and your own stable session ID. Store the returned runId so your team can open the matching Bothive trace later.
const res = await fetch("https://bothive.cloud/api/v1/chat", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": process.env.BOTHIVE_API_KEY,
},
body: JSON.stringify({
botId: "your-bot-id",
message: userMessage,
sessionId: customer.id,
userId: customer.id,
}),
});
const { response, runId } = await res.json();Option A — TypeScript SDK (recommended)
For Next.js, React, or Node, the @bothive/sdk wraps the REST API with types and error handling.
npm install @bothive/sdkimport { 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);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 /api/v1/chat with your key in the x-api-key header. Include the bot ID, the message, and a stable session ID from your app.
curl -X POST https://bothive.cloud/api/v1/chat \
-H "x-api-key: bh_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "botId": "<botId>", "message": "Summarize this week in tech", "sessionId": "customer-42" }'The response:
{
"response": "Here's your summary ...",
"runId": "run_...",
"model": "..."
}import requests
res = requests.post(
"https://bothive.cloud/api/v1/chat",
headers={"x-api-key": "bh_your_api_key"},
json={"botId": "<botId>", "message": "Summarize this week in tech", "sessionId": "customer-42"},
)
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).
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{ 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.