REST API Reference

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.

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.

Getting the answer as data, not prose

result_text is written for a person. When your code is the reader, describe the shape you want with schema and the same run also returns output - an object with your field names in it.

POST /v1/agents/command
{
  "agent_id": "<agent-uuid>",
  "instruction": "Review this month's orders and summarise revenue.",
  "schema": {
    "type": "object",
    "properties": {
      "total_revenue": { "type": "number", "description": "Sum of quantity x price" },
      "currency":      { "type": "string", "enum": ["TRY", "USD"] },
      "top_product":   { "type": "string", "description": "Name of the highest-earning product" },
      "products": {
        "type": "array",
        "description": "Revenue per product",
        "items": { "type": "object", "properties": { "name": { "type": "string" }, "revenue": { "type": "number" } } }
      }
    },
    "required": ["total_revenue", "top_product"]
  }
}

command_status then returns both:

{
  "run_id": "cmd_654741d0...",
  "status": "completed",
  "result_text": "This month's revenue is 27,400 TRY; Masa earned the most...",
  "output": {
    "total_revenue": 27400,
    "currency": "TRY",
    "top_product": "Masa",
    "products": [{ "name": "Masa", "revenue": 10000 }]
  },
  "output_error": null
}

What you get without a schema

Leave schema out and output still arrives, in a standard envelope - so the endpoint is programmable by default:

actions and files are computed from the run itself, not written by the model, so they cannot drift from what really happened.

Rules worth knowing

• Supported types: string, number, integer, boolean, array, object. Up to 50 properties, nested up to 5 levels. Anything else returns 400 SCHEMA_INVALID with the exact path, e.g. properties.when: unsupported type "date".
• Optional means nullable. A property you leave out of required is always present in output and is null when the run did not produce it, so you never have to tell an absent key from a null one.
• output can be null, and then output_error says why. The prose answer is still delivered - a run is never failed because a shape could not be filled.
• Describe your fields. The description on a property is what the agent reads. A field called product_count with no description may come back as units sold rather than distinct products; one sentence removes the ambiguity.
• data goes in, output comes back. They are different halves of the same call: data is context you supply, output is the answer in your shape.

Try it against your own agent in the API Playground: the request body ships with a schema you can edit, and the run comes back with output beside result_text.

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.

Common status codes and error codes:

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.