Émile Wines API

openapi: 3.2.0
info:
  title: Émile Wines API
  description: '# Émile API


    Public API for the Émile wine cellar app.


    ## Authentication


    Two methods are supported:


    **1. API Key** (recommended for external clients: MCP servers, scripts, ChatGPT custom connectors)


    Send your key in the `X-API-Key` header OR as `Authorization: Bearer emile_live_...`.


    Generate keys from your iOS app: **Profil → Paramètres → Clés API**.


    **2. Supabase JWT** (used by the official iOS app — internal)


    Send `Authorization: Bearer `.


    ## Rate Limits


    All endpoints are rate-limited per user. See each endpoint''s documentation for specific limits.

    On exceeded: HTTP 429 with `Retry-After` header and `X-RateLimit-*` informational headers.


    | Endpoint | Limit |

    |---|---|

    | `POST /scan` | 10/min, 50/day |

    | `POST /me/scan:batch` | 5/hour |

    | `POST /recommendations` | 20/min, 100/day |

    | `POST /cellars/{id}/bottles` | 60/min, 500/day |

    | `POST /me/bottles:batch` | 10/hour, 50/day |

    | `POST /me/keys` | 5/hour, 20/day |'
  version: '1.0'
tags:
- name: wines
paths:
  /wines/search:
    get:
      tags:
      - wines
      summary: Search Wines
      description: Fuzzy search wines by name and optional producer using pg_trgm.
      operationId: search_wines_wines_search_get
      security:
      - HTTPBearer: []
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          description: Wine name to search
          title: Q
        description: Wine name to search
      - name: producer
        in: query
        required: false
        schema:
          type: string
          description: Producer / domaine
          default: ''
          title: Producer
        description: Producer / domaine
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 10
          title: Limit
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /wines:
    post:
      tags:
      - wines
      summary: Manually create a wine reference
      description: Used when neither the scan nor the text search surface the wine. Calls the same LLM enrichment used by scan to fill in grape varieties, food pairings, region, etc. If the LLM is unavailable the raw user input is inserted as-is so the user never ends up in a dead end. The created wine is public (visible to all users), tagged via `source` so we can audit / clean later.
      operationId: create_wine_wines_post
      security:
      - HTTPBearer: []
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WineCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WineCreate:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        producer:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Producer
        appellation:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Appellation
        region:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Region
        country:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Country
        color:
          anyOf:
          - type: string
            enum:
            - rouge
            - blanc
            - rosé
            - effervescent
            - liquoreux
            - other
          - type: 'null'
          title: Color
      type: object
      required:
      - name
      title: WineCreate
      description: 'User-provided wine reference. All fields except `name` are optional;

        the LLM-enrichment step fills the gaps when configured.


        `color` is restricted to the same allowlist as the CHECK constraint

        on `wine_references.color` so an invalid value is rejected at the

        edge instead of bubbling up as a Postgres error.'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer