OpenAPI & routes
The engine aggregates every entitled package’s routes into one OpenAPI document. It is the exhaustive, always-current list of endpoints a given box exposes, because it is generated from the code that box actually runs.
Where to find it
| Surface | Path | Description |
|---|---|---|
| Swagger UI | GET /docs | Interactive, browsable API explorer |
| OpenAPI JSON | GET /docs/json | Machine-readable document for codegen/tooling |
Against a local box the defaults are:
http://localhost:3001/docs # Swagger UI
http://localhost:3001/docs/json # OpenAPI JSONThe document is built with these identifiers:
| Field | Value |
|---|---|
| Title | Box Backend |
| Version | 0.1.0 |
| Description | Partner-deployed Potter runtime: engine-mounted routes. |
Because the document is generated from the installed packages, a basic
box and an enterprise box expose different /docs. Always read the document
from the box you are integrating against, not a reference dump.
For a static, browsable map of which module mounts which routes, see the Module API reference: it lists all 372 routes by module, extracted from the package controllers.
Why the live document is the reference
Every @withpotter/* package annotates its controllers with Swagger decorators
(@ApiTags, @ApiOperation, DTO schemas). The engine calls
SwaggerModule.createDocument(app, …) after all modules are imported, so the
output reflects exactly the routes, request bodies, and response shapes of the
running build. Treat /docs/json as the canonical contract for client
generation.
Authentication
The OpenAPI document declares no global security scheme. Authentication is enforced per route by the engine. Public website requests are securely scoped to the correct merchant by Potter Website Hosting; authenticated member calls use the credentials issued for that member session.
First-party routes
Checkout
POST /checkout
GET /checkout/:orderIdPOST /checkout converts the active cart into an order. The body is a
CheckoutDto:
| Field | Required | Notes |
|---|---|---|
customer.email | yes | Buyer email |
customer.name / phone / address / billing | no | Optional buyer details |
notes | no | Free-text order note |
paymentMethod | no | Selects the payment flow |
The service loads the active cart (by session or member), validates it is
non-empty, generates an order number, creates the order with its items inside a
transaction, and clears the cart. GET /checkout/:orderId returns an order,
scoped to the current tenant.
Payment initiation is delegated to the bound payment provider adapter. With
the default noop adapter, any payment step returns
503 Payments are not configured in this environment. See
Adapters & ports → Payments.
Health
GET /healthReturns a health-check result for liveness probes and load balancers.
Migrations on boot
Before the server listens, the shell runs database migrations:
- Glob every
node_modules/@withpotter/*/migrations/*.js. - Sort by the timestamp-prefixed filename so cross-package foreign-key dependencies resolve in order.
- Run via Umzug +
SequelizeStorageagainst a sharedSequelizeMetatable. - Each migration runs exactly once; re-running the engine is a no-op.
This means adding an entitled package and restarting the engine is enough to bring its tables online: there is no separate migration step to remember.