# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/thecocktaildb/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/thecocktaildb/filter-cocktails-by-alcoholic \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/filter-cocktails-by-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/filter-cocktails-by-glass \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/filter-cocktails-by-ingredient \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/get-random-cocktail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/list-alcoholic-filters \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/list-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/list-glasses \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/list-ingredients \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/lookup-cocktail-by-id \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/lookup-ingredient-by-id \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/search-cocktails-by-first-letter \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/search-cocktails-by-name \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/thecocktaildb/search-ingredient-by-name \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.