> For the complete documentation index, see [llms.txt](https://docs.hos.accessacloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hos.accessacloud.com/evo-recipes-api/evo-recipes-api.md). # Evo Recipes API ## Introduction Welcome to the Access Evo Dishes & Recipes API documentation. The API is a machine-to-machine (M2M) REST API fronted by Azure API Management (APIM). It provides read access to an organisation's culinary reference data. This includes recipes, ingredients, suppliers, menus, and allergens. It also supports one write operation. Use it to ingest carbon assessments against a dish. All requests use an OAuth 2.0 client credentials JWT. All responses are JSON. List endpoints use cursor pagination. {% hint style="warning" %} This API is in **beta** (version `0.1`). Endpoint shapes may change between beta releases. Agree a rollout plan with your Access contact before going live. {% endhint %} #### Integration types | Integration type | What it does | Minimum requirement | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Data extraction** | Reads the recipe catalogue, ingredient directory, supplier list, menu hierarchy, and allergen reference data into a warehouse, BI tool, or partner system. | Implement cursor pagination correctly. Follow `next_cursor` until `has_next_page` is `false`. Cache access tokens rather than requesting one per call. | | **Allergen and labelling** | Builds allergen matrices and dish labelling from ingredient allergen associations. | Read `GET /apim/allergens` and each ingredient's `allergens` collection. Honour `YES`, `MAY_CONTAIN`, and `NO` `allergenStatus` values. | | **Carbon and sustainability** | Writes a carbon assessment against a dish's current recipe version. | Send `externalStatus` with every payload. Treat re-sends as idempotent. Handle `409` when a dish has no current recipe version. | #### Terminology | Term | Meaning | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Organisation (tenant)** | The Access Evo workspace that owns the data. Every response is scoped to the organisation resolved from your access token. You never pass an organisation identifier. | | **Recipe** | A dish definition. It holds stable attributes and points to a current recipe version. | | **Recipe version** | A numbered, status-tracked recipe snapshot. Statuses are `DRAFT`, `PENDING_APPROVAL`, `PUBLISHED`, and `ARCHIVED`. It carries yield, timings, currency, target gross profit, and sale price. | | **Dish** | The same entity as a recipe. Carbon requests use `dishId`, which is the Evo recipe `id`. | | **Ingredient** | A purchasable or preparable item with cost, unit, category, allergen associations, and fruit, vegetable, and nut classification for NPM scoring. | | **Supplier** | The vendor an ingredient is bought from. | | **Menu** | A named, currency-scoped collection of menu items. It can be nested beneath a parent menu. Each item can be recipe-backed or ingredient-backed. | | **Allergen** | Reference data following the EU 14 major allergens convention. Records with `tenantId: null` are global. Records with a `tenantId` are custom to your organisation. | | **Carbon assessment** | A My Emissions rating and emissions figures from Procure Wizard. It is stored one-to-one against a recipe version. | | **CUID** | The identifier format for Evo entities, such as `clx1a2b3c4d5e6f7g8h9i0j`. Treat IDs as opaque strings. | | **Cursor** | An opaque, base64-encoded continuation token returned as `next_cursor`. Pass it as `cursor` to fetch the next page. | #### Base URLs | Environment | Base URL | | ----------- | --------------------------------------------------------------------------- | | Production | `https://apim-hospitality-prod-uksouth.azure-api.net/evo/dishes-recipes/v1` | | Staging | `https://apim-hospitality-stg-uksouth.azure-api.net/evo/dishes-recipes/v1` | | Development | `https://apim-hospitality-dev-uksouth.azure-api.net/evo/dishes-recipes/v1` | Build integrations against Development or Staging first. Credentials are issued per environment and are not interchangeable. #### Data encryption All traffic uses HTTPS. We recommend **TLS 1.2 or later**. Support for older TLS versions may be removed. Never send client credentials or access tokens over an unencrypted channel. Never place them in a query string. #### Making a request Pass `access_token` in the `Authorization` header as a bearer token. APIM validates it and resolves your organisation from its claims. No additional identity headers are required. The API returns `401` if the header is missing or the token has expired. ```shell curl "https://apim-hospitality-prod-uksouth.azure-api.net/evo/dishes-recipes/v1/apim/recipes?page_size=2" \ -H "Authorization: Bearer VALID_TOKEN" ``` ```json { "data": [ { "id": "clx1a2b3c4d5e6f7g8h9i0j", "tenantId": "clw9z8y7x6w5v4u3t2s1r0q", "currentVersionId": "clv0a1b2c3d4e5f6g7h8i9j", "name": "Beef Lasagne", "description": "Layered pasta with beef ragu and béchamel", "instructions": null, "imageUrl": null, "servings": "4.00", "status": "PUBLISHED", "approvedBy": "chef@example.com", "approvedAt": "2026-01-14T09:12:04.000Z", "active": true, "isVisible": true, "productType": "FOOD", "sourceSystem": null, "externalId": null, "producedStockProductId": null, "createdAt": "2025-11-02T10:45:00.000Z", "updatedAt": "2026-01-14T09:12:04.000Z", "currentVersion": { "id": "clv0a1b2c3d4e5f6g7h8i9j", "versionNumber": 3, "status": "PUBLISHED", "name": "Beef Lasagne", "servings": "4.00", "prepTime": 25, "cookTime": 45, "currency": "GBP", "targetGP": "70.00", "salePrice": "12.50" }, "tags": [ { "recipeId": "clx1a2b3c4d5e6f7g8h9i0j", "tagId": "clt5t6t7t8t9u0u1u2u3u4", "createdAt": "2025-11-02T10:46:11.000Z", "tenantId": "clw9z8y7x6w5v4u3t2s1r0q", "tag": { "id": "clt5t6t7t8t9u0u1u2u3u4", "name": "Signature", "color": "#4CAF50" } } ] } ], "pagination": { "page_size": 2, "has_next_page": true, "next_cursor": "Y2x4MWEyYjNjNGQ1ZTZmN2c4aDlpMGo=" } } ``` #### Next steps * **Authentication** — obtain, cache, and rotate tokens. * **Paging** — work through large result sets. * **Errors** — resolve status codes and messages. * **Dishes & Recipes API guide** — follow endpoint-by-endpoint workflows. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.hos.accessacloud.com/evo-recipes-api/evo-recipes-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.