REST API overview
Base URL
https://api.tahlib.com/v1 # production
http://localhost:3001/v1 # local developmentRequests and responses are JSON. Send Content-Type: application/json on
any request with a body.
Headers
| Header | When | Purpose |
|---|---|---|
Authorization | Every route not marked public | Bearer <access token>. See Authentication. |
Content-Type | Requests with a body | application/json |
X-Restaurant-Id | Optional | The restaurant (location) to act in. |
Idempotency-Key | Optional, on the routes that support it | Replays a stored response instead of repeating a write. |
These are the request headers the API accepts from a browser (its CORS allow-list).
Choosing the restaurant: X-Restaurant-Id
A user can work at more than one restaurant. Each request runs against exactly one of them, chosen like this:
- If
X-Restaurant-Idnames a restaurant where the user has an active staff membership, and that restaurant has not been deleted, that restaurant is used. - Otherwise the header is ignored, without an error, and the API uses the restaurant the user joined first (their oldest active membership).
- A user with no staff membership but an active rider profile is resolved to the rider's restaurant.
A header that is not a valid UUID is ignored in the same way. If you need to
be sure which restaurant answered, call GET /v1/restaurant: it returns the
restaurant the request resolved to.
Postgres row-level security then limits every query in the request to that restaurant: rows belonging to other restaurants are not visible and cannot be written.
Success responses
A successful call returns the resource, or the list, as JSON. There is no shared envelope; each route returns its own shape.
Errors
Most errors follow NestJS's default shape:
{ "message": "Campaign 0000… not found", "error": "Not Found", "statusCode": 404 }Some routes add a machine-readable error code, such as permission_denied
or channel_unavailable, alongside message. Switch on error when it is
present and on the HTTP status otherwise.
400: validation failed
A request body that fails its schema returns:
{
"message": "validation failed",
"issues": [
{ "path": "channel", "message": "Required" }
]
}path is the dotted path to the field, for example items.0.productKey.
A malformed path parameter, such as an id that is not a UUID, gets Nest's
default 400 instead:
{ "message": "Validation failed (uuid is expected)", "error": "Bad Request", "statusCode": 400 }401: not authenticated
{ "message": "missing bearer token", "error": "Unauthorized", "statusCode": 401 }An expired or invalid token also returns 401, with a message beginning
token verification failed:.
402: product not active
Each module's routes are gated on the restaurant holding that product. When it doesn't, the API returns 402 Payment Required:
{
"error": "module_not_included",
"message": "Module 'webhooks' is not active for this restaurant",
"requiredModule": "webhooks",
"currentPlan": "…",
"upgradeUrl": "/modules?module=webhooks"
}upgradeUrl is a dashboard path where the owner can add the product.
currentPlan is an internal field kept for older accounts; don't rely on it.
403: permission denied
Each staff route requires a permission from the user's role:
{
"error": "permission_denied",
"message": "Missing required permission: customers.edit",
"requiredPermission": "customers.edit",
"actualRole": "cashier"
}Owner-only routes, such as activating a product, return 403 with
"error": "owner_required".
429: rate limited
{
"statusCode": 429,
"error": "rate_limit_exceeded",
"limit": 30,
"remaining": 0,
"resetAt": "2026-05-09T15:42:13.000Z",
"retryAfter": 7
}error is rate_limit_exceeded for the per-IP limits, or
restaurant_rate_limit for the per-restaurant ones. The response also
carries Retry-After (seconds), X-RateLimit-Limit, X-RateLimit-Remaining
and X-RateLimit-Reset (Unix seconds).
Rate limits
Every route is limited per client IP across three windows at once:
| Window | Requests |
|---|---|
| 10 seconds | 30 |
| 1 minute | 100 |
| 1 hour | 1,000 |
Some routes have tighter or extra limits:
| Route | Limit |
|---|---|
POST /v1/auth/signup, POST /v1/auth/forgot-password | 5 per minute per IP |
POST /v1/auth/login, /reset-password, /accept-invite | 10 per minute per IP |
POST /v1/auth/google, /verify-email | 20 per minute per IP |
POST /v1/auth/login | 10 failed attempts lock that email for 15 minutes (too_many_attempts) |
POST /v1/orders, POST /v1/orders/:id/items | also 1,000 per minute per restaurant |
POST /v1/api-keys | 5 per minute |
POST /v1/webhooks/:id/test | 5 per minute per endpoint |
Limits are counted in Redis, so they hold across API instances. If Redis is unreachable, each instance counts separately.
Pagination
There is no single pagination scheme. Lists that page say so in their query parameters:
| Route | Parameters | Response |
|---|---|---|
GET /v1/orders | limit (default 25, max 200), offset | { rows, total, … } |
GET /v1/audit-log | limit (default 50, max 200), cursor | { items, nextCursor } |
GET /v1/webhooks/:id/deliveries | page (from 1), pageSize (1–100, default 25) | { rows, page, pageSize, total, totalPages } |
Other lists return a plain array. Some of those are capped: GET /v1/campaigns,
for example, returns the newest 100.
Idempotency
On routes that support it, an Idempotency-Key header (at least 8
characters) stores the first response for 24 hours and returns it again for
a repeat of the same method, path and restaurant. Reusing a key for a
different request returns 409 idempotency_key_mismatch. Today only the
/v1/modules/* routes support it; elsewhere the header is ignored.
Sources
- Prefix, CORS headers, global filter:
apps/api/src/main.ts - Tenant resolution:
apps/api/src/auth/auth.guard.ts(resolveTenant,usableHeaderTenant);GET /v1/restaurantinapps/api/src/modules/core/restaurant.controller.ts - Row-level security:
docs/adr/009-row-level-security-enforcement.md,apps/api/src/tenant/tenant-context.interceptor.ts - 400 shape:
apps/api/src/common/zod-exception.filter.ts - 402 shape:
apps/api/src/auth/entitlement.guard.ts - 403 shapes:
apps/api/src/auth/permission.guard.ts,apps/api/src/auth/owner.guard.ts - 429 shape and headers:
apps/api/src/throttler/throttler-exception.ts - Limits:
apps/api/src/throttler/throttler.module.ts,restaurant-throttler.guard.ts,apps/api/src/auth/auth.controller.ts,apps/api/src/auth/auth.service.ts(login lockout),apps/api/src/modules/orders/orders.controller.ts,apps/api/src/modules/api-keys/api-keys.controller.ts,apps/api/src/modules/webhooks/webhook-queue.service.ts(checkTestRateLimit) - Pagination:
apps/api/src/modules/orders/orders.service.ts,apps/api/src/modules/audit-log/audit-log.controller.ts,apps/api/src/modules/webhooks/webhooks.controller.ts,apps/api/src/modules/campaigns/campaigns.service.ts - Idempotency:
apps/api/src/common/idempotency.interceptor.ts,apps/api/src/modules/marketplace/marketplace.controller.ts