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.
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
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.
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.