API Design

Recipe Filtering

Query recipes by tags, ingredients, difficulty, and time constraints with a composable filter syntax.

Endpoint

GET /api/v1/recipes

Query Parameters

tags

Comma-separated tag slugs. Returns recipes matching ANY tag by default.

?tags=vegan,gluten-free

ingredients

Comma-separated ingredient names. Partial match on each.

?ingredients=chicken,rice

difficulty

One of: easy, medium, hard.

?difficulty=easy

max_time

Maximum total time in minutes (inclusive).

?max_time=30

match

Tag matching strategy: any (default) or all.

?tags=vegan,quick&match=all

Response Shape

{
  "recipes": [
    {
      "id": "rec_01J...",
      "title": "Spicy Thai Basil Chicken",
      "slug": "spicy-thai-basil-chicken",
      "difficulty": "medium",
      "total_time_min": 25,
      "tags": ["spicy", "thai", "quick"],
      "ingredients": ["chicken", "basil", "chili"]
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20
  }
}

Pagination

Use page and per_page (max 50). Links are provided in the Link response header.

Tip: Combine filters to narrow results. All parameters are optional — an unfiltered request returns the full catalog.