Stateless agent execution — run one-shot tasks, background jobs, and scheduled automation.
POST /v1/bots/:id/execute
The Execute API runs a bot with a single prompt and returns a response. Unlike the Chat API, Execute is stateless — no session ID, no conversation history loaded. Each call is independent.Use Execute for:
Scheduled automation (daily reports, cron jobs)
Background processing (classify this email, summarize this document)
One-shot tasks that don’t need memory
Request
curl -X POST https://api.bothive.cloud/v1/bots/{bot_id}/execute \ -H "Authorization: Bearer bh_sk_xxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Summarize these support tickets and identify the top 3 issues: [...]", "context": { "time_range": "last_7_days", "team": "billing" } }'
Headers
Header
Required
Description
Authorization
Bearer bh_sk_...
Content-Type
application/json
Request body
Field
Type
Required
Description
prompt
string
The task prompt or instruction
context
object
Optional
Additional key-value context injected into the prompt
import { BothiveClient } from '@bothive/sdk';const client = new BothiveClient({ apiKey: process.env.BOTHIVE_API_KEY });// One-shot executionconst result = await client.bots.execute('bot_abc123', { prompt: 'Classify this support email as: billing / technical / general', context: { email: emailBody, sender: fromAddress, },});console.log(result.result); // "billing"console.log(result.run_id); // For trace lookup
Scheduled execution example
Run a bot on a schedule from your backend:
// Using node-cron or Vercel Cronimport cron from 'node-cron';cron.schedule('0 9 * * *', async () => { const report = await fetch( `https://api.bothive.cloud/v1/bots/${REPORT_BOT_ID}/execute`, { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.BOTHIVE_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ prompt: 'Generate today\'s business metrics report', context: { date: new Date().toISOString() }, }), } ); const { result, run_id } = await report.json(); // Post to Slack await postToSlack('#metrics', result); console.log(`Report generated. Trace: ${run_id}`);});
If your bot has a schedule block in HiveLang, Bothive handles the cron automatically — you don’t need to set up your own cron job. Use the Execute API only when you need to trigger a run from your own backend on-demand.
Execute vs Chat — when to use each
Use case
Chat API
Execute API
Product copilot / embedded assistant
Session-aware customer support
One-shot classification task
Daily scheduled report
Background email processing
Webhook-triggered automation
Long-running conversation
Fetching the trace
After any Execute call, use the run_id to fetch the full trace: