API reference

The Tamr API reference: every /api/v1 route for your backend and for apps that draw their own AI waiter chat, with authentication, schemas and curl, Node and Python examples.

Tamr's HTTP API lives at https://tamr.link/api/v1. Most apps never call the Client API, because the SDK's waiter page does. Every backend calls the Server API, to sign diners in with launch codes, send orders, set product ids, read menus and erase users. Each page below is generated from the committed OpenAPI spec, so it always matches what the server answers.

Two APIs

Server APIClient API
Who calls itYour backendThe waiter page, or your app if it draws its own chat
CredentialsA secret API key: Authorization: Bearer <key>Your publishable key in x-tamr-key and the diner's session in x-tamr-session
From a browserNever: no Server API route answers a browserOnly from an origin listed on the key
Limits100 requests a minute per secret keySee rate limits

Keys and permissions

Secret keys are made in Settings > API keys by an owner or admin of the restaurant, with one or more SDK permissions. Use one key per job if you can: a key that mints sessions can't then rewrite the catalog. A key stops working when the person who made it is no longer an owner or admin, so have a long-standing admin make it.

Permission in the dashboardScopeLets your backend
Diner sessions (SDK)diner:sdkCreate launch codes, erase a user
Catalog ids (SDK)catalog:sdkSet your product ids and nutrition figures
Orders (SDK)orders:sdkSend your orders, redeem treats
Menu read (SDK)catalog:readRead the restaurant's published menus

Publishable keys (tamr_pk_live_…, tamr_pk_test_…) are made in Settings > App keys. They name your app and are safe to ship in it. See Keys, test mode and guests.

Every route

Server API

Your backend, with a secret API key.

EndpointWhat it does
POST /api/v1/sdk/launch-codesMint a one-time launch code for one of your users
DELETE /api/v1/sdk/users/{externalUserId}Erase what Tamr holds for one of your users
POST /api/v1/sdk/ordersSend an order your own checkout placed
POST /api/v1/sdk/treats/{treatId}/redeemRedeem a treat your checkout gave at zero
PUT /api/v1/catalog/external-idsSet your ids for the restaurant's dishes, sizes and options
PUT /api/v1/catalog/nutritionSet your own nutrition figures for the restaurant's dishes
GET /api/v1/catalog/menuRead one of the restaurant's published menus

Client API

Your app or website, with a publishable key and the diner's session.

EndpointWhat it does
POST /api/v1/sdk/sessionExchange a diner token or launch code for a session
DELETE /api/v1/sdk/sessionEnd the diner's session (they logged out)
GET /api/v1/menuThe menu the waiter serves at a branch and service mode
GET /api/v1/waiterThe waiter's public face at a branch and service mode
POST /api/v1/chatSend the diner's message and stream the waiter's reply
POST /api/v1/chat/warmupPrime the waiter before the diner's first message
GET /api/v1/conversationsThe diner's recent conversations
GET /api/v1/conversations/{conversationId}One of the diner's conversations, with its messages
POST /api/v1/conversations/{conversationId}/closeClose a conversation so the next message starts afresh
POST /api/v1/transcribeTurn the diner's voice note into text
POST /api/v1/cart/matchMatch the app's cart to the dishes the waiter serves
GET /api/v1/usualThe diner's usual here, or their last order
GET /api/v1/tableWhether the diner may send an order, and their rounds
POST /api/v1/tableSeat the diner at the table they scanned
POST /api/v1/table/ordersSend the diner's order to the team
GET /api/v1/pickup/optionsWhere and when the diner can collect a pickup
GET /api/v1/pickup/ordersThe diner's pickups, newest first
POST /api/v1/pickup/ordersPlace the diner's pickup
GET /api/v1/goalThe nutrition goal Tamr keeps for the diner
PUT /api/v1/goalSet or clear the diner's nutrition goal
GET /api/v1/pay/optionsWhether the diner can pay with Tamr Pay here, and how
POST /api/v1/payStart paying the table's tab or an amount
GET /api/v1/pay/{paymentId}Where one of the diner's payments stands
POST /api/v1/reviews/matchWhich of an order's dishes the diner can rate
POST /api/v1/reviewsRate an order's dishes, one review per dish per order

The client library

@tamr/api is a typed client generated from the same spec, with no runtime dependencies, for Node 20+ and every current browser: createServerClient (from @tamr/api/server) for the Server API and createClient for the Client API. The Node examples on every page use it.

npm install @tamr/api

A refusal throws a TamrApiError with status, code (the stable data.code, or network when Tamr wasn't reached), requestId, retryAfter and data. Every call takes a last, optional { signal } to stop it.

The spec

The OpenAPI 3.1 document is served at tamr.link/api/v1/openapi.json. Every operation, every schema and every webhook payload is in it. Values in lists marked open carry an x-fallback: read a value you don't know as that fallback.

Versioning

/api/v1 only grows: new routes, new optional fields, new event types and card kinds, and new values in open lists. Nothing is removed or narrowed in v1, and CI compares every change to the spec with the published one to hold it to that. A breaking change would be /api/v2, run beside v1 for at least six months. Build your client to ignore fields and events it doesn't know.