# Getting Started (/docs)




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

| Host                           | What it serves                                                                                                                                                                             |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `https://api.brault.app/v1`    | **Central.** Your key's own context, plan, usage, members and roles — 7 paths, the same host worldwide.                                                                                    |
| `https://us.api.brault.app/v1` | **Regional.** Everything that holds your content: files, folders, libraries, boards, pages, transfers, webhooks, search. Answered by the region your brandspace lives in, and by no other. |

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`](/docs/reference/meta/MetaController_me) returns both hosts for your key in
its `hosts` field. [Conventions](/docs/conventions#central-and-regional-hosts) 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](/docs/conventions) for the full versioning policy.

## 1. Get an API key [#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](/docs/get-an-api-key) walks through the panel step by step; see
[Authentication and keys](/docs/authentication-and-keys) for scopes, lifecycle and error
codes.

## 2. Make your first request [#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:

<ApiExample plane="central">
  ```bash title="cURL"
  curl https://api.brault.app/v1/me \
    -H "Authorization: Bearer $BRAULT_API_KEY"
  ```

  ```js title="JavaScript"
  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);
  ```

  ```python title="Python"
  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"])
  ```
</ApiExample>

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

```json
{
  "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](/docs/conventions) for the wire format,
pagination and error shape shared by every route.

## 3. Where to go next [#3-where-to-go-next]

* [Authentication and keys](/docs/authentication-and-keys) — key format, scopes, lifecycle.
* [Plans and limits](/docs/plans-and-limits) — rate limits, quotas, and the plan table.
* [Conventions](/docs/conventions) — pagination, errors, idempotency, versioning.
* [Guides](/docs/guides/upload-and-organize) — end-to-end walkthroughs for common tasks.
* [Webhooks](/docs/webhooks) — event catalogue and signature verification.
* [API Reference](/docs/reference) — every `/v1` operation, generated from the OpenAPI document.

<Cards>
  <Card title="Authentication and keys" href="/docs/authentication-and-keys" />

  <Card title="API Reference" href="/docs/reference" />
</Cards>