Integrations

Third-party integrations available in BrewHoard — Untappd import, photo storage, and more.

Overview

BrewHoard supports several third-party integrations to enhance the beer collecting experience.

Untappd Integration

Import your beer history and ratings from Untappd into BrewHoard.

Setup Guide

  1. Go to Untappd Developer Dashboard and create a new app
  2. Set the redirect URL to https://your-domain.com/api/v1/integrations/untappd/callback
  3. Copy the Client ID and Client Secret
  4. Add these environment variables:
Bash
# Untappd OAuth
UNTAPPD_CLIENT_ID="your-client-id"
UNTAPPD_CLIENT_SECRET="your-client-secret"
UNTAPPD_REDIRECT_URL="https://your-domain.com/api/v1/integrations/untappd/callback"
  1. Restart the server

Connect Your Account

GET /api/v1/integrations/untappd

Initiates the OAuth flow with Untappd. Requires environment variables:

  • UNTAPPD_CLIENT_ID
  • UNTAPPD_CLIENT_SECRET
  • UNTAPPD_REDIRECT_URL

OAuth Callback

GET /api/v1/integrations/untappd/callback

Handles the OAuth callback from Untappd. Exchanges the auth code for an access token and stores it.

Import Data

POST /api/v1/integrations/untappd/import

Import beer history from Untappd into your BrewHoard collection.

Response:

JSON
{
  "success": true,
  "data": {
    "imported": 42,
    "skipped": 8,
    "errors": 2
  }
}

The import process:

  1. Fetches your beer check-ins from Untappd
  2. Matches beers against the BrewHoard database
  3. Creates new beer entries when no match is found
  4. Adds imported beers to your collection
  5. Imports ratings where available

Photo Upload

POST /api/v1/photos/upload

Upload photos for beers, collection items, or marketplace listings. Photos are stored in MinIO (S3-compatible) object storage.

Request: multipart/form-data

FieldTypeRequiredDescription
fileFileYesImage file (JPEG, PNG, WebP)
typestringYesbeer, collection, listing
idstringYesUUID of the related entity

Response:

JSON
{
  "success": true,
  "data": {
    "url": "/photos/beer/uuid/image-name.jpg",
    "thumbnailUrl": "/photos/beer/uuid/thumb-image-name.jpg"
  }
}

Environment Configuration

Photo storage requires MinIO configuration:

Bash
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=brewhoard-photos
MINIO_USE_SSL=false

Data Export

POST /api/v1/export

Export your collection data in various formats.

Request:

JSON
{
  "format": "csv",
  "filters": {
    "status": "available",
    "dateFrom": "2024-01-01"
  }
}

Supported formats:

  • csv — Comma-separated values
  • json — Full JSON export with nested data

Data Import

POST /api/v1/import

Import collection data from external sources.

Supported sources:

  • CSV files (BrewHoard format)
  • JSON exports (BrewHoard format)
  • Untappd data (via integration)

Health Check

GET /api/v1/health

Returns service health status.

JSON
{
  "status": "ok",
  "version": "0.0.1",
  "uptime": 86400,
  "database": "connected"
}

Next Steps