# HTTP API reference

Every operation of the BuildBase HTTP API, by tag, generated from its OpenAPI description: method, path, sign-in, fields, answers and errors.

The API your app and `@buildbase/sdk` call: hosted sign-in, OAuth 2.0, and the session API that acts as one signed-in user of your app.

618 operations in 42 groups. 204 are fully described; the others have a page that says what is still missing.

## Where to send requests

| Server                | URL                                 |
| --------------------- | ----------------------------------- |
| BuildBase cloud       | `https://api.console.buildbase.app` |
| A self-hosted install | `{serverUrl}`                       |

## How a request signs in

Each operation page says which of these it needs.

| Credential    | How to send it              | What it is                                                                                                           |
| ------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `loginToken`  | `Authorization: Bearer ...` | An app end user's login token from hosted sign-in, for the same org as the request.                                  |
| `orgQuery`    | the `org` query parameter   | The org id the request is for, when there is no sign-in state. Not a credential.                                     |
| `sessionId`   | the `x-session-id` header   | An end user's session id, as the SDK sends it. `POST /api/v1/public/token/exchange` issues one for an org API token. |
| `signInState` | the `state` header          | The hosted sign-in state id. Names the org the request is for; not a credential.                                     |

## Operations by tag

| Tag                                                              | Operations | Fully described |
| ---------------------------------------------------------------- | ---------- | --------------- |
| [Account](/http-api/reference/account)                           | 2          | 2               |
| [Accounts](/http-api/reference/accounts)                         | 6          | 6               |
| [Ad conversions](/http-api/reference/ad-conversions)             | 2          | 2               |
| [Add ons](/http-api/reference/add-ons)                           | 1          | 0               |
| [Agent readiness](/http-api/reference/agent-readiness)           | 1          | 1               |
| [Analytics](/http-api/reference/analytics)                       | 1          | 1               |
| [Auth](/http-api/reference/auth)                                 | 63         | 45              |
| [Beta](/http-api/reference/beta)                                 | 2          | 2               |
| [Billing](/http-api/reference/billing)                           | 1          | 0               |
| [Cart](/http-api/reference/cart)                                 | 3          | 0               |
| [Checkout](/http-api/reference/checkout)                         | 3          | 0               |
| [Connected agents](/http-api/reference/connected-agents)         | 2          | 2               |
| [Consent](/http-api/reference/consent)                           | 2          | 1               |
| [Credit packages](/http-api/reference/credit-packages)           | 1          | 0               |
| [Device token](/http-api/reference/device-token)                 | 1          | 1               |
| [Devices](/http-api/reference/devices)                           | 3          | 3               |
| [Discovery](/http-api/reference/discovery)                       | 6          | 3               |
| [Guest](/http-api/reference/guest)                               | 2          | 2               |
| [Invitations](/http-api/reference/invitations)                   | 4          | 0               |
| [Item types](/http-api/reference/item-types)                     | 2          | 0               |
| [Items](/http-api/reference/items)                               | 5          | 0               |
| [Logout](/http-api/reference/logout)                             | 1          | 1               |
| [Me](/http-api/reference/me)                                     | 182        | 0               |
| [MFA](/http-api/reference/mfa)                                   | 8          | 7               |
| [monday.com](/http-api/reference/monday-com)                     | 7          | 4               |
| [Notifications](/http-api/reference/notifications)               | 8          | 6               |
| [OAuth 2.0](/http-api/reference/oauth-2-0)                       | 12         | 10              |
| [Passkeys](/http-api/reference/passkeys)                         | 3          | 3               |
| [Plan group versions](/http-api/reference/plan-group-versions)   | 1          | 0               |
| [Plans](/http-api/reference/plans)                               | 1          | 0               |
| [Profile](/http-api/reference/profile)                           | 10         | 7               |
| [Promotions](/http-api/reference/promotions)                     | 1          | 0               |
| [Push](/http-api/reference/push)                                 | 4          | 2               |
| [Session](/http-api/reference/session)                           | 3          | 3               |
| [Sessions](/http-api/reference/sessions)                         | 2          | 2               |
| [Settings](/http-api/reference/settings)                         | 1          | 1               |
| [Token](/http-api/reference/token)                               | 1          | 1               |
| [Tracking](/http-api/reference/tracking)                         | 1          | 1               |
| [Uploads](/http-api/reference/uploads)                           | 2          | 2               |
| [Users](/http-api/reference/users)                               | 5          | 3               |
| [Web analytics beacon](/http-api/reference/web-analytics-beacon) | 1          | 1               |
| [Workspaces](/http-api/reference/workspaces)                     | 251        | 79              |

## For tools and agents

- The OpenAPI description these pages come from: [public-v1.json](https://docs.buildbase.app/openapi/public-v1.json)
- Every fully described operation, one line each: [llms/http-api.txt](https://docs.buildbase.app/llms/http-api.txt)
- Any page as Markdown: its URL with `.md` added
