# 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:** (Markdown: ) - **OpenAPI description:** - **Site description for AI agents:** ## 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 | | | `deathco` | Death & Co: Modern Classic Cocktails | David Kaplan, Nick Fauchald, Alex Day (Ten Speed Press, 2014) | 477 | 453 | | ## 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 | | | `GET /cocktails/api/{book}/recipes?offset=&limit=` | recipe names and links, at most 50 per page, with `next` | | | `GET /cocktails/api/{book}/recipes/{name}` | one recipe in full | | | `GET /cocktails/api/{book}/ingredients?offset=&limit=` | ingredient names and links | | | `GET /cocktails/api/{book}/ingredients/{name}` | category, ABV and the cocktails using it | | | `GET /cocktails/api/{book}/search?q=` | cocktails and ingredients matching `q`, at most 20 each | | 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, `also_in` (the same cocktail in the other books, with `same_recipe` true when the recipe is identical), `image_url` (an AI-generated illustration, 500px JPEG), `images` and `glass_images` (that picture and the glass's, in every size: see Pictures below), `source_book` (title, authors, publisher, year, ISBN, buy link), `cite_as` and `license`. ## Pictures Every cocktail and glass has an AI-generated illustration by Decent, and every ingredient a picture of its bottle or fruit; all on white, all square. A recipe's `images` and `glass_images` give the URLs of each copy that exists, so you needn't build them. To build them yourself, start from the picture's **name**: the path below `https://fast.decentespresso.com/cocktails/img/` without the extension, such as `deathco/negroni`, `glasses/coupe` or `ingredients/campari`. It is the `name` in `images`, and the `image` column of the `drink`, `ingredient` and `glass` tables (null where there's no picture). For a name `{dir}/{n}`: | Copy | URL below /cocktails/img/ | Size | Made for | |---|---|---|---| | `png` | `{dir}/{n}.png` | 1024×1024 (spirit-pair pictures 512 tall) | the master; large, about 1 MB | | `avif` | `{dir}/{n}.avif` | cocktails 500px, ingredients 360px, glasses 260px | what the pages show | | `jpg` | `{dir}/{n}.jpg` | the AVIF's size | for browsers without AVIF | | `thumb` | `{dir}/t/{n}.jpg` | 192px | small icons: lists, chips, recipe rows | | `zoom` | `{dir}/tz/{n}.jpg` | white margins cut away on all four sides; the full picture 840px tall | cocktails, ingredients and glasses: the hover zoom, the scale's step picture | | `crop`, `crop_avif` | `{dir}/vc/{n}.jpg`, `.avif` | cut top and bottom to the glass and its shadow; 500px wide | cocktails: the recipe page's large photo | | `baseline` | `{dir}/tr/{n}.jpg` | margins cut away, at one common scale (600px per 1024) | cocktails and ingredients standing side by side on one baseline | | | `ingredients/tc/{n}.jpg` | cut left, right and bottom to the bottle and its shadow; the full picture 216px tall | ingredients: the recipe page's strip of bottles | How a name is made, should you have only the drink's name: lowercase it, turn `&` into ` and `, replace each run of characters other than letters, digits, `_`, `.`, `'` and `-` with one `_`, and trim `_` and `.` from the ends. A cocktail is `{book}/{that}` (`deathco/naked_and_famous`), an ingredient `ingredients/{that}` (shared by every book). A glass is `glasses/{name}` with each run of anything but `a-z0-9` replaced by `-` (`glasses/nick-nora` for Nick & Nora). Other pictures: `spirits/pair/{a}-{b}` (two base spirits' bottles side by side, keys in alphabetical order, e.g. `spirits/pair/gin-rum`; png, avif and jpg 180px tall, `t/` 192px), `hero` and `hero-{book}` (`.avif`, `.jpg`, 1200×1200, a book's home page), and the 1200×630 share pictures `og/{page}.jpg` (`og/{book}/` for books other than PDT). The cocktail and glass pictures are Decent's own and CC BY 4.0, as below. The ingredient pictures are not covered by that licence and are not in the API: many are product photographs, or drawn from them, and show the makers' labels. ## Your own data: /cocktails/api/me A logged-in member's own Liked and Made lists, notes, Your Bar and settings. You log in with the website's cookies, or an OAuth bearer token (the app). These requests are never cached and don't count toward the limit below. | Request | Does | |---|---| | `GET /cocktails/api/me` | everything: `liked` (`id`, `book`, `liked_at`), `made` (`id`, `book`, `last_made_at`, `times_made`), `notes` (drink id → text), `bar` (locations and what is in each), `prefs` (`hide_unmakeable`, `video_hidden`, `share`), `following` | | `PUT` / `DELETE /cocktails/api/me/liked/{drink id}` | add to / take off Liked | | `PUT` / `DELETE /cocktails/api/me/made/{drink id}?source=web\|scale\|app` | made it now (making it again re-dates it and counts it) / take off Made | | `PUT` / `DELETE /cocktails/api/me/notes/{drink id}` | your note on a drink (form field `note`; empty deletes) | | `PUT /cocktails/api/me/bar` | the whole bar (form field `bar`: `{"cur":id,"locs":[{"id","name","items":[{"t":"i","id":N} or {"t":"b","b":kind} or {"t":"c","b":kind,"d":text}]}]}`) | | `POST /cocktails/api/me/bar/items` | add one item (form field `item`) to the current location | | `PUT /cocktails/api/me/prefs` | any of `hide_unmakeable`, `video_hidden`, `share_made`, `share_liked` (0 or 1) | | `PUT` / `DELETE /cocktails/api/me/following/{member id}` | add / remove a member who shares their bar | Drink ids are unique across books. Answers are `{"ok":true}`, or an `error` with 400 (bad id or body), 401 (not logged in) or 404. ## MCP server For AI assistants (Claude and others), the same recipes are an MCP server: https://zh-hans.decentespresso.com/cocktails/mcp. No account is needed for recipes; with a free decentespresso.com account it also keeps Your Bar ("what can I make?") and the Wishlist and Made lists (connect https://zh-hans.decentespresso.com/cocktails/mcp/account to sign in). ## 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://zh-hans.decentespresso.com/cocktails/deathco/recipes/Naked%20and%20Famous), after Death & Co: Modern Classic Cocktails by David Kaplan, Nick Fauchald, Alex Day.*