Execute API

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
`model`	`string`	Optional	Override the bot’s default model for this run
`max_tokens`	`number`	Optional	Cap the response length

Response

{
  "result": "Top 3 billing issues this week:\n1. Failed card charges (47 tickets)\n2. Plan upgrade confusion (23 tickets)\n3. Invoice discrepancies (18 tickets)",
  "run_id": "run_abc456",
  "latency_ms": 1204,
  "tokens_used": 892,
  "tools_called": ["billing.getTickets", "ai.summarize"],
  "status": "success"
}

Response fields

Field	Type	Description
`result`	`string`	The agent’s output for this execution
`run_id`	`string`	Unique run ID — use to fetch the full trace
`latency_ms`	`number`	Total execution time in milliseconds
`tokens_used`	`number`	Total tokens consumed
`tools_called`	`string[]`	Capability names invoked during this run
`status`	`string`	`success`, `error`, or `timeout`

TypeScript example

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

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

// One-shot execution
const 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 Cron
import 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:

curl https://api.bothive.cloud/v1/runs/{run_id} \
  -H "Authorization: Bearer bh_sk_xxxxxxxxx"

Start Here

Getting Started

Core Concepts

Building Agents

Deployment & Operations

Teams & Organisations

Integrations

API Reference

Resources

POST /v1/bots/:id/execute

Request

Headers

Request body

Response

Response fields

TypeScript example

Scheduled execution example

Execute vs Chat — when to use each

Fetching the trace

Next reads

Chat API

Deploy API

Observability

​POST /v1/bots/:id/execute

​Request

​Headers

​Request body

​Response

​Response fields

​TypeScript example

​Scheduled execution example

​Execute vs Chat — when to use each

​Fetching the trace

​Next reads

Chat API

Deploy API

Observability

POST /v1/bots/:id/execute

Request

Headers

Request body

Response

Response fields

TypeScript example

Scheduled execution example

Execute vs Chat — when to use each

Fetching the trace

Next reads