---
title: "Read a menu"
method: POST
path: "/menus"
tags: ["Menus"]
---

# Read a menu

`POST /menus`

## Request

- Base URL: `https://api.layout.link/v1`
- URL: `https://api.layout.link/v1/menus`
- Auth: HTTP bearer

The restaurant's menu, read from its own site: a whole menu Layout read within the last 30 days when it holds one (`readAt` says when), else a live read. The same read the MCP `menu` tool runs. A first read takes up to a minute, so this answers 202 `reading` with a `menuId` when it is not done; poll GET /menus/{menuId}. Read-only: nothing is built or charged to the person.

## Headers

- `Layout-Version` '2026-10-01'
- `Idempotency-Key` string

## Request body

- MenuRequest
  - `placeId` string
  - `query` string: A restaurant name.
  - `near` string: Where, in the person's words.
  - `lat` number
  - `lng` number
  - `category` string: One menu section, from a `categories` answer.
  - `mode` 'live' | 'knowledge': `live` (default) reads the restaurant's own site. `knowledge` answers from general knowledge, labeled `live: false`, and opens nothing.
  - `intent` string: The person's own request, for a knowledge answer.

## Response `200`

An answer: a menu, its sections, a labeled knowledge answer, or why there is none.

- union
  - object
    - `status` 'menu', required
    - `restaurant` MenuRestaurant, required
      - `name` string, required
      - `address` string, nullable, required
    - `assumedNearest` boolean, required: True when the name matched several branches and Layout read the nearest one. Tell the person which.
    - `items` MenuItem[], required
      - `name` string, required
      - `image` ItemImage
        - `url` string, required: A JPEG, up to 1000px on its long side, served from Layout's CDN. Show this URL; do not copy the file.
        - `webpUrl` string, required: The same photo as WebP, smaller.
        - `width` integer, nullable, required
        - `height` integer, nullable, required
        - `source` 'menu' | 'product_page', required: `menu`: from the restaurant's own menu. `product_page`: from its own page for the item.
        - `checkedAt` string, nullable, required: When Layout last checked the photo against the restaurant's site (ISO 8601).
      - `priceMinor` integer: Minor units. 429 is $4.29. Absent when the site did not give one.
      - `description` string
      - `category` string
      - `optionGroups` MenuOptionGroup[]: Absent: not read. Empty: read, and the item needs no choices.
        - `name` string, required
        - `required` boolean, required
        - `options` string[], required
        - `moreOptions` integer: Options beyond the ones listed.
    - `confidence` 'high' | 'partial', required: `partial`: this may not be the whole menu.
    - `pricesUnavailable` boolean, required: The site gave no prices when it was read. Never fill one in.
    - `scope` 'chain': `chain`: this location's own menu could not be read, so these are the items at least half of the restaurant's read locations list. Never priced (`pricesUnavailable` is true, since prices vary by location), and this location may not carry every item. Absent: this location's own menu.
    - `readAt` string, date-time: When Layout read this whole menu from the site, for a menu served from that read rather than read just now. Absent: read just now.
  - object
    - `status` 'categories', required
    - `restaurant` MenuRestaurant, required
      - `name` string, required
      - `address` string, nullable, required
    - `assumedNearest` boolean, required: True when the name matched several branches and Layout read the nearest one. Tell the person which.
    - `categories` string[], required: Read one by sending it back as `category`.
  - object
    - `status` 'reading', required
    - `menuId` string, required
    - `restaurant` MenuRestaurant, required
      - `name` string, required
      - `address` string, nullable, required
    - `assumedNearest` boolean, required: True when the name matched several branches and Layout read the nearest one. Tell the person which.
    - `retryAfterSec` integer, required: When to poll GET /menus/{menuId}.
  - object
    - `status` 'knowledge', required
    - `restaurant` MenuRestaurant
      - `name` string, required
      - `address` string, nullable, required
    - `knowledge` string, required: General knowledge, not the live menu. Prices are not current.
    - `live` false, required
  - object
    - `status` 'unreadable', required
    - `restaurant` MenuRestaurant
      - `name` string, required
      - `address` string, nullable, required
  - object
    - `status` 'not_found', required
  - object
    - `status` 'needs_location', required
    - `candidates` object[], required: Send one back as `placeId`. Empty: send `near` or coordinates.
      - `placeId` string, required
      - `name` string, required
      - `address` string, required
      - `distanceMi` number, nullable, required

## Other responses

- `202`: The read is in flight. Poll GET /menus/{menuId}.
- `400`: The body is invalid. The message names the field. `unsupported_version`: the Layout-Version header names no version this API answers.
- `401`: The token is missing, expired, revoked, issued for another audience, or the person disconnected. Every 401 reads the same.
- `403`: The credential is real and may not do this: an application or account that is suspended, a live person on an unapproved application, a scope the token was not granted, or a person whose Layout account cannot order yet.
- `404`: No place with that placeId.
- `409`: `idempotency_conflict`: the Idempotency-Key was already used with a different request. `in_progress`: the first request with that key is still running; retry after `Retry-After`.
- `429`: This menu was read moments ago, a per-minute brake, or a daily allowance of live menu reads (the person's, Layout's, or your application's). The message names which.
- `500`: Layout failed to answer. Retry with backoff.
- `503`: Credentials or a dependency could not be checked right now. Retry with backoff.

---

[API](https://skmtc.dev/layout/apis/layout-partner-api.md) · [All operations](https://skmtc.dev/layout/apis/layout-partner-api/llms.txt) · [OpenAPI document](https://skmtc.dev/layout/apis/layout-partner-api/revisions/7ff4ba01bf56?raw)