# Thecocktaildb — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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>"}'
```