API Reference

The Recipe API v1 provides read-only access to a collection of over 50,000 recipes and ingredients. All endpoints require authentication via API key.

Base URL

https://recipeapi.io/api/v1

Authentication

All API requests must include your API key using one of the following methods:

Bearer token (recommended)

curl "https://recipeapi.io/api/v1/recipes" \
  -H "Authorization: Bearer sk_live_..."

X-API-Key header

curl "https://recipeapi.io/api/v1/recipes" \
  -H "X-API-Key: sk_live_..."

Query parameter

curl "https://recipeapi.io/api/v1/recipes?apikey=sk_live_..."

You can generate an API key from your Dashboard after creating an account. All paid plans include a 10-day free trial.

Error Response (401)

{
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Invalid or missing API key. Pass your key via Authorization: Bearer sk_live_..., X-API-Key header, or ?apikey= query parameter."
    }
}

Rate Limiting

All plans are limited to 10 requests per second per user. Exceeding this limit returns a 429 status code:

{
    "error": {
        "code": "RATE_LIMIT",
        "message": "Too many requests. Please retry after some time."
    }
}

Monthly Usage Limits

Each plan has a maximum number of requests per calendar month:

Plan	Price/month	Requests/month	Max per_page
Free	$0	500	10
Essential	$29.99	50,000	25
Business	$99.99	300,000	50
Enterprise	$249.99	1,000,000	100

When you exceed your monthly limit, the API returns a 429 status code:

{
    "error": {
        "code": "USAGE_LIMIT_EXCEEDED",
        "message": "Monthly API usage limit exceeded. Upgrade your plan for more requests."
    }
}

Response Format

Success (List)

Paginated list responses use the following envelope:

{
    "data": [
        {
            "..."
        },
        {
            "..."
        },
        "..."
    ],
    "links": {
        "first": "https://recipeapi.io/api/v1/recipes?page=1",
        "last": "https://recipeapi.io/api/v1/recipes?page=50",
        "prev": null,
        "next": "https://recipeapi.io/api/v1/recipes?page=2"
    },
    "meta": {
        "current_page": 1,
        "last_page": 50,
        "path": "https://recipeapi.io/api/v1/recipes",
        "per_page": 10,
        "total": 500,
        "language": "en"
    }
}

Success (Detail)

Single resource responses:

{
    "data": {
        "id": 1,
        "name": "Spaghetti Carbonara",
        "...": "..."
    },
    "meta": {
        "language": "en"
    }
}

Error

{
    "error": {
        "code": "NOT_FOUND",
        "message": "The requested resource was not found."
    }
}

Pagination

All list endpoints support pagination with these query parameters:

Parameter	Default	Description
page	1	Page number
per_page	10	Items per page (max depends on your plan)

The maximum value for per_page depends on your subscription:

Plan	Max per_page
Free	10
Essential	25
Business	50
Enterprise	100

Values above your plan's limit are automatically capped. For example, a Free plan user requesting per_page=50 will receive 10 results per page.

Want more results per page?

Upgrade your plan to increase your per_page limit and unlock higher rate limits. View pricing →

Localization

Paid feature

Languages other than English require a paid plan. Free plan users who pass lang with a value other than en will receive a 402 error.

Upgrade to unlock translations →

The API supports multiple languages for recipe content (name, description, instructions). Use the lang query parameter on any endpoint to get translated content:

GET /api/v1/recipes?lang=fr
GET /api/v1/recipes/42?lang=es

Supported languages

Code	Language
en	English (default)
fr	French
es	Spanish

How it works

• The meta.language field in every response indicates the requested language
• Search (search parameter) matches in both the requested language and English to ensure no results are missed
• Passing an unsupported language returns a 422 error:

{
    "error": {
        "code": "UNSUPPORTED_LANGUAGE",
        "message": "The language 'xx' is not supported.",
        "supported_languages": [
            "en",
            "fr",
            "es"
        ]
    }
}

• Free plan users passing lang (other than en) receive a 402 error:

{
    "error": {
        "code": "PLAN_FEATURE_UNAVAILABLE",
        "message": "Language selection is not available on the Free plan. Please upgrade to use the lang parameter."
    }
}

Example

curl "https://recipeapi.io/api/v1/recipes?lang=fr&search=poulet" \
  -H "Authorization: Bearer sk_live_..."

{
    "data": [
        {
            "id": 42,
            "name": "Poulet Tikka Masala",
            "description": "Un plat indien épicé et crémeux.",
            "instructions": [
                "Faire mariner le poulet...",
                "Préparer la sauce..."
            ],
            "..."
        }
    ],
    "links": {
        "first": "https://recipeapi.io/api/v1/recipes?lang=fr&search=poulet&page=1",
        "last": "https://recipeapi.io/api/v1/recipes?lang=fr&search=poulet&page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "path": "https://recipeapi.io/api/v1/recipes",
        "per_page": 10,
        "total": 1,
        "language": "fr"
    }
}

Query Builder

Don't want to write code yet? Use the interactive Query Builder in your Dashboard to visually build requests, apply filters, and preview results as formatted cards or raw JSON.

The Query Builder supports all endpoints listed below with their full set of filters.

Endpoints Overview

Method	Endpoint	Description
GET	/recipes	List recipes with filters
GET	/recipes/random	Get a random recipe
GET	/recipes/{id}	Get recipe details
GET	/ingredients	List ingredients
GET	/ingredients/{id}	Get ingredient details

tip

You can also filter recipes by ingredients using the ingredients query parameter on the /recipes endpoint. For example: /recipes?ingredients=tomato,basil