REST API
bermooda serves two REST surfaces on the same app: a public storefront API for catalog, cart, and checkout, and an Admin API for shop operations, agents, and your own tools.
Where to send requests
Section titled “Where to send requests”| Audience | Base URL | Access |
|---|---|---|
| Storefront | /api/v1 |
Public. No API key. Carts are gated by the token returned when the cart is created. |
| Admin | /api/admin/v1 |
Requires an Admin API key (Authorization: Bearer berm_…) except for setup routes. |
Storefront catalog, search, cart, and checkout endpoints do not require a key. Most Admin routes do. See Authentication for keys, scopes, and first-time bootstrap.
A machine-readable OpenAPI description is published in the bermooda/bermooda repository.
Errors
Section titled “Errors”Every error response is JSON with a human-readable error string and a machine-readable code:
{ "error": "Invalid API key", "code": "KEY_INVALID" }| HTTP status | Meaning |
|---|---|
| 400 | Bad request (missing or invalid body) |
| 401 | Missing or invalid API key |
| 403 | API key lacks the required scope |
| 404 | Resource not found |
| 405 | Method not allowed |
| 422 | Business logic error (see code) |
Next steps
Section titled “Next steps”- Authentication — storefront cart tokens, Admin
berm_keys, scopes, and setup endpoints - Storefront — catalog, categories, search, reviews, cart, and checkout
- Admin — settings, catalog, orders, customers, reports, and other keyed resources
- Webhooks — payload shape, HMAC verification, retries, and events
Related guides: authentication and agents (MCP).