Developer Documentation

HoverBot API Reference

Authentication, endpoints, webhooks, and operational limits for production integrations.

Authentication

Use API keys for server-to-server requests with workspace-scoped permissions.
Use OAuth 2.0 for multi-tenant marketplace integrations.
All API requests require TLS and `Authorization: Bearer <token>`.

Core endpoints

Endpoint	Method	Purpose
/v1/conversations	POST	Create a conversation session with channel and user metadata.
/v1/conversations/{id}/messages	POST	Send a user message and return assistant response + trace metadata.
/v1/conversations/{id}	GET	Fetch transcript, outcomes, and escalation state.
/v1/knowledge-sources	POST	Create or update indexed knowledge sources used by retrieval.
/v1/escalations	POST	Push manual handoff events into CRM/helpdesk workflows.

Webhook events

Event	When fired	Key fields
conversation.created	Session initialized	conversationId, tenantId, channel, startedAt
message.responded	Assistant response emitted	latencyMs, modelTier, confidence, policyFlags
lead.qualified	Qualification threshold reached	leadScore, intent, contactFields, transcriptUrl
escalation.created	Human handoff created	reasonCode, destination, owner, priority

Rate limits and SLA

Default API limit: 600 requests per minute per workspace key.
Burst handling: up to 2x sustained limit for short windows with retry guidance.
Webhook retries: exponential backoff for up to 24 hours with idempotency keys.
Availability objective: 99.9% monthly target on production plans.

Code examples

cURL

curl -X POST "https://api.hoverbot.ai/v1/conversations/{id}/messages" \
  -H "Authorization: Bearer $HOVERBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Can I change my shipping address?",
    "channel": "web",
    "locale": "en-US"
  }'

Node.js

const response = await fetch("https://api.hoverbot.ai/v1/conversations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HOVERBOT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    externalUserId: "user-123",
    channel: "web",
    metadata: { source: "landing-page-demo" },
  }),
});

const payload = await response.json();

Python

import requests

resp = requests.post(
    "https://api.hoverbot.ai/v1/knowledge-sources",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "name": "Help Center",
        "type": "url-crawl",
        "seedUrls": ["https://docs.example.com/help"]
    },
    timeout=20,
)

print(resp.status_code, resp.json())

Related technical docs

Technical Overview HubSpot Integration Guide