# Cocktails API
> Search cocktails, fetch full recipes with measured ingredients and instructions, get a random drink, and filter by ingredient, category, glass or alcoholic / non-alcoholic. Each cocktail includes a photo and tags. Powered by TheCocktailDB.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/cocktails-api/..."
```

## Pricing
- **Free** (Free) — 2,500 calls/Mo, 2 req/s
- **Basic** ($6/Mo) — 40,000 calls/Mo, 8 req/s
- **Pro** ($18/Mo) — 200,000 calls/Mo, 25 req/s
- **Mega** ($44/Mo) — 1,200,000 calls/Mo, 80 req/s

## Endpoints

### Cocktails

#### `GET /v1/lookup` — Full cocktail by id

**Parameters:**
- `id` (query, required, string) — Numeric drink id Example: `11007`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cocktails-api/v1/lookup?id=11007"
```

**Response:**
```json
{
    "data": {
        "id": "11007",
        "name": "Margarita",
        "tags": [
            "IBA",
            "ContemporaryClassic"
        ],
        "glass": "Cocktail glass",
        "video": null,
        "category": "Ordinary Drink",
        "alcoholic": "Alcoholic",
        "thumbnail": "https://www.thecocktaildb.com/images/media/drink/5noda61589575158.jpg",
        "ingredients": [
            {
                "measure": "1 1/2 oz",
                "ingredient": "Tequila"
            },
            {
                "measure": "1/2 oz",
                "ingredient": "Triple sec"
            },
            {
                "measure": "1 oz",
                "ingredient": "Lime juice"
            },
            {
                "measure": null,
                "ingredient": "Salt"
            }
        ],
        "instructions": "Rub the rim of the glass with the lime slice to make the salt stick to it. Take care to moisten only the outer rim and sprinkle the salt on it. The salt should present to the lips of the imbiber and never mix into the cocktail. Shake the other ingredients with ice, then carefully pour into the glass."
    },
    "meta": {
        "timestamp": "2026-05-30T02:58:48.498Z",
        "request_id": "b1583981-8853-46e2-8845-7f7ab01b9214"
    },
    "status": "ok",
    "message": "Cocktail retrieved successfully",
    "success": true
}
```

#### `GET /v1/random` — A random cocktail

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cocktails-api/v1/random"
```

**Response:**
```json
{
    "data": {
        "id": "178339",
        "name": "The Strange Weaver",
        "tags": [
            "Classy"
        ],
        "glass": "Collins glass",
        "video": null,
        "category": "Cocktail",
        "alcoholic": "Alcoholic",
        "thumbnail": "https://www.thecocktaildb.com/images/media/drink/opxjzh1604179528.jpg",
        "ingredients": [
            {
                "measure": "1 oz",
                "ingredient": "Light Rum"
            },
            {
                "measure": "1 oz",
                "ingredient": "Gin"
            },
            {
                "measure": "0.75 oz",
                "ingredient": "Sweet Vermouth"
            },
            {
                "measure": "0.75 oz",
                "ingredient": "Campari"
            },
            {
                "measure": "Dash",
                "ingredient": "Lemon Juice"
            },
            {
                "measure": "Dash",
                "ingredient": "Orgeat Syrup"
            },
            {
                "measure": "Garnish with",
                "ingredient": "Orange Peel"
            }
        ],
        "instructions": "Mix ingredients slowly in a glass with ice, garnish with orange slice"
    },
    "meta": {
        "timestamp": "2026-05-30T02:58:49.704Z",
        "request_id": "8d1f3aa9-ba3c-45f2-82c5-f61d132d589a"
    },
    "status": "ok",
    "message": "Random cocktail retrieved successfully",
    "success": true
}
```

#### `GET /v1/search` — Search cocktails by name

**Parameters:**
- `q` (query, required, string) — Cocktail name Example: `margarita`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cocktails-api/v1/search?q=margarita"
```

