# Read a menu from your backend

> Read one of the restaurant's published menus from your server, with prices, sizes, choices, availability, your product ids and the menu's version, to keep your own catalog in step with Tamr.

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

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

One published menu, for a backend that keeps Tamr as the source of truth for its menu and prices. The dishes are exactly what [Get the menu](https://tamr.link/docs/api/get-menu) gives your app at that branch and mode: prices in minor units, sizes, choices, what is on sale now on the branch's clock, and your ids, a branch's own winning over the chain-wide one. With them, the menu's `menuId`, `menuSlug`, the service `modes` it covers, and its `version`.

- Name a `branch` and a `mode` for the menu the waiter serves there, or a `menu` by its id or slug (with a `branch`, the dishes are read at that branch). With neither, the restaurant's default menu.
- `version` grows by one each time what diners see on the menu changes, and the [`menu.changed`](https://tamr.link/docs/webhooks/menu-changed) webhook carries it. Your ids and a sold-out dish coming back on sale don't move it: `menu.changed` still tells you.
- The answer carries an `ETag`. Send it back in `If-None-Match` and Tamr answers `304 Not Modified` with no body while nothing changed. See [Keep your app in step](https://tamr.link/docs/guides/keeping-in-step).

The dishes exactly as GET /api/v1/menu lists them at that branch and mode, with the menu's ids and the version Tamr recorded. Send the ETag back in If-None-Match to get a 304 when nothing changed.

## Authentication

**Server API.** Send a secret API key with the **Menu read (SDK)** permission (`catalog:read`) as `Authorization: Bearer <key>`. Secret keys are made in **Settings > API keys** by an owner or admin. Keep them on your server: no browser can call this route.

## 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`. |
| `menu` | string | No | 1 to 200 characters. |

## Response

A [CatalogMenuResponse](https://tamr.link/docs/api/schemas#catalogmenuresponse).

| Field | Type | Description |
| --- | --- | --- |
| `menu` | object |  |
| `menu.menuId` | string | 1 to 200 characters. |
| `menu.menuSlug` | string | 1 to 200 characters. |
| `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). |
| `menu.modes` | array of string | At most 3 items. Each: One of `dine_in`, `pickup`, `delivery`. |
| `menu.branch` | string or null | An address: lower-case letters, digits and dashes. |
| `menu.version` | integer | 0 to 9,007,199,254,740,991. |
| `menu.updatedAt` | string (date-time) |  |
| `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 |  |

The `ETag` response header: The menu's version and a hash of the body. Send it back in If-None-Match: the answer is then a 304 with no body while nothing changed.

## Example

curl:

```bash
curl "https://tamr.link/api/v1/catalog/menu?branch=achrafieh&mode=delivery" \
  -H "Authorization: Bearer $TAMR_SECRET_KEY"
```

Node:

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

const tamr = createServerClient({ secretKey: process.env.TAMR_SECRET_KEY });

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

Python:

```python
import os

import requests

API = "https://tamr.link/api/v1"
headers = {"Authorization": f"Bearer {os.environ['TAMR_SECRET_KEY']}"}

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

## Example response

```json
{
  "menu": {
    "menuId": "cmmenu0001",
    "menuSlug": "dinner",
    "name": "Dinner",
    "locale": "en",
    "currency": "USD",
    "modes": [
      "dine_in",
      "pickup",
      "delivery"
    ],
    "branch": "achrafieh",
    "version": 42,
    "updatedAt": "2026-11-16T09:30:00.000Z"
  },
  "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 |
| --- | --- | --- |
| `other` | 401 | No secret key, or one Tamr doesn't accept: wrong, revoked, or made by someone who is no longer an owner or admin. |
| `other` | 403 | The key doesn't have the `catalog:read` permission. |
| `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. |
| `sdk_disabled` | 403 | The SDK isn't switched on for this restaurant. Ask Tamr. |
| `menu_unavailable` | 404 | No published menu is served at that branch and service mode. |
