# Decent Cocktails API

Read-only cocktail recipes with every ingredient weighed in grams, from published cocktail books, plus Decent's own descriptions, comparisons and alcohol/sugar/acid figures. Free to use; please credit (see below).

- **JSON version of this page:** <https://it.decent.la/cocktails/api/index.json> (Markdown: <https://it.decent.la/cocktails/api/?format=md>)
- **OpenAPI description:** <https://it.decent.la/cocktails/api/openapi.json>
- **Site description for AI agents:** <https://it.decent.la/cocktails/llms.txt>

## Books

| id | Book | Authors | Recipes | Ingredients | Web |
|---|---|---|---|---|---|
| `pdt` | The PDT Cocktail Book: The Complete Bartender's Guide from the Celebrated Speakeasy | Jim Meehan (Sterling Epicure, 2011) | 304 | 441 | <https://it.decent.la/cocktails/pdt/> |
| `deathco` | Death & Co: Modern Classic Cocktails | David Kaplan, Nick Fauchald, Alex Day (Ten Speed Press, 2014) | 477 | 453 | <https://it.decent.la/cocktails/deathco/> |

## Endpoints

All responses are JSON (`application/json; charset=utf-8`), allow cross-origin requests, and include a `license` block. Names in URLs are the exact names, URL-encoded.

| Endpoint | Returns | Example |
|---|---|---|
| `GET /cocktails/api/{book}` | the book: counts, source, licence | <https://it.decent.la/cocktails/api/deathco> |
| `GET /cocktails/api/{book}/recipes?offset=&limit=` | recipe names and links, at most 50 per page, with `next` | <https://it.decent.la/cocktails/api/deathco/recipes?limit=10> |
| `GET /cocktails/api/{book}/recipes/{name}` | one recipe in full | <https://it.decent.la/cocktails/api/deathco/recipes/Naked%20and%20Famous> |
| `GET /cocktails/api/{book}/ingredients?offset=&limit=` | ingredient names and links | <https://it.decent.la/cocktails/api/pdt/ingredients?limit=10> |
| `GET /cocktails/api/{book}/ingredients/{name}` | category, ABV and the cocktails using it | <https://it.decent.la/cocktails/api/pdt/ingredients/Yellow%20Chartreuse> |
| `GET /cocktails/api/{book}/search?q=` | cocktails and ingredients matching `q`, at most 20 each | <https://it.decent.la/cocktails/api/pdt/search?q=mezcal> |

A full recipe gives: `name`, `web_url`, `description`, `ingredients` (each with `name`, `amount` as written, `grams`, `role` such as add/garnish/top/muddle, `category`), `method`, `glass`, `credit` (who created it, and when), `stats` (volume after dilution, ABV, alcohol, sugar, acid, balance), `similar` drinks, `image_url` (an AI-generated illustration), `source_book` (title, authors, publisher, year, ISBN, buy link), `cite_as` and `license`.

## Limits

- 60 requests per minute per IP address; over that you get HTTP 429 with `Retry-After`.
- There is no bulk download. Fetch the recipes you need, one at a time.
- Responses may be cached for an hour.

## Why we can publish these recipes

A recipe's ingredients and amounts are facts, and facts can't be copyrighted. The same goes for a drink's name, its glass and garnish, and who created it and when. The US Copyright Office says this directly: a "mere listing of ingredients" is not protected ([Circular 33](https://www.copyright.gov/circs/circ33.pdf)). Most other countries take the same view. What copyright does protect is the author's own writing: their stories, descriptions and instructions. We haven't reproduced any of that.

This isn't a copy of the books. We rebuilt every recipe as a series of weighed steps: each amount converted to grams, each step labelled (add, muddle, top, garnish), and every method rewritten in our own words. Then we added what the books don't have: alcohol, sugar and acid figures for every drink, comparisons with similar drinks, our own descriptions and drink pictures, and ways to browse by spirit, ingredient and glass. What remains from the books are the facts: drink names, ingredients, amounts, glass, garnish and creator credits. We don't claim to own those facts; nobody can copyright a fact.

We built this because these books are wonderful, and we wanted their drinks to be easy to weigh, compare and make. If you enjoy them, please buy the books. The stories and writing in them are worth having, and you won't find them here.

## Licence and credit

- **Decent's own content** is licensed under [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/) (CC BY 4.0), to the extent Decent Espresso Ltd holds rights in it: the descriptions, comparisons and taste notes, the method wording, the computed figures and the AI-generated drink and glass pictures.
- **The recipe facts** (drink names, ingredients and amounts, glass, garnish and creator credits) come from the books above. They are facts, so Decent claims no rights in them and offers no licence for them. Please buy the books.
- Third-party product photographs, label artwork and trademarks are not covered. Some drink names are also trademarks (Sazerac, for example); they belong to their owners and are used here only to name the drink.
- **How to credit:** name "Decent Cocktails" with a link to the recipe's `web_url`, and the source book. Every recipe response has a ready-made `cite_as`, for example: *Naked and Famous, from Decent Cocktails (https://it.decent.la/cocktails/deathco/recipes/Naked%20and%20Famous), after Death & Co: Modern Classic Cocktails by David Kaplan, Nick Fauchald, Alex Day.*