BWEZE Docs

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 acme

Anything 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:

CodeStatusMeaning
missing_api_key / invalid_api_key401No or bad bearer key
secret_key_required403Endpoint needs bw_sk_...
key_role_denied403The token owner's workspace role doesn't allow this action
token_permission_denied403The token was not granted this action (API tokens)
token_resource_denied403The project, backend or zone is outside the token's resources
token_ip_denied403The request's address is outside the token's IP filter
token_expired / token_not_yet_valid401Outside the token's validity window
insufficient_balance402Top up before retrying
recipient_opted_out409Never retry
idempotency_key_reuse_mismatch409Same key, different content
message_too_long400Over 10 segments

On this page