# 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.

Source: https://tamr.link/docs/api

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 API | Client API |
| --- | --- | --- |
| Who calls it | Your backend | The waiter page, or your app if it [draws its own chat](https://tamr.link/docs/guides/custom-chat) |
| Credentials | A secret API key: `Authorization: Bearer <key>` | Your publishable key in `x-tamr-key` and the diner's session in `x-tamr-session` |
| From a browser | Never: no Server API route answers a browser | Only from an origin listed on the key |
| Limits | 100 requests a minute per secret key | See [rate limits](https://tamr.link/docs/errors#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 dashboard | Scope | Lets your backend |
| --- | --- | --- |
| Diner sessions (SDK) | `diner:sdk` | Create launch codes, erase a user |
| Catalog ids (SDK) | `catalog:sdk` | Set your product ids and nutrition figures |
| Orders (SDK) | `orders:sdk` | Send your orders, redeem treats |
| Menu read (SDK) | `catalog:read` | Read 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](https://tamr.link/docs/keys).

## Every route

### Server API

Your backend, with a secret API key.

| Endpoint | What it does |
| --- | --- |
| [`POST /api/v1/sdk/launch-codes`](https://tamr.link/docs/api/create-launch-code) | Mint a one-time launch code for one of your users |
| [`DELETE /api/v1/sdk/users/{externalUserId}`](https://tamr.link/docs/api/erase-user) | Erase what Tamr holds for one of your users |
| [`POST /api/v1/sdk/orders`](https://tamr.link/docs/api/send-order) | Send an order your own checkout placed |
| [`POST /api/v1/sdk/treats/{treatId}/redeem`](https://tamr.link/docs/api/redeem-treat) | Redeem a treat your checkout gave at zero |
| [`PUT /api/v1/catalog/external-ids`](https://tamr.link/docs/api/set-external-ids) | Set your ids for the restaurant's dishes, sizes and options |
| [`PUT /api/v1/catalog/nutrition`](https://tamr.link/docs/api/set-nutrition) | Set your own nutrition figures for the restaurant's dishes |
| [`GET /api/v1/catalog/menu`](https://tamr.link/docs/api/get-catalog-menu) | Read one of the restaurant's published menus |

### Client API

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

| Endpoint | What it does |
| --- | --- |
| [`POST /api/v1/sdk/session`](https://tamr.link/docs/api/start-session) | Exchange a diner token or launch code for a session |
| [`DELETE /api/v1/sdk/session`](https://tamr.link/docs/api/end-session) | End the diner's session (they logged out) |
| [`GET /api/v1/menu`](https://tamr.link/docs/api/get-menu) | The menu the waiter serves at a branch and service mode |
| [`GET /api/v1/waiter`](https://tamr.link/docs/api/get-waiter) | The waiter's public face at a branch and service mode |
| [`POST /api/v1/chat`](https://tamr.link/docs/api/chat) | Send the diner's message and stream the waiter's reply |
| [`POST /api/v1/chat/warmup`](https://tamr.link/docs/api/warm-up) | Prime the waiter before the diner's first message |
| [`GET /api/v1/conversations`](https://tamr.link/docs/api/list-conversations) | The diner's recent conversations |
| [`GET /api/v1/conversations/{conversationId}`](https://tamr.link/docs/api/get-conversation) | One of the diner's conversations, with its messages |
| [`POST /api/v1/conversations/{conversationId}/close`](https://tamr.link/docs/api/close-conversation) | Close a conversation so the next message starts afresh |
| [`POST /api/v1/transcribe`](https://tamr.link/docs/api/transcribe) | Turn the diner's voice note into text |
| [`POST /api/v1/cart/match`](https://tamr.link/docs/api/match-cart) | Match the app's cart to the dishes the waiter serves |
| [`GET /api/v1/usual`](https://tamr.link/docs/api/get-usual) | The diner's usual here, or their last order |
| [`GET /api/v1/table`](https://tamr.link/docs/api/get-table) | Whether the diner may send an order, and their rounds |
| [`POST /api/v1/table`](https://tamr.link/docs/api/seat-at-table) | Seat the diner at the table they scanned |
| [`POST /api/v1/table/orders`](https://tamr.link/docs/api/send-table-order) | Send the diner's order to the team |
| [`GET /api/v1/pickup/options`](https://tamr.link/docs/api/get-pickup-options) | Where and when the diner can collect a pickup |
| [`GET /api/v1/pickup/orders`](https://tamr.link/docs/api/list-pickups) | The diner's pickups, newest first |
| [`POST /api/v1/pickup/orders`](https://tamr.link/docs/api/place-pickup) | Place the diner's pickup |
| [`GET /api/v1/goal`](https://tamr.link/docs/api/get-goal) | The nutrition goal Tamr keeps for the diner |
| [`PUT /api/v1/goal`](https://tamr.link/docs/api/set-goal) | Set or clear the diner's nutrition goal |
| [`GET /api/v1/pay/options`](https://tamr.link/docs/api/get-pay-options) | Whether the diner can pay with Tamr Pay here, and how |
| [`POST /api/v1/pay`](https://tamr.link/docs/api/start-payment) | Start paying the table's tab or an amount |
| [`GET /api/v1/pay/{paymentId}`](https://tamr.link/docs/api/get-payment) | Where one of the diner's payments stands |
| [`POST /api/v1/reviews/match`](https://tamr.link/docs/api/match-review) | Which of an order's dishes the diner can rate |
| [`POST /api/v1/reviews`](https://tamr.link/docs/api/submit-reviews) | Rate 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.

```sh
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](https://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.
