Connect a Bot to Your App

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

1. Get the pieces

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

Keep keys server-side. A bh_ key can run your bots and is billed to you.

2. Option A — TypeScript SDK (recommended)

For Next.js, React, or Node:

bash
npm install @bothive/sdk

javascript
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);

3. Option B — REST

From any language, POST to the bot's run endpoint:

bash
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:

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

4. Option C — Chat from the browser (CORS)

For conversational UIs, use the CORS-enabled chat endpoint with message, botId, and prior history:

javascript
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: [],
  }),
});
const data = await res.json();
console.log(data.response);

Keep your own array of { role, content } turns and pass the recent ones as history — the endpoint is stateless.

Errors to handle

• 401 — missing/invalid key. 403 — key can't run this bot. 404 — no bot matched. 429 — rate limit or quota; back off or upgrade.