# Thecocktaildb — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Discover and explore thousands of cocktail recipes by searching by name, ingredient, category, or glass type, plus get random drink suggestions and detailed information about cocktail components. Filter drinks by whether they're alcoholic or non-alcoholic, and browse complete lists of available categories, glasses, and ingredients.

**Category:** Food & Dining | **Website:** [thecocktaildb.com/](https://thecocktaildb.com/) | **Docs:** [parse.bot/marketplace/130d6c01-f774-4b92-b008-ba1015a8708f/thecocktaildb-com-api](https://parse.bot/marketplace/130d6c01-f774-4b92-b008-ba1015a8708f/thecocktaildb-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### Filter cocktails by alcoholic

Filter cocktails by alcoholic classification. Returns abbreviated cocktail entries with name, thumbnail URL, and ID only.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `alcoholic` | string | Yes | Alcoholic filter value. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/filter_cocktails_by_alcoholic \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alcoholic":"<string>"}'
```

### Filter cocktails by category

Filter cocktails by category. Returns abbreviated cocktail entries with name, thumbnail URL, and ID only. Use list_categories to discover valid category values.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Category name to filter by, using underscores for spaces. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/filter_cocktails_by_category \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>"}'
```

### Filter cocktails by glass

Filter cocktails by glass type. Returns abbreviated cocktail entries with name, thumbnail URL, and ID only. Use list_glasses to discover valid glass values.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `glass` | string | Yes | Glass type to filter by, using underscores for spaces. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/filter_cocktails_by_glass \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"glass":"<string>"}'
```

### Filter cocktails by ingredient

Get a list of cocktails that contain a specified ingredient. Returns abbreviated cocktail entries with name, thumbnail URL, and ID only — use lookup_cocktail_by_id to get full details for a specific result.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ingredient` | string | Yes | Ingredient name to filter by. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/filter_cocktails_by_ingredient \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ingredient":"<string>"}'
```

### Get random cocktail

Fetch a single random cocktail with full details. No parameters required. Each call returns a different cocktail chosen randomly from the database.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/get_random_cocktail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### List alcoholic filters

List all available alcoholic classification values used by the database. Returns the set of values that can be passed to filter_cocktails_by_alcoholic.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/list_alcoholic_filters \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### List categories

List all available drink categories used by the database. Returns the complete set of category names that can be passed to filter_cocktails_by_category.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/list_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### List glasses

List all available glass types used by the database. Returns the complete set of glass names that can be passed to filter_cocktails_by_glass.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/list_glasses \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### List ingredients

List all available ingredient names used by the database. Returns objects with a single strIngredient1 field containing the ingredient name.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/list_ingredients \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Lookup cocktail by id

Fetch full cocktail details by its numeric ID (idDrink). Returns a single cocktail with all fields including instructions in multiple languages, all ingredients and measures, thumbnail, tags, and modification date. Returns an empty results array if the ID does not exist.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Numeric ID of the cocktail (idDrink). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/lookup_cocktail_by_id \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>"}'
```

### Lookup ingredient by id

Fetch ingredient details by numeric ingredient ID. Returns a single ingredient with description, type classification, alcohol flag, and ABV. Returns empty results if the ID does not exist.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Numeric ID of the ingredient. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/lookup_ingredient_by_id \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>"}'
```

### Search cocktails by first letter

List all cocktails whose name starts with a given single letter. Returns full cocktail details for each match including instructions, ingredients, measures, and images.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `letter` | string | Yes | Single letter (a-z) to match the first character of the cocktail name. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/search_cocktails_by_first_letter \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"letter":"<string>"}'
```

### Search cocktails by name

Search for cocktails by name or partial name. Returns full cocktail details including instructions, ingredients (strIngredient1–15), measures (strMeasure1–15), category, glass type, and thumbnail URL for all matching cocktails. An unmatched query returns an empty results array.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Cocktail name or partial name to search for. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/search_cocktails_by_name \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"<string>"}'
```

### Search ingredient by name

Search for an ingredient by name. Returns ingredient details including a text description, type classification, whether it is alcoholic, and ABV percentage. Returns empty results if no ingredient matches.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Ingredient name to search for. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/parse-thecocktaildb-com-api-130d6c01/search_ingredient_by_name \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"<string>"}'
```