API Reference
Overview

REST API overview

Base URL

https://api.tahlib.com/v1      # production
http://localhost:3001/v1       # local development

Requests and responses are JSON. Send Content-Type: application/json on any request with a body.

Headers

HeaderWhenPurpose
AuthorizationEvery route not marked publicBearer <access token>. See Authentication.
Content-TypeRequests with a bodyapplication/json
X-Restaurant-IdOptionalThe restaurant (location) to act in.
Idempotency-KeyOptional, on the routes that support itReplays 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:

  1. If X-Restaurant-Id names a restaurant where the user has an active staff membership, and that restaurant has not been deleted, that restaurant is used.
  2. Otherwise the header is ignored, without an error, and the API uses the restaurant the user joined first (their oldest active membership).
  3. 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:

WindowRequests
10 seconds30
1 minute100
1 hour1,000

Some routes have tighter or extra limits:

RouteLimit
POST /v1/auth/signup, POST /v1/auth/forgot-password5 per minute per IP
POST /v1/auth/login, /reset-password, /accept-invite10 per minute per IP
POST /v1/auth/google, /verify-email20 per minute per IP
POST /v1/auth/login10 failed attempts lock that email for 15 minutes (too_many_attempts)
POST /v1/orders, POST /v1/orders/:id/itemsalso 1,000 per minute per restaurant
POST /v1/api-keys5 per minute
POST /v1/webhooks/:id/test5 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:

RouteParametersResponse
GET /v1/orderslimit (default 25, max 200), offset{ rows, total, … }
GET /v1/audit-loglimit (default 50, max 200), cursor{ items, nextCursor }
GET /v1/webhooks/:id/deliveriespage (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/restaurant in apps/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