**Response:**
```json
{
    "data": {
        "count": 6,
        "query": "margarita",
        "cocktails": [
            {
                "id": "11007",
                "name": "Margarita",
                "tags": [
                    "IBA",
                    "ContemporaryClassic"
                ],
                "glass": "Cocktail glass",
                "video": null,
                "category": "Ordinary Drink",
                "alcoholic": "Alcoholic",
                "thumbnail": "https://www.thecocktaildb.com/images/media/drink/5noda61589575158.jpg",
                "ingredients": [
                    {
                        "measure": "1 1/2 oz",
                        "ingredient": "Tequila"
                    },
                    {
                        "measure": "1/2 oz",
                        "ingredient": "Triple sec"
                    },
                    {
                        "measure": "1 oz",
                        "ingredient": "Lime juice"
                    },
                    {
                        "measure": null,
                        "ingredient": "Salt"
                    }
                ],
                "instructions": "Rub the rim of the glass with the lime slice to make the salt stick to it. Take care to moisten only the outer rim and sprinkle the salt on it. The salt should present to the lips of the imbiber and never mix into the cocktail. Shake the other ingredients with ice, then carefully pour into the glass."
            }
…(truncated, see openapi.json for full schema)
```

### Discovery

#### `GET /v1/filter` — Filter by ingredient/category/glass/alcoholic

**Parameters:**
- `ingredient` (query, optional, string) — Main ingredient Example: `Gin`
- `category` (query, optional, string) — Category Example: `Cocktail`
- `glass` (query, optional, string) — Glass type Example: `Highball glass`
- `alcoholic` (query, optional, string) — Alcoholic / Non_Alcoholic Example: `Alcoholic`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cocktails-api/v1/filter?ingredient=Gin&category=Cocktail&glass=Highball+glass&alcoholic=Alcoholic"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "filter": {
            "type": "ingredient",
            "value": "Gin"
        },
        "cocktails": [
            {
                "id": "15300",
                "name": "3-Mile Long Island Iced Tea",
                "thumbnail": "https://www.thecocktaildb.com/images/media/drink/rrtssw1472668972.jpg"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-30T02:58:50.473Z",
        "request_id": "1da25e97-a014-423f-b9b7-f824ae702fbf"
    },
    "status": "ok",
    "message": "Filtered cocktails retrieved successfully",
    "success": true
}
```

#### `GET /v1/list` — List filter values

**Parameters:**
- `type` (query, required, string) — categories | glasses | ingredients | alcoholic Example: `glasses`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cocktails-api/v1/list?type=glasses"
```

**Response:**
```json
{
    "data": {
        "type": "glasses",
        "count": 32,
        "values": [
            "Balloon Glass",
            "Beer Glass",
            "Beer mug",
            "Beer pilsner",
            "Brandy snifter",
            "Champagne flute",
            "Cocktail glass",
            "Coffee mug",
            "Collins glass",
            "Copper Mug",
            "Cordial glass",
            "Coupe Glass",
            "Highball glass",
            "Hurricane glass",
            "Irish coffee cup",
            "Jar",
            "Margarita glass",
            "Margarita/Coupette glass",
            "Martini Glass",
            "Mason jar",
            "Nick and Nora Glass",
            "Old-fashioned glass",
            "Parfait glass",
            "Pint glass",
            "Pitcher",
            "Pousse cafe glass",
            "Punch bowl",
            "Shot glass",
            "Whiskey Glass",
            "Whiskey sour glass",
            "White wine glass",
            "Wine Glass"
        ]
    },
    "meta": {
        "timestamp": "2026-05-30T02:58:50.908Z",
        "request_id": "d2652b91-bbda-4b92-a75b-473b654e697d"
    },
    "status": "ok",
    "message": "List retrieved successfully",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/cocktails-api
OpenAPI spec: https://www.oanor.com/api/cocktails-api/openapi.json