Building with agents
The CLI, the messaging SDK, and the agent-readable docs layer.
BWEZE is built to be driven by AI agents as much as by humans.
CLI - @bweze/cli
Agents drive BWEZE from the terminal the same way people do:
npx @bweze/cli login
bweze projects create acme-web --type frontend
bweze projects domains search acmeAnything the CLI does is also a plain REST call with a bearer key; see the error contract below. Calls that spend money or send a message accept an idempotency key, so a retry never double-acts.
SDK - @bweze/messaging
import { BwezeMessaging } from "@bweze/messaging";
const sms = new BwezeMessaging({ apiKey: process.env.BWEZE_API_KEY! });
await sms.send({ to: "+250788123456", template: "Code {{c}}", data: { c: 1234 } });Errors throw a typed BwezeError carrying the same code and docs URL as
the HTTP API.
Agent-readable docs
/llms.txt- the index, one screen./llms-full.txt- everything an agent needs in one file.- Every docs page is also served as raw markdown under
/llms.mdx/docs/...for tools that want per-page context. - Machine-readable API spec:
https://api.bweze.com/v1/openapi.json.
Error contract
Every error, everywhere:
{ "error": { "code": "insufficient_balance", "message": "...", "docs": "https://docs.bweze.com/errors/insufficient_balance" } }Always branch on code; message is for humans. Common codes:
| Code | Status | Meaning |
|---|---|---|
missing_api_key / invalid_api_key | 401 | No or bad bearer key |
secret_key_required | 403 | Endpoint needs bw_sk_... |
key_role_denied | 403 | The token owner's workspace role doesn't allow this action |
token_permission_denied | 403 | The token was not granted this action (API tokens) |
token_resource_denied | 403 | The project, backend or zone is outside the token's resources |
token_ip_denied | 403 | The request's address is outside the token's IP filter |
token_expired / token_not_yet_valid | 401 | Outside the token's validity window |
insufficient_balance | 402 | Top up before retrying |
recipient_opted_out | 409 | Never retry |
idempotency_key_reuse_mismatch | 409 | Same key, different content |
message_too_long | 400 | Over 10 segments |