Mealie · OpenAPI Overlay 1.0.0

API Evangelist enhancements for the Mealie OpenAPI

10 actions 10 updates servers
Derived by API Evangelist Built from the contracts Mealie publishes. Mealie did not publish this file.
View Overlay File View on GitHub Overlay Specification

What the actions change

x-agent-cautionserversx-harvested-fromx-harvested-onx-version-channelx-application-releasex-licensex-source-repository

Targets 9

$
$.info
$.components.securitySchemes
$.paths['/api/recipes/create/url'].post
$.paths['/api/recipes/create/ai'].post
$.paths['/api/recipes/{slug}/image'].post
$.paths['/api/recipes/bulk-actions/delete'].post
$.paths['/api/recipes/{slug}'].delete
$.paths['/api/households/shopping/lists/{item_id}/recipe'].post

OpenAPI Overlay

Raw ↑
overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Mealie OpenAPI
  version: 1.0.0
x-provenance:
  generated: '2026-08-27'
  method: generated
  source: openapi/mealie-openapi.json
  extends: openapi/mealie-openapi.json
  note: >-
    Non-destructive Overlay 1.0.0 capturing this profile's enhancements to the Mealie
    contract. It adds a servers[] block the original omits, records the undeclared
    error responses, flags the three endpoints the project's own security docs single
    out, and marks the destructive operations. The original spec is never mutated.
actions:
- target: $
  description: >-
    The harvested document declares no servers[]. Mealie is self-hosted, so the host
    is a variable the operator supplies; the project's public demo instance is the
    default here.
  update:
    servers:
    - url: https://{host}/api
      description: A Mealie instance. Mealie is self-hosted — substitute your own host.
      variables:
        host:
          default: demo.mealie.io
          description: >-
            The hostname of the Mealie instance. demo.mealie.io is the project's
            public demonstration instance running the nightly build.
- target: $.info
  description: Record the origin of this contract and the fact that it tracks the nightly branch.
  update:
    x-harvested-from: https://demo.mealie.io/openapi.json
    x-harvested-on: '2026-08-27'
    x-version-channel: nightly
    x-application-release: v3.24.0
    x-license: AGPL-3.0
    x-source-repository: https://github.com/mealie-recipes/mealie
- target: $.components.securitySchemes
  description: >-
    Document the long-lived bearer API token the docs tell integrators to use. It is
    accepted by the same handler as the password-flow token but is not declared as a
    scheme in the original document.
  update:
    ApiTokenBearer:
      type: http
      scheme: bearer
      description: >-
        Long-lived API token minted by a user at /user/profile/api-tokens and sent as
        `Authorization: Bearer <token>`. Carries the full permission set of the user
        who created it; there are no scopes.
      x-minted-at: /user/profile/api-tokens
      x-docs: https://docs.mealie.io/documentation/getting-started/api-usage/
- target: $.info
  description: >-
    Record cross-cutting runtime semantics an agent needs and the contract does not
    state.
  update:
    x-conventions:
      pagination:
        request: {page: integer, perPage: 'integer (-1 returns all)'}
        response: [page, per_page, total, total_pages, items, next, previous]
        warning: >-
          Request params are camelCase, the response envelope is snake_case, and
          next/previous are relative paths without the base URL.
      filtering:
        param: queryFilter
        grammar: SQL-like expression string with AND/OR, parentheses, IN, LIKE, IS NULL, CONTAINS ALL and a $NOW placeholder
        docs: https://docs.mealie.io/documentation/getting-started/api-usage/
      idempotency:
        supported: false
        warning: No Idempotency-Key. Retrying a POST create produces a duplicate.
      rate_limiting:
        supported: false
        docs: https://docs.mealie.io/documentation/getting-started/installation/security/
      undeclared_error_statuses: ['401', '403', '404', '409', '500']
- target: $.paths['/api/recipes/create/url'].post
  description: The project's own security documentation flags this endpoint for SSRF and DoS.
  update:
    x-agent-caution:
      classes: [ssrf, denial-of-service]
      consequence: external-fetch
      source: https://docs.mealie.io/documentation/getting-started/installation/security/
      note: >-
        Fetches an arbitrary caller-supplied URL from the server. Mealie recommends
        strict reverse-proxy rate limits on this path.
- target: $.paths['/api/recipes/create/ai'].post
  description: The project's own security documentation flags this endpoint for SSRF, DoS and AI spend.
  update:
    x-agent-caution:
      classes: [ssrf, denial-of-service, cost]
      consequence: external-fetch-and-billable
      source: https://docs.mealie.io/documentation/getting-started/installation/security/
- target: $.paths['/api/recipes/{slug}/image'].post
  description: The project's own security documentation flags this endpoint for SSRF and DoS.
  update:
    x-agent-caution:
      classes: [ssrf, denial-of-service]
      consequence: external-fetch
      source: https://docs.mealie.io/documentation/getting-started/installation/security/
- target: $.paths['/api/recipes/bulk-actions/delete'].post
  description: Mark the most destructive operation in the API as irreversible.
  update:
    x-agent-caution:
      classes: [destructive]
      consequence: irreversible-bulk-delete
      reversal: none
      note: >-
        No undo and no trash. The only recovery is an admin restore of the entire
        database from a backup, which also reverts every other change since.
- target: $.paths['/api/recipes/{slug}'].delete
  description: Mark recipe deletion as irreversible.
  update:
    x-agent-caution:
      classes: [destructive]
      consequence: irreversible-delete
      reversal: none
- target: $.paths['/api/households/shopping/lists/{item_id}/recipe'].post
  description: Record the paired reverse operation.
  update:
    x-reversal:
      operationId: remove_recipe_ingredients_from_list_api_households_shopping_lists__item_id__recipe__recipe_id__delete_post
      window: null

Work with this as data

Every overlay here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for openapi overlays

4 MCP tools reach this
  • find_overlaysBrowse and filter every overlay in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This overlay
curl "https://apis.io/api/v1/overlays/mealie-openapi-overlay"
All openapi overlays
curl "https://apis.io/api/v1/overlays?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.