Developer: API overview
The BoostUp API is a JSON API built with FastAPI. The web app, the Hermes employee and your own tools use the same endpoints.
Schema
The live OpenAPI schema is at /openapi.json on the API host. A readable view of it is in the
API reference.
Authentication
Browsers authenticate with a session cookie set by POST /auth/login or POST /auth/register:
bu_session: httpOnly,SameSite=Lax,Securein production.bu_csrf: readable by the page. EveryPOST,PATCHandDELETEmust send its value in theX-CSRF-Tokenheader. Requests from a foreignOriginare refused.
Scoped tokens for the Hermes employee arrive with agent provisioning.
Organization context
Most endpoints act inside one organization. By default this is your active organization. To pick another one you
belong to, send X-Org-Id: <organization id>. Asking for an organization you do not belong to returns 404, the
same answer as for one that does not exist.
Main endpoints
| Area | Endpoints |
|---|---|
| Auth | POST /auth/register, POST /auth/login, POST /auth/logout, GET /auth/me, POST /auth/verify, POST /auth/password/forgot, POST /auth/password/reset |
| Organizations | GET /orgs, POST /orgs, GET /orgs/{id}/members, POST /orgs/{id}/members (invite), PATCH and DELETE /orgs/{id}/members/{membership_id}, POST /invites/{id}/accept |
| Brands | GET /brands, POST /brands, GET, PATCH, DELETE /brands/{id}, POST /brands/{id}/websites |
| Approvals | GET /approvals, POST /approvals, POST /approvals/{id}/decision |
| Jobs | GET /jobs, GET /jobs/{id}, POST /jobs/ping, POST /jobs/{id}/cancel |
| Usage | GET /usage/summary, GET /usage/records |
| Support | GET and POST /support/tickets, GET and POST /support/feature-requests, POST and DELETE /support/feature-requests/{id}/vote |
| Health | GET /health |
Errors
Errors are JSON with a detail field. Notable status codes:
| Code | Meaning |
|---|---|
| 401 | Not signed in or session expired |
| 402 | Plan limit reached, or a provider budget would be exceeded (code: budget_exceeded) |
| 403 | Your role is not allowed to do this, or the CSRF token is missing |
| 404 | Not found, including anything that belongs to another organization |
| 409 | Conflict, for example a duplicate invitation or removing the last owner |
| 503 | A provider is not configured on this deployment |