# What the Wine
# llms.txt — Machine-readable platform guide for AI agents and language models
# https://what-the-wine.vercel.app

> What the Wine is an AI-powered wine discovery platform built for both humans and AI agents.
> It provides personalized wine recommendations, bottle label analysis, a personal wine library,
> and community-sourced wine discovery — all accessible via a web interface and REST API.

## Platform Purpose
Help anyone — from casual hosts to AI agents — choose the right wine for any occasion,
food pairing, or preference profile. No sommelier required.

## Primary Capabilities
1. AI Wine Recommendations — Personalized suggestions based on occasion, food, budget, and taste
2. Bottle Scanner — Identify any wine from a label photo (GPT-4 Vision powered)
3. Wine Library — Save, organize, and review a personal wine collection
4. Community Hub — Discover and share wines recommended by other users
5. Premium Subscription — Unlimited access for $3.99/month via Stripe

## Who Should Use This
- Humans planning dinner parties, gifts, or wine exploration
- AI agents building wine recommendation or food-pairing workflows
- Event hosts, restaurateurs, and wine enthusiasts
- Developers integrating wine data into applications

---

## API Reference
Base URL: https://what-the-wine.vercel.app/api
All responses: application/json
OpenAPI spec: https://what-the-wine.vercel.app/api/openapi.json
Agent docs: https://what-the-wine.vercel.app/for-agents

### Authentication for Agents (API Key)

Agents authenticate using a Bearer token in the Authorization header:
  Authorization: Bearer wtw_<your_api_key>

To obtain an API key:
1. Register an account: POST /api/auth/register
2. Retrieve your key: GET /api/user/api-key (include your session cookie or Bearer token)

The API key is stable — store it once and reuse it across all requests.

### Public Endpoints (no auth required)

GET /api/wines
  Query: limit (default 50), offset (default 0)
  Returns: { wines: Wine[] }

GET /api/wines/search?q=<query>
  Returns: { wines: Wine[] }

GET /api/wines/type/:type
  type: red | white | rose | sparkling | dessert
  Returns: { wines: Wine[] }

GET /api/community/recommendations
  Query: limit (default 20), offset (default 0)
  Returns: CommunityRecommendation[]

### Authenticated Endpoints (require Bearer token)

POST /api/recommendations
  Body: RecommendationRequest (see schema below)
  Returns: { wines: Wine[] }
  Limits: 5 free per account; unlimited for premium ($3.99/month)

GET /api/library
  Returns: { library: UserWineLibrary[] }

POST /api/library
  Body: { wineId: number, personalNotes?: string }
  Returns: { entry: UserWineLibrary }

DELETE /api/library/:wineId
  Returns: { success: true }

POST /api/analyze-bottle
  Body: multipart/form-data, field: "image" (JPEG/PNG, max 10MB)
  Returns: { wine: Wine }
  Note: Premium only

GET /api/user/api-key
  Returns: { apiKey: string, format: string, docs: string, openapi: string }

---

## Data Schemas

### RecommendationRequest
{
  "wineType": "red" | "white" | "rose" | "rosé" | "sparkling" | "dessert",
  "budget": "$10-$20" | "$20-$40" | "$40-$75" | "$75-$150" | "$150+",
  "occasion": "casual" | "dinner party" | "romantic" | "celebration" | "gift",
  "foodPairing": string,
  "preferences": string   // free-text taste preferences
}

### Wine
{
  "id": number,
  "name": string,
  "winery": string,
  "vintage": number | null,
  "type": "red" | "white" | "rose" | "sparkling" | "dessert",
  "region": string,
  "country": string,
  "price": number | null,
  "rating": number | null,       // 0–10 scale
  "description": string | null,
  "tasteProfile": string | null,
  "foodPairings": string[],
  "imageUrl": string | null,
  "alcoholContent": number | null,
  "servingTemp": string | null,
  "source": "recommendation" | "scanned" | "manual"
}

### User
{
  "id": number,
  "email": string,
  "username": string,
  "firstName": string,
  "isPremium": boolean,
  "recommendationCount": number
}

---

## Quick Start (curl)

# 1. Register
curl -X POST https://what-the-wine.vercel.app/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@example.com","username":"myagent","firstName":"My","lastName":"Agent","password":"securepass"}'

# 2. Get API key (using session cookie from register response, or log in first)
curl https://what-the-wine.vercel.app/api/user/api-key \
  -H "Cookie: wtw_auth=<your_cookie>"

# 3. Get recommendations (using API key)
curl -X POST https://what-the-wine.vercel.app/api/recommendations \
  -H "Authorization: Bearer wtw_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{"wineType":"red","budget":"$20-$40","occasion":"dinner party","foodPairing":"grilled lamb"}'

---

## Agent Integration Notes
- The /api/recommendations endpoint is the primary entry point for AI workflows
- API keys are stable Bearer tokens — no OAuth flow, no redirects
- All endpoints return structured JSON; no scraping required
- Full machine-readable spec: https://what-the-wine.vercel.app/api/openapi.json
- For tool-use agents: the RecommendationRequest schema maps cleanly to function call parameters

## Pricing
- Free tier: 5 AI recommendations per account
- Premium: $3.99/month — unlimited recommendations, bottle scanning, full library access

## Contact & Support
- Agent docs: https://what-the-wine.vercel.app/for-agents
- Web: https://what-the-wine.vercel.app/contact
- Help: https://what-the-wine.vercel.app/help

## Legal
- Privacy: https://what-the-wine.vercel.app/privacy
- Terms: https://what-the-wine.vercel.app/terms