Food and fitness · TheMealDB

recipes.search

Searches recipes by one supported query or filter, then retrieves ingredients, measures and instructions from the source. On update, supplying one query, ingredient, category or cuisine replaces the previous selector while preserving num unless changed. Multiple selectors cannot be combined. Nutrition, allergy safety and storage suitability are not inferred when the source does not provide them.

Operation: POST /v1/capabilities/recipes.search/execute
operationId: executeRecipesSearch
Typical credits: 0
Search deadline: 15 s server-side
Paging: local
Availability: UnavailableChecked 2026-09-23 21:02 UTC

Cost basis: Commercial provider subscription; no per-request allocation is charged until a usage price is configured. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/recipes.search/execute, JSON, validated against the RecipesSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of recipes.search
Field	Type	Required	Default	Constraints and description
query	string	no		min length 1, max length 120
ingredient	string	no		min length 1, max length 120
category	string	no		min length 1, max length 120
cuisine	string	no		min length 1, max length 120
num	integer	no	10	min 1, max 20

Choose exactly one recipe name query, ingredient, category or cuisine (TheMealDB area). Filters cannot be combined.
Exactly one of query, ingredient, category, cuisine is required.
Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

Exactly one of query, ingredient, category or cuisine; blank filters are refused.

Examples

Dinner ideas

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/recipes.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"chicken","num":5}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the RecipesSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of recipes.search
Key	Type	Presence
category	string	when the source has it
cuisine	string	when the source has it
attribution	string	always

Follow-ups

Paging: Whole result set held in the session; more is served locally and costs nothing. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.
Update: Re-run the recipe search. One supplied query, ingredient, category or cuisine replaces the previous selector; num is preserved unless changed. Empty params refresh the current search. Params accept any subset of the request fields (RecipesSearchUpdateParams). One supplied query, ingredient, category or cuisine replaces the previous selector; num is preserved unless changed. Empty params refresh the current search.
Record actions:
- details: Recipe ingredients, measures, instructions and source links.
Detail behaviour: Stored at search time; details is free and never calls the provider. details returns the stored recipe; a missing record is looked up again at no charge.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/recipes.search/execute", {
  body: {
    "query": "chicken",
    "num": 5
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);