> ## Documentation Index
> Fetch the complete documentation index at: https://brewgravity.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate a recipe preview

> A structured read of how a recipe will turn out: appearance, aroma, flavour, mouthfeel, style adherence, and specific observations.

Takes a recipe id rather than a recipe body — the server loads the recipe under your own scope, so this cannot be used to analyse data you do not own.

Counts against your daily AI budget.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/ai/recipe-preview
openapi: 3.1.0
info:
  title: Brewgravity API
  version: 1.0.0
  description: >-
    Read and write your recipes, brew sessions, fermentation logs, and
    ingredient inventory.


    Every request is scoped to the account its credential belongs to — there is
    no `user_id` parameter anywhere, and an id belonging to someone else returns
    `404`.


    All units are metric: kilograms, grams, litres, degrees Celsius, minutes.
  contact:
    name: Brewgravity support
    email: support@brewgravity.com
servers:
  - url: https://brewgravity.com
    description: Production
  - url: http://localhost:8787
    description: Local development
security:
  - apiKey: []
tags:
  - name: Identity
    description: Who the credential belongs to.
  - name: Recipes
    description: Recipes and their computed stats.
  - name: Fermentables
    description: Grain, sugar, and extract on a recipe.
  - name: Hops
    description: Hop additions on a recipe.
  - name: Yeasts
    description: Yeast on a recipe.
  - name: Other ingredients
    description: Finings, salts, spices, and flavourings.
  - name: Mash steps
    description: A recipe's mash schedule.
  - name: Brew sessions
    description: Individual brew days made from a recipe.
  - name: Brew day steps
    description: The checklist attached to a brew session.
  - name: Fermentation logs
    description: Timestamped readings against a brew session.
  - name: Inventory
    description: Ingredients you physically have on hand.
  - name: AI
    description: Recipe analysis and usage metering.
  - name: Chats
    description: >-
      AI chat threads. The streaming turn endpoint is not part of the REST
      surface.
paths:
  /v1/ai/recipe-preview:
    post:
      tags:
        - AI
      summary: Generate a recipe preview
      description: >-
        A structured read of how a recipe will turn out: appearance, aroma,
        flavour, mouthfeel, style adherence, and specific observations.


        Takes a recipe id rather than a recipe body — the server loads the
        recipe under your own scope, so this cannot be used to analyse data you
        do not own.


        Counts against your daily AI budget.
      operationId: generateRecipePreview
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipePreviewRequest'
      responses:
        '200':
          description: The generated preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipePreview'
        '400':
          description: '`recipe_id` was missing or not a string'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid, or revoked credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such resource, or it does not belong to you
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Daily AI budget exhausted; resets at midnight UTC
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: AI is not configured on this deployment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RecipePreviewRequest:
      type: object
      properties:
        recipe_id:
          type: string
          description: The recipe to analyse
          format: uuid
      required:
        - recipe_id
    RecipePreview:
      type: object
      properties:
        taste:
          type: object
          properties:
            appearance:
              type: string
              description: How the beer will look
            aroma:
              type: string
              description: What it will smell like
            flavor:
              type: string
              description: What it will taste like
            mouthfeel:
              type: string
              description: Body and texture
            overall:
              type: string
              description: The summary judgement
        style_adherence:
          type: string
          description: How well the recipe fits the style it claims
        observations:
          type: array
          description: Specific points worth knowing about this recipe
          items:
            type: object
            properties:
              category:
                type: string
                enum:
                  - water
                  - mash
                  - hops
                  - yeast
                  - fermentation
                  - balance
                  - general
                description: What the observation is about
              title:
                type: string
                description: Short summary
              detail:
                type: string
                description: The full explanation
              severity:
                type: string
                enum:
                  - info
                  - attention
                description: '`attention` marks something worth acting on'
        predicted_characteristics:
          type: object
          properties:
            bitterness:
              type: string
              description: Perceived bitterness
            sweetness:
              type: string
              description: Perceived sweetness
            body:
              type: string
              description: Perceived body
            carbonation_suggestion:
              type: string
              description: Recommended carbonation level
            alcohol_warmth:
              type: string
              description: Perceived alcohol warmth
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable description of what went wrong
      required:
        - error
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: An API key created from a signed-in session. See Authentication.

````