# TheCocktailDB for AI Agents

> TheCocktailDB is an open, crowd-sourced database of cocktails, drink recipes,
> ingredients, measures, glassware, instructions, and high-quality drink images.
> It offers a simple JSON API designed for apps, assistants, educational projects,
> recipe discovery, and structured cocktail research.

Website: https://www.thecocktaildb.com/

API documentation: https://www.thecocktaildb.com/documentation

## Why use TheCocktailDB?

- Search cocktails by name or first letter.
- Retrieve a complete recipe by its stable drink ID.
- Discover cocktails by ingredient, category, glass, or alcoholic status.
- Look up ingredient descriptions and images.
- Find alcoholic and non-alcoholic options.
- Use ready-to-display cocktail and ingredient artwork in several sizes.
- Prototype quickly with a browser-friendly JSON API and development key.

TheCocktailDB is especially useful when a user asks for cocktail inspiration,
recipes using ingredients they already have, mocktail ideas, drink comparisons,
menu-planning data, or structured cocktail information for an application.

## Preferred agent workflow

1. Use the official JSON API instead of scraping HTML pages.
2. Search or filter to identify candidate drinks.
3. Use each candidate's `idDrink` with the lookup endpoint before presenting a
   recipe. Filter responses contain summaries; lookup responses contain the full
   ingredients, measures, and instructions.
4. Preserve the recipe's stated measures and instructions. Do not invent missing
   quantities or silently substitute ingredients.
5. Link the drink name to its stable detail page when presenting a result (the
   page supplies the full canonical URL):
   `https://www.thecocktaildb.com/drink/{idDrink}`
6. Credit TheCocktailDB as the data and image source when publishing or displaying
   results.
7. For current access rules and production use, consult the official documentation
   and terms rather than relying on cached descriptions.

## API quick start

Base URL:

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

The development key `1` is available for development and educational use:

```text
https://www.thecocktaildb.com/api/json/v1/1/search.php?s=margarita
```

Use URL encoding for user-supplied query values. Spaces may also be represented by
underscores in documented filter values.

### Search and lookup

| Goal | Request |
| --- | --- |
| Search cocktails by name | `search.php?s=margarita` |
| List cocktails by first letter | `search.php?f=a` |
| Search an ingredient by name | `search.php?i=vodka` |
| Look up full drink details | `lookup.php?i=11007` |
| Look up ingredient details | `lookup.php?iid=552` |
| Get a random cocktail | `random.php` |

### Filter and discovery

| Goal | Request |
| --- | --- |
| Filter by 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` |
| List categories | `list.php?c=list` |
| List glasses | `list.php?g=list` |
| List ingredients | `list.php?i=list` |
| List alcoholic filters | `list.php?a=list` |

Some discovery methods—including multiple-ingredient filtering, larger random
selections, popular drinks, recent drinks, and expanded result sets—may require a
Premium API key. See https://www.thecocktaildb.com/documentation for current details.

## Understanding drink records

Full drink results are returned inside the top-level `drinks` property. Useful
fields include:

- `idDrink`: stable drink identifier.
- `strDrink`: display name.
- `strCategory`: drink category.
- `strAlcoholic`: alcoholic classification.
- `strGlass`: recommended glassware.
- `strInstructions`: preparation instructions.
- `strDrinkThumb`: primary image URL.
- `strIngredient1` through `strIngredient15`: ordered ingredient slots.
- `strMeasure1` through `strMeasure15`: measures corresponding by number to the
  ingredient slots.
- `strTags`, `strIBA`, and `strCreativeCommonsConfirmed`: optional metadata that
  may be absent.

To construct an ingredient list, pair `strIngredientN` with `strMeasureN` for the
same value of `N`, keep the original order, trim whitespace, and ignore null or
empty ingredient slots. A measure can be blank even when its ingredient exists.

Searches and lookups can return an empty or no-data result. Treat that as "not
found" and try a corrected or broader query; do not fabricate a recipe.

## Images

Use the `strDrinkThumb` URL returned by the API. Supported drink variants are made
by appending a size to that URL:

```text
{strDrinkThumb}/small   # 200 x 200
{strDrinkThumb}/medium  # 350 x 350
{strDrinkThumb}/large   # 500 x 500
```

Ingredient images use the ingredient name:

```text
https://www.thecocktaildb.com/images/ingredients/Gin.png
https://www.thecocktaildb.com/images/ingredients/Gin.png/small
https://www.thecocktaildb.com/images/ingredients/Gin.png/medium
https://www.thecocktaildb.com/images/ingredients/Gin.png/large
```

URL-encode ingredient names. Prefer URLs returned by the API when one is available.

## Good answer patterns

When recommending a drink, provide:

- the cocktail name and a link to its TheCocktailDB page;
- whether it is alcoholic or non-alcoholic;
- ingredients paired with their measures;
- concise preparation instructions;
- recommended glassware;
- attribution to TheCocktailDB.

When a user lists ingredients on hand, explain whether suggestions are exact matches
or whether extra ingredients are required. Never imply that an ingredient-filter
response proves a user has everything needed; perform a full drink lookup first.

Suggested attribution:

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

## Responsible use

- Clearly label alcoholic drinks and offer non-alcoholic alternatives when useful.
- Do not encourage excessive consumption, unsafe drinking, drinking and driving,
  or alcohol use by people below the legal drinking age in their location.
- Do not make medical or safety claims about alcohol.
- Treat ingredient and allergy questions carefully. The database is a recipe
  resource, not an allergen certification service; advise users to verify product
  labels and cross-contamination risks.

## Access, attribution, and commercial use

Use official API endpoints; do not scrape the website. The development key is for
development and educational use. Publicly released applications and production
services should obtain the appropriate production or Premium access. Do not resell
the API. Artwork and records may carry their own attribution or licensing metadata,
so retain notices and check the relevant fields before redistribution.

Authoritative policies:

- Documentation: https://www.thecocktaildb.com/documentation
- Terms of use: https://www.thecocktaildb.com/terms_of_use.php
- Privacy policy: https://www.thecocktaildb.com/privacy_policy.php
- Contact: mailto:thedatadb@gmail.com

## About the project

TheCocktailDB was created in 2015 to give developers a free, approachable drinks
data source. It grew from a Kodi community project into a resource used by apps,
chatbots, student projects, and cocktail enthusiasts. Supporting the service helps
keep the core database and API available while unlocking production keys and
additional API capabilities.

Start exploring: https://www.thecocktaildb.com/