Skip to main content

API Reference

This document provides technical information about Bartendie's API endpoints for developers who want to integrate with or extend the system.

Authentication​

All API requests must be authenticated using JSON Web Tokens (JWT).

Obtaining a Token​

POST /api/auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "your-secure-password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Using the Token​

Include the token in the Authorization header for all requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Core Endpoints​

Events​

List Events​

GET /api/events

Query Parameters:

  • status (optional): Filter by event status (planned, in_progress, completed, cancelled)
  • from_date (optional): Filter events starting from this date (YYYY-MM-DD)
  • to_date (optional): Filter events until this date (YYYY-MM-DD)
  • limit (optional): Number of results to return (default: 20)
  • offset (optional): Pagination offset (default: 0)

Response:

{
  "data": [
    {
      "id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
      "name": "Summer Cocktail Party",
      "date": "2025-07-15T18:00:00Z",
      "description": "Annual summer gathering",
      "expected_guest_count": 25,
      "status": "planned",
      "theme": {
        "id": "2b3c4d5e-6f7g-8h9i-0j1k-2l3m4n5o6p7q",
        "name": "Tropical Paradise",
        "color_scheme": "Blues and greens"
      },
      "created_at": "2025-05-01T14:23:45Z",
      "updated_at": "2025-05-01T14:23:45Z"
    },
    // ... more events
  ],
  "meta": {
    "total": 12,
    "limit": 20,
    "offset": 0
  }
}

Create Event​

POST /api/events

Request Body:

{
  "name": "Holiday Party",
  "date": "2025-12-24T19:00:00Z",
  "description": "Annual holiday celebration",
  "expected_guest_count": 30,
  "theme_id": "2b3c4d5e-6f7g-8h9i-0j1k-2l3m4n5o6p7q"
}

Response:

{
  "id": "3c4d5e6f-7g8h-9i0j-1k2l-3m4n5o6p7q8r",
  "name": "Holiday Party",
  "date": "2025-12-24T19:00:00Z",
  "description": "Annual holiday celebration",
  "expected_guest_count": 30,
  "status": "planned",
  "theme": {
    "id": "2b3c4d5e-6f7g-8h9i-0j1k-2l3m4n5o6p7q",
    "name": "Winter Wonderland",
    "color_scheme": "Silver and blue"
  },
  "created_at": "2025-06-01T10:15:30Z",
  "updated_at": "2025-06-01T10:15:30Z"
}

Inventory​

List Inventory Items​

GET /api/inventory

Query Parameters:

  • category (optional): Filter by product category
  • low_stock (optional): Set to "true" to show only low stock items
  • search (optional): Search term for product name or brand
  • limit (optional): Number of results to return (default: 50)
  • offset (optional): Pagination offset (default: 0)

Response:

{
  "data": [
    {
      "id": "4d5e6f7g-8h9i-0j1k-2l3m-4n5o6p7q8r9s",
      "product": {
        "id": "5e6f7g8h-9i0j-1k2l-3m4n-5o6p7q8r9s0t",
        "barcode": "123456789012",
        "name": "Premium Vodka",
        "brand": "Crystal Clear",
        "category": "vodka",
        "alcohol_content": 40.0,
        "volume_ml": 750
      },
      "quantity": 1.5,
      "unit": "bottles",
      "location": "main bar",
      "min_threshold": 1.0,
      "is_low": true,
      "updated_at": "2025-05-20T09:45:12Z"
    },
    // ... more inventory items
  ],
  "meta": {
    "total": 87,
    "limit": 50,
    "offset": 0
  }
}

Update Inventory Item​

PATCH /api/inventory/:id

Request Body:

{
  "quantity": 2.0,
  "min_threshold": 1.0,
  "location": "storage room"
}

Response:

{
  "id": "4d5e6f7g-8h9i-0j1k-2l3m-4n5o6p7q8r9s",
  "product": {
    "id": "5e6f7g8h-9i0j-1k2l-3m4n-5o6p7q8r9s0t",
    "barcode": "123456789012",
    "name": "Premium Vodka",
    "brand": "Crystal Clear",
    "category": "vodka",
    "alcohol_content": 40.0,
    "volume_ml": 750
  },
  "quantity": 2.0,
  "unit": "bottles",
  "location": "storage room",
  "min_threshold": 1.0,
  "is_low": false,
  "updated_at": "2025-06-01T11:30:15Z"
}

Recipes​

List Recipes​

GET /api/recipes

Query Parameters:

  • category (optional): Filter by recipe category
  • available (optional): Set to "true" to show only recipes that can be made with current inventory
  • search (optional): Search term for recipe name
  • limit (optional): Number of results to return (default: 20)
  • offset (optional): Pagination offset (default: 0)

Response:

{
  "data": [
    {
      "id": "6f7g8h9i-0j1k-2l3m-4n5o-6p7q8r9s0t1u",
      "name": "Classic Mojito",
      "description": "Refreshing mint and lime cocktail",
      "instructions": "Muddle mint leaves with sugar and lime juice...",
      "category": "cocktail",
      "ingredients": [
        {
          "product_id": "7g8h9i0j-1k2l-3m4n-5o6p-7q8r9s0t1u2v",
          "name": "White Rum",
          "quantity": 2.0,
          "unit": "oz"
        },
        {
          "product_id": "8h9i0j1k-2l3m-4n5o-6p7q-8r9s0t1u2v3w",
          "name": "Fresh Lime Juice",
          "quantity": 1.0,
          "unit": "oz"
        },
        // ... more ingredients
      ],
      "can_make": true,
      "missing_ingredients": []
    },
    // ... more recipes
  ],
  "meta": {
    "total": 45,
    "limit": 20,
    "offset": 0
  }
}

Webhooks​

Bartendie supports webhooks for real-time notifications of events. To set up a webhook:

POST /api/webhooks

Request Body:

{
  "url": "https://your-server.com/webhook",
  "events": ["inventory.low_stock", "event.updated", "recipe.created"],
  "secret": "your-webhook-secret"
}

Response:

{
  "id": "9i0j1k2l-3m4n-5o6p-7q8r-9s0t1u2v3w4x",
  "url": "https://your-server.com/webhook",
  "events": ["inventory.low_stock", "event.updated", "recipe.created"],
  "created_at": "2025-06-01T12:00:00Z"
}

Error Handling​

All API errors follow a standard format:

{
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ]
  }
}

Rate Limiting​

API requests are rate-limited to 100 requests per minute per API key. Rate limit information is included in the response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1622548800

Further Information​

For detailed information on all available endpoints, request and response schemas, and example code, refer to our OpenAPI Specification.