> 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/procure-wizard-evo-recipes-api.md). # Procure Wizard Evo Recipes API ## Introduction Access Procure Wizard Evo Recipes is a recipe and menu management solution designed for Hospitality. The API allows third party solutions to interrogate the data held in a customers system for use in situations such as online menus, labelling, data analysis and emissions calculation. The documentation on the following pages outlines the different endpoints and data available via this API, as well as details on authentication, pagination and error handling. 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 %} #### Example Integration types | Integration type | What it does | Minimum requirement | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Data extraction** | Reads the recipe catalogue, product 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 recipe definition including ingredients, health and compliance data and method/informational data. | | **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 UK/EU 14 major allergens convention. | | **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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.hos.accessacloud.com/evo-recipes-api/procure-wizard-evo-recipes-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.