API reference

REST API overview.

The Brily API is a standard JSON REST API. Every endpoint lives under api.brily.app, every request authenticates with a bearer token, every response has a predictable error shape. Version v0 during private beta. v1 freezes at public beta in Q3 2026.

Base URL

https://api.brily.app/v0

Authentication

Every request includes a bearer token in the Authorization header. Tokens are project-scoped by default. Organisation-scoped tokens are available for cross-project automation.

Authorization: Bearer brly_live_r8xH2...eP1W

Create tokens under Settings → API tokens. Token prefixes are stable: brly_live_ for production, brly_test_ for sandbox. Treat them like passwords. They grant full access within their scope.

Content type

Requests with a body send Content-Type: application/json. Responses are always JSON with UTF-8 encoding.

Versioning

The version segment sits in the URL (/v0/monitors). Breaking changes move to a new version. Additive changes happen in place. During v0 we reserve the right to rename fields with 14 days' notice by email. At v1 freeze, the contract is stable.

Rate limits

Default: 60 requests per second per token for read endpoints, 10 per second for writes. Business and Enterprise plans get higher limits on request. Responses include rate-limit headers.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1712860321

Exceeding the limit returns HTTP 429 with a retry_after field in the error body (seconds).

Pagination

List endpoints return a cursor-based paginated response.

{
  "data": [ /* items */ ],
  "pagination": {
    "next_cursor": "eyJpZCI6ICJtb25fMTIzIn0",
    "has_more": true
  }
}

Pass ?cursor= and ?limit= (max 100, default 25) to paginate. Cursors are opaque. Do not try to decode or construct them.

Errors

Error responses use a consistent shape with a stable machine code plus a human message.

{
  "error": {
    "code": "validation_failed",
    "message": "url is required and must be a valid URL",
    "field": "url",
    "request_id": "req_8aFj2Nc"
  }
}

Standard HTTP status codes:

200, 201, 204: success
400: validation_failed
401: unauthenticated (missing or invalid token)
403: unauthorized (token scope insufficient)
404: not_found
409: conflict (e.g., duplicate name)
429: rate_limited
500, 503: server errors. Rare. Include them in bug reports.

Idempotency

Mutating endpoints accept an Idempotency-Key header. Supply a UUID per logical action. Brily deduplicates retries for 24 hours. Recommended for any write from a CI pipeline.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Webhook signing

Outbound webhooks are signed with HMAC-SHA256. Verify with the shared secret from Settings → Webhooks.

// TypeScript
import crypto from "crypto";

function verify(rawBody: string, signature: string, secret: string) {
  const mac = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(mac),
    Buffer.from(signature.replace(/^sha256=/, ""))
  );
}

Request IDs

Every response includes an X-Request-Id header. Include it when you email support. We find your request in our logs in seconds instead of minutes.

Monitors API