Getting Started

The Brault public API lets you automate libraries, files, boards, pages, reviews, sharing and transfers in your brandspace. It is a JSON HTTP API served on two hosts:

Regional paths are served next to your data, so an EU brandspace's files are answered by an EU machine and never by a US one. You do not have to work it out: every code example on this site is labeled Central or Regional and shows the host to call, and GET /v1/me returns both hosts for your key in its hosts field. Conventions has the full table of the 7 central paths.

Every route lives under /v1 — there is no /api segment in the public URL. The version is part of the path: additive changes (new fields, endpoints, optional parameters) never bump it, and a breaking change would ship as /v2 served alongside /v1 for at least 12 months. See Conventions for the full versioning policy.

1. Get an API key

API access starts at the Lite plan — the Free plan has no API access. Keys are created and managed from Settings → Developers → API keys in the Brault web app, never through the API itself. A key looks like:

bsk_<region>_<8-character prefix>_<46-character secret>

The <region> segment names the regional host to call — bsk_us_… means us.api.brault.app. A key created before regions existed has no such segment (bsk_<prefix>_<secret>); it keeps working forever and means us.

It is shown in full exactly once, at creation. Store it like any other secret. Get an API key walks through the panel step by step; see Authentication and keys for scopes, lifecycle and error codes.

2. Make your first request

Every request authenticates with Authorization: Bearer <key> — never as a query parameter. Here is the simplest possible call, which just confirms who the key is and what it can do:

curl https://api.brault.app/v1/me \
  -H "Authorization: Bearer $BRAULT_API_KEY"

const res = await fetch('https://api.brault.app/v1/me', {
  headers: { Authorization: `Bearer ${process.env.BRAULT_API_KEY}` },
});
const me = await res.json();
console.log(me.brandspace.name, me.plan.type);

import os
import requests

res = requests.get(
    "https://api.brault.app/v1/me",
    headers={"Authorization": f"Bearer {os.environ['BRAULT_API_KEY']}"},
)
me = res.json()
print(me["brandspace"]["name"], me["plan"]["type"])

A successful response looks like this (field names and shapes below are taken directly from the published OpenAPI document, GET /v1/me):

{
  "object": "api_key_context",
  "brandspace": { "id": "clx1…", "name": "Acme Studio", "username": "acme", "region": "us" },
  "key": {
    "id": "…",
    "name": "CI integration",
    "display": "bsk_us_a1b2c3d4_…wxyz",
    "scopes": ["files:read", "files:write"],
    "region": "us",
    "region_stale": false,
    "expires_at": null
  },
  "created_by": { "id": "…", "name": "Jamie Rivera" },
  "plan": { "type": "pro", "name": "Pro" },
  "limits": {
    "burst_per_second": 10,
    "sustained_per_minute": 300,
    "monthly_requests": 100000,
    "uploads_per_day": 2000,
    "downloads_per_day": 10000,
    "search_per_minute": 30
  },
  "hosts": {
    "central": "https://api.brault.app",
    "regional": "https://us.api.brault.app"
  }
}

hosts is the answer to "which host do I call?", read straight from your own key: hosts.central for the 7 central paths, hosts.regional for everything else. brandspace.region is authoritative and decides which host may answer; key.region is the hint printed inside the key string, and key.region_stale is true only when the brandspace moved region after the key was minted — the key still works, the printed hint is what went out of date.

Every object on the wire carries an "object" field identifying its type, and every response is snake_case — see Conventions for the wire format, pagination and error shape shared by every route.

3. Where to go next

• Authentication and keys — key format, scopes, lifecycle.
• Plans and limits — rate limits, quotas, and the plan table.
• Conventions — pagination, errors, idempotency, versioning.
• Guides — end-to-end walkthroughs for common tasks.
• Webhooks — event catalogue and signature verification.
• API Reference — every /v1 operation, generated from the OpenAPI document.