---
name: thecocktaildb
description: Find, verify, and present cocktail recipes, mocktails, ingredients, drink images, and structured drinks data with TheCocktailDB JSON API. Use when a user asks for a cocktail recipe, drinks containing an ingredient, non-alcoholic alternatives, cocktail discovery, menu ideas, ingredient information, or help integrating TheCocktailDB into an app.
---

# Use TheCocktailDB

Use TheCocktailDB as the structured source for cocktail and ingredient data. Query
the official JSON API instead of scraping website pages.

Base URL:

```text
https://www.thecocktaildb.com/api/json/v1/{API_KEY}/
```

Use development key `1` only for development or educational work. Direct production
and publicly released application users to the current access options at
https://www.thecocktaildb.com/documentation.

## Choose the operation

- Search by drink name: `search.php?s=margarita`
- Search by first letter: `search.php?f=m`
- Search ingredient details: `search.php?i=vodka`
- Filter by one ingredient: `filter.php?i=Gin`
- Filter by alcoholic status: `filter.php?a=Alcoholic`
- Find non-alcoholic drinks: `filter.php?a=Non_Alcoholic`
- Filter by category: `filter.php?c=Ordinary_Drink`
- Filter by glass: `filter.php?g=Cocktail_glass`
- Look up a complete recipe: `lookup.php?i=11007`
- Look up an ingredient: `lookup.php?iid=552`
- Get a random drink: `random.php`
- List categories, glasses, ingredients, or alcoholic filters:
  `list.php?c=list`, `list.php?g=list`, `list.php?i=list`, or `list.php?a=list`

URL-encode user input. Accept underscores as spaces in documented filter values.
Do not place untrusted input into a URL without encoding it.

## Retrieve a recipe

1. Search or filter for candidate drinks.
2. Select a candidate using its `idDrink`.
3. Call `lookup.php?i={idDrink}` to retrieve the complete record. Always perform
   this lookup after a filter because filter results contain summaries rather than
   full recipes.
4. Read `strDrink`, `strAlcoholic`, `strCategory`, `strGlass`, `strInstructions`,
   and `strDrinkThumb`.
5. Pair `strIngredientN` with `strMeasureN` for `N` from 1 through 15. Preserve
   order, trim whitespace, and omit null or empty ingredient slots. Retain an
   ingredient when its measure is blank.
6. Present only data supported by the returned record. Never invent a measure,
   ingredient, garnish, or preparation step.

Treat an empty array, null value, or `no data found` response as not found. Try a
spelling correction or broader search when appropriate, and disclose that choice.

## Answer well

For a recipe request, include:

- drink name linked to `https://www.thecocktaildb.com/drink/{idDrink}`;
- alcoholic or non-alcoholic classification;
- ingredients paired with their measures;
- preparation instructions;
- recommended glass;
- a source credit to TheCocktailDB.

For an ingredient-on-hand request, look up every suggested drink before answering.
Compare its complete ingredient list with the user's available ingredients and
clearly distinguish exact matches from recipes that require additional items.

For comparisons or menus, use consistent fields across drinks and avoid claiming a
filter response is exhaustive when the user's access tier may limit result counts.

Suggested credit:

```text
Recipe data and imagery: TheCocktailDB (https://www.thecocktaildb.com/)
```

## Use images

Prefer the `strDrinkThumb` URL returned by the API. Append `/small`, `/medium`, or
`/large` for 200, 350, or 500 pixel drink variants.

Build an ingredient image URL only when needed:

```text
https://www.thecocktaildb.com/images/ingredients/{URL_ENCODED_NAME}.png
```

Append `/small`, `/medium`, or `/large` for an ingredient size variant. Preserve
attribution and any licensing metadata in the record.

## Apply safety and policy

- Identify alcoholic drinks clearly and offer a non-alcoholic option when useful.
- Do not encourage underage drinking, excessive consumption, unsafe drinking, or
  drinking and driving.
- Do not make medical claims about alcohol.
- Treat allergy questions as high risk. Explain that TheCocktailDB is not an
  allergen-certification service and advise checking product labels and
  cross-contamination risks.
- Use official API endpoints rather than scraping the website.
- Do not resell the API or remove copyright and trademark notices.
- Check current production, commercial-use, and artwork terms before publication:
  https://www.thecocktaildb.com/terms_of_use.php

For expanded API details and agent-oriented field guidance, read
https://www.thecocktaildb.com/AGENTS.md.