REST API reference

All endpoints are owned by apps/api, a Hono application on Cloudflare Workers. Owner routes are guarded by a session token stored in the SESSIONS KV namespace; public routes are unauthenticated. Data is persisted to D1 via Drizzle, and realtime traffic is routed through the per-restaurant OrderHub Durable Object.

This is a summarized reference grouped by area. For the realtime streams see realtime: reconnect and snapshots.

Auth

Owner identity and sessions.

Method	Path	Purpose
`POST`	`/v1/auth/signup`	Self-serve owner signup with a mock card. Creates the restaurant and the owner user, returns a session, and deep-links into the onboarding wizard.
`POST`	`/v1/auth/login`	Owner login. Issues an opaque session token stored in `SESSIONS` KV and sets a cookie.
`POST`	`/v1/auth/logout`	Invalidate the current session in KV.
`GET`	`/v1/auth/me`	Return the current authenticated owner plus restaurant context for the console and KDS.

Unauthenticated customer-facing menu read.

Method	Path	Purpose
`GET`	`/v1/r/:slug/menu`	Public customer menu: ordered, non-hidden categories with products, modifiers, sold-out and hidden flags, and the current store open and accepting state. Cached in `MENU_CACHE` KV and invalidated on owner mutations.

Categories (owner)

Menu category management.

Method	Path	Purpose
`GET`	`/v1/categories`	List categories in display order.
`POST`	`/v1/categories`	Create a category.
`PATCH`	`/v1/categories/:id`	Update name, description, or hidden flag.
`DELETE`	`/v1/categories/:id`	Delete a category.
`PATCH`	`/v1/categories/reorder`	Persist drag-to-reorder display order in one call.

Products (owner)

Menu product management, including the signature 86 toggle.

Method	Path	Purpose
`GET`	`/v1/products`	List products, optionally by category, with hidden and sold-out flags.
`POST`	`/v1/products`	Create a product with price, description, and modifiers.
`PATCH`	`/v1/products/:id`	Update product fields (price, description, category, modifiers).
`DELETE`	`/v1/products/:id`	Delete a product.
`PATCH`	`/v1/products/reorder`	Persist drag-to-reorder display order.
`PATCH`	`/v1/products/:id/sold-out`	The 86 toggle. Flip `is_sold_out`, invalidate the menu cache, and push the update so the item vanishes from the customer portal within seconds.
`PATCH`	`/v1/products/:id/visibility`	Toggle published or hidden.

Media

Image upload.

Method	Path	Purpose
`POST`	`/v1/media/upload-url`	Get a direct upload path to store a product or logo image in R2. Returns the `r2_key`.

Cart and orders

Stateless pricing, order placement, payment, and KDS state advance.

Method	Path	Purpose
`POST`	`/v1/cart/price`	Stateless cart pricing. The client sends items plus modifiers; the server uses `packages/core` to compute authoritative subtotal, tax, and total and to validate availability before checkout. No server-side cart persistence.
`POST`	`/v1/orders`	Place an order from a priced cart. Re-validate availability and price server-side, create the order (status placed) plus the order-items snapshot plus the `order_placed` event, and return `order_number` and `tracker_token`.
`POST`	`/v1/orders/:id/pay`	Mock payment. Take a card token through the mock processor, create the payment, transition placed to paid, and emit the `order_paid` event that lights up the KDS, tracker, and receipt pipeline.
`POST`	`/v1/orders/:id/transitions`	KDS state advance. The body specifies the target (accept, start, ready, complete, cancel); the `packages/core` state machine guards the transition, appends an `order_event` with the next `seq`, and OrderHub fans it out. One endpoint for all forward transitions keeps the spine single-sourced.
`GET`	`/v1/orders`	KDS and console: list active and recent orders for the restaurant (board hydration on load).
`GET`	`/v1/orders/:id`	Full order detail with items, events, payment, and receipt.

Customer tracker and realtime

Public order tracking plus the two realtime streams. See realtime: reconnect and snapshots for the snapshot and reconnect semantics.

Method	Path	Purpose
`GET`	`/v1/track/:trackerToken`	Public customer tracker snapshot: current status plus timestamps for the shareable status URL.
`GET`	`/v1/track/:trackerToken/stream`	Customer-facing SSE stream of order status events for one order, served via OrderHub. Sends a snapshot, then incremental events, deduplicated by `seq` on reconnect.
`GET`	`/v1/kds/stream`	KDS WebSocket or SSE upgrade to OrderHub for the restaurant. Snapshot of open tickets on connect, then ordered incremental order events. The client acks its last `seq` so reconnect replays only the gap, with no dropped or duplicated tickets.

Settings

Restaurant settings, the kill switch, and opening hours.

Method	Path	Purpose
`GET`	`/v1/settings`	Read restaurant settings (accepting orders, tax, ETA, KDS age threshold).
`PATCH`	`/v1/settings`	Update settings.
`PATCH`	`/v1/settings/accepting-orders`	Master kill switch. Toggle accepting orders; immediately reflected on the customer portal so new orders pause when the kitchen is slammed.
`GET`	`/v1/settings/hours`	Read the weekly opening-hours schedule.
`PUT`	`/v1/settings/hours`	Replace the weekly opening-hours schedule.

Receipts and export

The fixed receipt template, generated receipts, and owner data export.

Method	Path	Purpose
`GET`	`/v1/receipt-template`	Read the fixed receipt template (header, footer, show-logo). The template editor is deferred to V1.1.
`PATCH`	`/v1/receipt-template`	Update the limited fixed-template fields (header text, footer text, logo on or off).
`GET`	`/v1/orders/:id/receipt`	Fetch the generated fixed-format receipt (HTML or JSON) for render or browser-print on the KDS. Generated on Accept from the order event.
`GET`	`/v1/export`	Owner data export. Downloadable menu, customer order history, and receipts as JSON or CSV. The no-lock-in story.