BWEZE Docs

API reference

Every /v1 endpoint of api.bweze.com - base URL, auth, the permission each one needs, rate limits, idempotency and errors.

Everything the dashboard and the CLI do goes through one REST API:

curl https://api.bweze.com/v1/me -H "authorization: Bearer bw_sk_..."

The machine-readable spec is https://api.bweze.com/v1/openapi.json (OpenAPI 3.1). Where this page and the spec disagree, this page follows what the API does.

Conventions

  • Base URL: https://api.bweze.com. Every path starts with /v1.
  • Auth: Authorization: Bearer <token>. Secret tokens (bw_sk_...) work everywhere; publishable tokens (bw_pk_...) only read, and only where an endpoint says so (today: GET /v1/domains/rw/{name}). Every endpoint below also needs the token to hold the permission listed, on the resource it touches. See API tokens.
  • Bodies are JSON: send content-type: application/json.
  • Money is in RWF minor units in fields that end in Minor (priceMinor: 18000 is 18,000 RWF).
  • Lists return the whole set. The exceptions take query parameters: job runs (?limit=, 1-200, default 50), a job's log lines (?after=<line id>, up to 2,000 at a time) and analytics (?days=, 1-90, default 30).
  • Rate limit: 300 requests a minute per token. Over that, requests fail with rate_limited until the minute is up.
  • Idempotency: POST /v1/messages takes an Idempotency-Key header (or idempotencyKey in the body). A retry with the same key returns the first result with replayed: true and charges nothing; the same key with different content is 409 idempotency_key_reuse_mismatch.

Errors

Every error has the same shape. Branch on code; message is for people.

{
  "error": {
    "code": "insufficient_balance",
    "message": "This message costs 15 RWF; available balance is 0. Top up to send.",
    "docs": "https://docs.bweze.com/errors/insufficient_balance"
  }
}

The error codes page lists every code, its status and whether a retry can help.

Account

EndpointPermissionWhat it does
GET /v1/meany secret tokenThe token's workspace, owner, permissions, resources and expiry (API tokens)
GET /v1/pricingnoneThe published price list, current and scheduled, in RWF (Pricing)

Projects and Terminal

EndpointPermissionWhat it does
GET /v1/projectsdeployment:readProjects the token can see
POST /v1/projectsdeployment:createCreate a project: name, type (frontend or backend). Not for tokens limited to some projects
GET /v1/projects/{id}deployment:readOne project
GET /v1/projects/{id}/analyticsdeployment:readTraffic for the last ?days= days
POST /v1/projects/{id}/execterminal:execRun one command in the running container: command (Terminal)

Services and jobs

EndpointPermissionWhat it does
GET /v1/projects/{id}/servicesdeployment:readThe project's services
GET /v1/services/{id}deployment:readOne service
PATCH /v1/services/{id}deployment:updateport, start_command, pre_deploy_command, cron_schedule, cron_timeout_seconds, sleep_after_minutes (Services)
GET /v1/services/{id}/jobsdeployment:readJob and cron runs, newest first
POST /v1/services/{id}/jobsterminal:execRun a command once on the live release: command, timeout_seconds (60-43,200, default 3,600) (Jobs)
GET /v1/services/{id}/jobs/{jobId}deployment:readOne run and its log lines after ?after=
POST /v1/services/{id}/jobs/{jobId}/cancelterminal:execStop a run

Scheduled URLs and the firewall

EndpointPermissionWhat it does
GET /v1/projects/{id}/crondeployment:readScheduled URL calls
POST /v1/projects/{id}/crondeployment:createCall target_url on schedule: name, schedule, target_url
PATCH /v1/cron/{id}deployment:updateTurn one on or off: enabled
DELETE /v1/cron/{id}deployment:deleteDelete one
GET /v1/projects/{id}/firewalldeployment:readFirewall rules
POST /v1/projects/{id}/firewalldeployment:createAllow or block a range: action (allow or block), cidr, note
DELETE /v1/firewall/{id}deployment:deleteDelete a rule

Backends

EndpointPermissionWhat it does
GET /v1/backendsbackend:readThe workspace's backends
POST /v1/backendsbackend:createCreate one: name (2-31 lowercase letters, digits and hyphens). Not for tokens limited to some backends
GET /v1/backends/{id}backend:readOne backend and whether it is running
POST /v1/backends/{id}/deploybackend:createStart or restart it
GET /v1/backends/{id}/keysbackend:createIts URL, anon and service-role keys, and Postgres password
DELETE /v1/backends/{id}backend:deleteDelete it and its data: confirm must be the backend's name

See Backends.

SMS

EndpointPermissionWhat it does
POST /v1/messagesmessage:sendSend: to, body or template + data, idempotencyKey. Charged per segment (Messaging)
POST /v1/messages/previewmessage:readEncoding and segment count, without sending or charging

Domains

EndpointPermissionWhat it does
GET /v1/domains/search?q=dns:readAvailability and first-year price
GET /v1/domains/rw/{name}dns:read, publishable tokens tooIs a .rw name free
GET /v1/projects/{id}/register-domaindns:readThe project's purchases and the saved owner
POST /v1/projects/{id}/register-domaindns:createBuy a domain from the wallet: domain, registrant (Domains)
GET /v1/projects/{id}/domainsdns:readThe project's custom domains
POST /v1/projects/{id}/domainsdns:createConnect a domain you own, or a *.bweze.app name: domain
POST /v1/domains/{id}/verifydns:readCheck its DNS records again
DELETE /v1/domains/{id}dns:deleteDetach it from the project

DNS

EndpointPermissionWhat it does
GET /v1/dns/zonesdns:readZones hosted on BWEZE's nameservers
POST /v1/dns/zonesdns:createAdd a zone: zone. Not for tokens limited to some zones
GET /v1/dns/zones/{zone}dns:readA zone and its record sets
DELETE /v1/dns/zones/{zone}dns:deleteDelete a zone
POST /v1/dns/zones/{zone}/recordsdns:updateSet a record set: name, type, ttl, records (DNS)
DELETE /v1/dns/zones/{zone}/recordsdns:deleteDelete a record set: name, type

On this page