REST API Reference

Authenticate, make requests, and integrate Botonom into your existing stack using our REST API.

7 min okuma3,500 görüntülenmeGüncelleme 2026-07-10

JuliaRehber Asistanı

This guide begins with Authentication, continues through Conventions, Core endpoints, Webhooks, and finishes with Rate limits & errors.

Authentication

All API requests require a company API key (bk_live_...). Create one from your dashboard:

Dashboard → Developers → Credentials → Create Key

The full key is shown once at creation. Send it with every request:

curl "https://api.botonom.com/en/api/v1/agents/list/" \
  -H "X-Botonom-Api-Key: bk_live_your_key_here"

Authorization: Bearer bk_live_... is also accepted. The key is scoped to your workspace; keys can be listed and revoked from the same page or via keys/list and keys/revoke.

Never expose your API key in client-side code. Always make API calls from your backend server.

Conventions

Base URL: https://api.botonom.com/en/api/v1

Paths are <resource>/<action>/ - identifiers travel as query parameters or in the JSON body, never in the path.
agent_id is always the agent's uuid (from agents/list).
Every response uses the envelope {status, code, title, data, msg}; failures add a machine-readable error.code and a real HTTP status.
Idempotency-Key header (max 128 chars) is supported on agents/command and every create endpoint: retrying the identical request replays the stored response instead of duplicating the action; the same key with a different payload returns 409 IDEMPOTENCY_CONFLICT.

The full machine-readable contract is published as an OpenAPI 3.0 spec, and you can try every endpoint live in the API Playground.

Core endpoints

Method	Endpoint	Description
GET	`agents/list`	List agents (public id = uuid)
GET	`agents/get?agent_id=`	Agent details
POST	`agents/create`	Hire an agent from a preset
POST	`agents/command`	Give an agent a natural-language command
GET	`agents/command_status?run_id=`	Poll a command run
GET	`skills/list` · POST `skills/install`	Skill catalog + install/remove
POST	`contacts/create` · `calendar/event_create` · `tasks/create`	Create records agents work with
GET	`usage/tokens` · `billing/get`	Usage and billing reads
POST	`webhooks/create`	Subscribe to signed events

The flagship flow is agents/command: your system sends an instruction, the agent executes it asynchronously with its own persona, skills and permissions (with autonomy: full it acts - e.g. sends an email from its own address).

POST /v1/agents/command
{
  "agent_id": "<agent-uuid>",
  "instruction": "Send a short welcome email to ahmet@example.com and greet him by name.",
  "data": { "name": "Ahmet" },
  "autonomy": "full"
}

Response (202 Accepted):

{
  "status": true,
  "code": 202,
  "data": {
    "run": { "run_id": "cmd_654741d0...", "status": "queued", "autonomy": "full" }
  },
  "msg": "Command queued"
}

Poll agents/command_status?run_id=cmd_... until status is completed (the agent's reply arrives in result_text), or skip polling entirely by subscribing to the agent.command.completed webhook.

Webhooks

Subscribe an https endpoint to events; the signing secret (whsec_...) is returned once:

POST /v1/webhooks/create
{
  "url": "https://yourapp.com/botonom/webhook",
  "events": ["agent.command.completed", "agent.command.failed"]
}

Deliveries carry X-Botonom-Event and X-Botonom-Signature: t=<unix>,v1=<hmac> headers. Failed deliveries retry automatically (2m / 10m / 30m / 2h, max 5 attempts); 20 consecutive failures auto-disable the subscription. See the Webhook Setup Guide for signature verification code.

Rate limits & errors

Common status codes and error codes:

HTTP	error.code	Meaning
400	`VALIDATION_ERROR`	Missing or malformed input
401	`API_KEY_REQUIRED` / `API_KEY_INVALID`	Missing or bad key
404	`AGENT_NOT_FOUND` / `RUN_NOT_FOUND` / `NOT_FOUND`	Unknown resource
405	`METHOD_NOT_ALLOWED`	Wrong HTTP method
409	`IDEMPOTENCY_CONFLICT`	Same Idempotency-Key, different payload
429	`RATE_LIMITED`	Quota exceeded - honor `Retry-After`

Business gates surface with their own codes, e.g. TOKEN_LIMIT_REACHED, PLAN_REQUIRED, SKILL_OAUTH_REQUIRED. Treat error.code as the stable contract; human-readable msg text may change.

See API Rate Limits for quota details.

Canlı deneyin

Bu makaledeki endpoint'leri API Playground'da test edin.

Playground'ı aç

apiresttokenwebhooksintegration