# Get the menu

> Read the menu the AI waiter serves at a branch and service mode, with Tamr's ids for every dish, size and option.

Source: https://tamr.link/docs/api/get-menu

`GET https://tamr.link/api/v1/menu`

The menu the waiter serves at a branch and in a service mode: categories and dishes with prices in minor units, images, allergens, nutrition figures and Tamr's ids for each dish, size and option.

## Authentication

**Client API.** Send your publishable key in `x-tamr-key` and the diner's session in `x-tamr-session`, from [Start a session](https://tamr.link/docs/api/start-session). For a guest's session, also send its device id in `x-tamr-device`. A browser may call it only from an origin listed on the key.

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `branch` | string | No | An address: lower-case letters, digits and dashes. |
| `mode` | string | No | One of `dine_in`, `pickup`, `delivery`. |

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `x-tamr-device` | string | No | Guest sessions only: the device id the session was exchanged with. Matches `^[A-Za-z0-9_-]{8,128}$`. |
| `x-tamr-app` | string | No | Native apps only: the app's iOS bundle id or Android package name. A key used from an app it doesn't list is logged, never refused. Matches `^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)+$`. |

## Response

A [MenuResponse](https://tamr.link/docs/api/schemas#menuresponse).

| Field | Type | Description |
| --- | --- | --- |
| `menu` | object |  |
| `menu.name` | string | 1 to 200 characters. |
| `menu.locale` | string | A language tag, such as `ar` or `en-GB`. |
| `menu.currency` | string | A three-letter currency code (ISO 4217). |
| `categories` | array of object |  |
| `categories[].name` | string | 1 to 200 characters. |
| `categories[].dishes` | array of object |  |
| `categories[].dishes[].dishId` | string | 1 to 200 characters. |
| `categories[].dishes[].name` | string | 1 to 200 characters. |
| `categories[].dishes[].price` | string | An amount in minor units, as a string. |
| `categories[].dishes[].currency` | string | A three-letter currency code (ISO 4217). |
| `categories[].dishes[].imageUrl` | string or null | Matches `^https:\/\/[^\s]+$`. |
| `categories[].dishes[].calories` | integer or null | 0 to 9,007,199,254,740,991. |
| `categories[].dishes[].proteinGrams` | integer or null | 0 to 9,007,199,254,740,991. |
| `categories[].dishes[].carbsGrams` | integer or null | 0 to 9,007,199,254,740,991. |
| `categories[].dishes[].fatGrams` | integer or null | 0 to 9,007,199,254,740,991. |
| `categories[].dishes[].allergens` | array of string | At most 10 items. Each: One of `gluten`, `dairy`, `egg`, `nuts`, `sesame`, `soy`, `fish`, `shellfish`, `peanut`, `mustard`. |
| `categories[].dishes[].dietaryTags` | array of string | At most 11 items. Each: One of `vegan`, `vegetarian`, `gluten_free`, `halal`, `kosher`, `dairy_free`, `nut_free`, `keto`, `spicy`, `high_protein`, `other`. An open list: read a value you don't know as `other`. |
| `categories[].dishes[].available` | boolean |  |
| `categories[].dishes[].externalId` | string or null | 1 to 200 characters. |
| `categories[].dishes[].description` | string or null | At most 2,000 characters. |
| `categories[].dishes[].sizes` | array of object |  |
| `categories[].dishes[].choices` | array of object |  |

## Example

curl:

```bash
curl "https://tamr.link/api/v1/menu?branch=achrafieh&mode=dine_in" \
  -H "x-tamr-key: $TAMR_APP_KEY" \
  -H "x-tamr-session: $TAMR_SESSION"
```

Node:

```js
import { createClient } from "@tamr/api";

const tamr = createClient({ appKey: process.env.TAMR_APP_KEY });
// Sign the diner in first, with a token your backend signed (or a launch code).
await tamr.startSession({ token: dinerToken });

const result = await tamr.menu({ branch: "achrafieh", mode: "dine_in" });
console.log(result);
```

Python:

```python
import os

import requests

API = "https://tamr.link/api/v1"
headers = {
    "x-tamr-key": os.environ["TAMR_APP_KEY"],
    "x-tamr-session": os.environ["TAMR_SESSION"],  # from POST /api/v1/sdk/session
}

response = requests.get(
    f"{API}/menu",
    headers=headers,
    params={"branch": "achrafieh", "mode": "dine_in"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

## Example response

```json
{
  "menu": {
    "name": "Dinner",
    "locale": "en",
    "currency": "USD"
  },
  "categories": [
    {
      "name": "Mezze",
      "dishes": [
        {
          "dishId": "cmdish0001",
          "name": "Grilled halloumi",
          "price": "1200",
          "currency": "USD",
          "imageUrl": "https://tamr.link/image-proxy/media/halloumi.webp",
          "calories": 420,
          "proteinGrams": 24,
          "carbsGrams": 8,
          "fatGrams": 31,
          "allergens": [
            "dairy"
          ],
          "dietaryTags": [
            "vegetarian"
          ],
          "available": true,
          "externalId": "SKU-HALLOUMI",
          "description": "Grilled, with za'atar.",
          "sizes": [
            {
              "variantId": "9b1c2d3e-0001",
              "label": "Large",
              "price": "1600",
              "externalId": null
            }
          ],
          "choices": [
            {
              "name": "Sauce",
              "min": 0,
              "max": 1,
              "options": [
                {
                  "optionId": "9b1c2d3e-0002",
                  "name": "Garlic",
                  "price": null,
                  "extra": "150",
                  "calories": 90,
                  "proteinGrams": 1,
                  "carbsGrams": 2,
                  "fatGrams": 9,
                  "allergens": [],
                  "externalId": null
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

## Errors

Every error has the same body; switch on `data.code`. See [Errors and rate limits](https://tamr.link/docs/errors).

| `data.code` | Status | What to do |
| --- | --- | --- |
| `app_key_invalid` | 401 | The key is wrong, revoked or of another kind. Check it in the dashboard. |
| `sdk_disabled` | 403 | The SDK isn't switched on for this restaurant. Ask Tamr. |
| `origin_not_allowed` | 403 | A browser called from an origin the key doesn't list. Add the origin to the key. |
| `session_expired` | 401 | Start a new session with a fresh token or code, then send the call again once. |
| `invalid_request` | 400 | A field doesn't match the spec. The message says which. |
| `rate_limited` | 429 | Wait `retryAfter` seconds (also in the `Retry-After` header), then try again. |
| `menu_unavailable` | 404 | No published menu is served at that branch and service mode. |
