Connect Your Own API

Want a bot that answers from your data — orders, accounts, your matching algorithm? Connect your API. Bothive never touches your database; your bot calls your endpoints, and your backend runs the query and enforces your auth.

The model

text
user asks the bot → bot calls your endpoint (e.g. POST /match)
  → your backend queries your DB → returns result → bot explains it

The security boundary stays where it belongs: your data and rules stay yours.

1. Open Connect API

In the dashboard, go to Integrations → Connect API (/dashboard/integrations/connect-api). You'll describe your API once; Bothive turns it into tools your bots can call.

2. Describe your endpoints

Fill in the guided form:

• Base URL — e.g. https://api.yourcompany.com.
• Auth — how to authenticate (e.g. a bearer token). Your token is encrypted at rest and sent only to your endpoints.
• Endpoints — each becomes a capability, e.g. POST /match → integration.yourapi.match.

Have an OpenAPI / Swagger spec? Upload it to auto-fill the endpoints.

Design bot-friendly capabilities

Name each action for what the bot should accomplish, not for the raw route name. A bot understands createTicket better than postTickets.

Endpoint	Capability name	Bot should use it when
		It needs account context before answering
		A human follow-up is needed
		A workflow closes or escalates a ticket
		The user asks for pricing based on inputs

3. Use it in a bot

Once saved, your integration shows up as tools named integration.<slug>.<capability>. Declare them in a bot's capabilities and call them like any tool:

hivelang
bot Matchmaker {
  instructions { Help users find their best match using our API. }

  capabilities {
    integration.yourapi.match
  }

  on user.message {
    call integration.yourapi.match with { query: input } as result
    respond with "Here's your best match: " + result
  }
}

They also appear automatically as App nodes in the Orchestrator, so workflows can call your API too.

Test with safe inputs

Before giving the integration to production users:

1. Run each capability from the integration tester.
2. Confirm failed auth returns a clear error, not a generic 500.
3. Try missing or invalid inputs.
4. For write actions, test in a sandbox account first.
5. Open Live Logs and confirm the trace redacts tokens and sensitive fields.

Example endpoint contract

Your endpoint should return simple JSON. Keep the response shape stable so bots and workflows can rely on it.

http
POST /tickets
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

json
{
  "subject": "Refund request",
  "customerEmail": "ada@example.com",
  "priority": "normal"
}

json
{
  "ticketId": "tic_123",
  "status": "created",
  "url": "https://app.example.com/tickets/tic_123"
}

Why it's secure

• Bothive never connects to your database — only to the endpoints you list.
• Your token is encrypted and per-user.
• Outbound calls are SSRF-guarded (no internal/metadata IPs).
• Your backend still owns authorization. If a user should not see a record, your API should reject the request.

Common errors

Error	Usually means	Fix
	The saved token is missing or expired	Reconnect the integration
	Your API rejected the user's permission	Check the account/workspace mapping
	The route or record was not found	Confirm base URL and path params
	Required input is missing	Add clearer parameter descriptions
Timeout	Endpoint took too long	Return less data or add pagination

Next steps

• Connect a bot to your app — now expose the bot to your users.
• Build & schedule workflows — chain your API calls into automations.