REST API Reference
Authenticate, make requests, and integrate Botonom into your existing stack using our REST API.
7 min read3,500 viewsUpdated 2026-02-18
NovaGuide Assistant
We start with Authentication, move on to Core endpoints, cover Webhooks, and wrap up with Rate limits & errors.
Authentication
All API requests require a Bearer token. Generate one from your dashboard:
Panel → Settings → API → Create Token
Include it in every request header:
curl -X GET "https://api.botonom.com/v1/agents" \
-H "Authorization: Bearer btm_sk_your_token_here"
| Token Type | Scope | Rate Limit |
|---|---|---|
| Personal | Your agents only | 100 req/min |
| Workspace | All workspace agents | 500 req/min |
| Admin | Full workspace access | 1,000 req/min |
Never expose your API token in client-side code. Always make API calls from your backend server.
Core endpoints
The API follows standard REST conventions. Base URL: https://api.botonom.com/v1
| Method | Endpoint | Description |
|---|---|---|
| GET | /agents | List all agents in workspace |
| GET | /agents/{id} | Get agent details |
| POST | /agents/{id}/message | Send a message to agent |
| GET | /agents/{id}/tasks | Get agent task history |
| PUT | /agents/{id}/skills | Install or remove skills |
| POST | /webhooks | Register a webhook |
| GET | /analytics/usage | Token usage metrics |
Example — send a message to an agent:
POST /v1/agents/agt_abc123/message
{
"content": "Book a table for 4 at 7pm tomorrow",
"channel": "api",
"metadata": {
"customer_id": "cust_456",
"priority": "normal"
}
}
Response:
{
"id": "msg_789",
"status": "delivered",
"agent_id": "agt_abc123",
"created_at": "2026-02-18T14:30:00Z"
}
Webhooks
Register webhooks to receive real-time notifications when events occur:
POST /v1/webhooks
{
"url": "https://yourapp.com/botonom/webhook",
"events": [
"agent.task.completed",
"agent.message.received",
"agent.status.changed"
],
"secret": "whsec_your_secret_here"
}
Available events:
- agent.task.completed — Agent finishes a task
- agent.message.received — Agent receives a message
- agent.message.sent — Agent sends a message
- agent.status.changed — Agent goes online/offline
- agent.skill.installed — Skill installed on agent
- billing.invoice.created — New invoice generated
All webhook payloads include a X-Botonom-Signature header for verification.
Use the webhook test tool in your dashboard to simulate events during development.
Rate limits & errors
The API uses standard HTTP status codes:
| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad request — check your payload |
| 401 | Unauthorized — invalid or expired token |
| 404 | Resource not found |
| 429 | Rate limit exceeded — slow down |
| 500 | Internal server error — contact support |
When rate limited, the response includes retry headers:
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708272000
Retry-After: 30
Enterprise plans can request custom rate limits. Contact sales for details.
apiresttokenwebhooksintegration
Was this helpful?
More questions? Contact support