/Docs

Public REST API

AvsB exposes a versioned REST API for managing every resource you can edit in the dashboard — projects, experiments, feature flags, audiences, segments, metrics, exclusion groups, results, and more. Authentication uses scoped service tokens; writes are retry-safe via the Idempotency-Key header; concurrent edits are detected via ETags; and every state-changing request appears in the organisation audit log.

Base URL

All API endpoints are served from the same hostname as your AvsB dashboard. Production endpoints look like:

text
1https://app.avsb.cloud/api/orgs/{orgId}/...

Authentication

Every public-API request must include a service token in the Authorization header:

bash
1curl https://app.avsb.cloud/api/orgs/<orgId>/projects \
2  -H "Authorization: Bearer avsb_svc_abc1234_..."

Service tokens are scoped (per resource family, read or write), rotation-aware, expirable, and revocable. They are different from Personal Access Tokens — see the Authentication guide for the full token model.

Response envelope

Successful responses return { "data": ... }:

json
1{ "data": { "id": "tok_abc", "name": "Terraform CI", ... } }

List endpoints add cursor pagination fields:

json
1{
2  "data": [ ... ],
3  "next_cursor": "eyJpZCI6ImFiYyIsInNvcnRWYWx1ZSI6IjIwMjYtMDUtMTciLCJzY2hlbWFWZXJzaW9uIjoxfQ",
4  "has_more": true
5}

Errors use a structured shape:

json
1{
2  "error": {
3    "code": "scope_missing",
4    "message": "Token is missing required scope: experiments:write",
5    "details": { "missingScope": "experiments:write" }
6  }
7}

Rate limits

Every response carries the standard rate-limit headers — read them and back off cleanly:

  • X-RateLimit-Limit — requests permitted per minute for this token + scope family.
  • X-RateLimit-Remaining — requests left in the current window.
  • X-RateLimit-Reset — Unix timestamp (seconds) when the window resets.
  • Retry-After — sent only on 429 responses; seconds to wait before retrying.

Idempotent writes

Every state-changing endpoint accepts an optional Idempotency-Key header. When supplied, the API guarantees that retrying the same request with the same key within 24 hours produces the same response — not a duplicate side effect:

bash
1curl https://app.avsb.cloud/api/orgs/<orgId>/tokens \
2  -X POST \
3  -H "Authorization: Bearer avsb_svc_..." \
4  -H "Content-Type: application/json" \
5  -H "Idempotency-Key: $(uuidgen)" \
6  -d '{"name":"CI","scopes":["projects:read"]}'

Re-using the same key with a different body returns 409 Conflict with a idempotency_conflicterror code, so retry storms can't silently corrupt data.

Optimistic concurrency via ETags

Every individual-resource read returns a weak ETag header. Pass that ETag back as If-Match on subsequent writes to detect concurrent edits:

bash
1# 1. Read the resource and store its ETag
2curl -i .../tokens/tok_123
3# → ETag: W/"a1b2c3d4e5f60798"
4

5# 2. Update with If-Match — succeeds only if no one else has written
6curl -X PATCH .../tokens/tok_123 \
7  -H "If-Match: W/\"a1b2c3d4e5f60798\"" \
8  -d '{"description":"renamed"}'
9# 412 Precondition Failed if the resource has changed since you read it.

Versioning

The API uses date-based version pinning via the AvsB-API-Version request header. Omit the header to track the latest version. Pin to a date to lock to a known-good contract:

bash
1curl .../projects \
2  -H "Authorization: Bearer ..." \
3  -H "AvsB-API-Version: 2026-05-17"

Audit log

Every state-changing request authenticated by a service token appears in your organisation audit log with source API, the token name as actor, the client IP, and a structured diff. Query the audit log itself through the API by reading with the audit:read scope.

Next steps

  • Authentication — service token creation, scopes, rotation, revocation.
  • OpenAPI specification — auto-generated machine-readable contract, served live, suitable for Postman/Insomnia/Bruno/OpenAPI Generator.