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

# Create meal

> Create a new meal for a user. This endpoint stores the meal and triggers
asynchronous nutrition analysis. The response includes the meal with
analysis_status='pending'. When analysis completes, a 'meals:updated'
webhook will be sent with full nutrition data, and the meal's
`summary_id` will reference an AI-generated `MealSummary` retrievable
via `GET /users/{user_id}/ai/summaries/{summary_id}`.




## OpenAPI

````yaml /api-reference/openapi.yaml post /users/{user_id}/nutrition/meals
openapi: 3.1.0
info:
  title: ONVY Health API
  description: >-
    AI-powered holistic health services API with data merging and metrics
    calculation
  version: 1.0.0
  contact:
    name: ONVY Support
    email: support@onvy.health
    url: https://onvy.health
  license:
    name: Proprietary
    url: https://onvy.health/terms
servers:
  - url: https://api.onvy.health
    description: Public API
security:
  - bearerAuth: []
tags:
  - name: static
    description: Static configuration endpoints
  - name: users
    description: User management
  - name: baselines
    description: User baseline metrics
  - name: daily-records
    description: Daily health records
  - name: chat
    description: AI chat completions
  - name: facts
    description: User facts for individualization
  - name: activities
    description: User activities (workouts and mindfulness sessions)
  - name: ai-summaries
    description: |
      AI-generated summaries. This is how ONVY exposes domain-specific
      insights such as meal nutrition analysis, sleep insights, workouts,
      and daily, weekly, nutrition, trend, and impact analysis. Most
      summary types are system-generated; the public create surface
      currently accepts `type=meal`.
  - name: custom-records
    description: Custom records and types
  - name: meals
    description: Nutrition meal tracking
paths:
  /users/{user_id}/nutrition/meals:
    post:
      tags:
        - meals
      summary: Create meal
      description: |
        Create a new meal for a user. This endpoint stores the meal and triggers
        asynchronous nutrition analysis. The response includes the meal with
        analysis_status='pending'. When analysis completes, a 'meals:updated'
        webhook will be sent with full nutrition data, and the meal's
        `summary_id` will reference an AI-generated `MealSummary` retrievable
        via `GET /users/{user_id}/ai/summaries/{summary_id}`.
      operationId: createMeal
      parameters:
        - $ref: '#/components/parameters/UserIdParam'
      requestBody:
        description: Meal data (requires either description or image_base64)
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MealInput'
            examples:
              text_meal:
                summary: Text-based meal
                value:
                  meal_time: '2024-10-28T12:00:00Z'
                  description: Grilled chicken breast with quinoa and steamed broccoli
                  portion_multiplier: 1.5
                  comment: Homemade healthy lunch
              image_meal:
                summary: Image-based meal
                value:
                  meal_time: '2024-10-28T12:00:00Z'
                  image_base64: data:image/jpeg;base64,/9j/4AAQSkZJRg...
                  portion_multiplier: 1
      responses:
        '201':
          description: Meal created successfully (analysis pending)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Meal'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    UserIdParam:
      name: user_id
      in: path
      required: true
      description: User ID (e.g., google_104940819145861640201)
      schema:
        type: string
  schemas:
    MealInput:
      title: MealInput
      description: Input schema for creating or updating a meal
      type: object
      required:
        - meal_time
      properties:
        meal_time:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the meal was consumed
          example: '2024-10-28T12:00:00Z'
        description:
          type: string
          description: >-
            Text description of the meal/food consumed. Required if image_base64
            is not provided.
          maxLength: 2000
          example: Grilled chicken breast with quinoa and steamed broccoli
        image_base64:
          type: string
          description: >-
            Base64-encoded image data with data URI prefix. Required if
            description is not provided.
          pattern: ^data:image/(jpeg|png|jpg);base64,[A-Za-z0-9+/=]+$
          example: data:image/jpeg;base64,/9j/4AAQSkZJRg...
        portion_multiplier:
          type: number
          description: Multiplier for portion size (default 1.0)
          default: 1
          minimum: 0.1
          maximum: 10
          example: 1.5
        comment:
          type: string
          description: Additional comment about the meal
          maxLength: 500
          example: Homemade healthy lunch
      anyOf:
        - required:
            - description
        - required:
            - image_base64
    Meal:
      title: Meal
      description: A meal record with nutrition analysis status
      type: object
      required:
        - id
        - user_id
        - project_id
        - meal_time
        - analysis_status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Unique meal identifier (ULID format)
          example: meal_01JCXVK5N3P4Q2R7S8T9U0V1W2
        user_id:
          type: string
          description: User ID this meal belongs to
        project_id:
          type: string
          description: Project ID this meal belongs to
        meal_time:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the meal was consumed
          example: '2024-10-28T12:00:00Z'
        description:
          type: string
          description: Text description of the meal/food consumed
          maxLength: 2000
          example: Grilled chicken breast with quinoa and steamed broccoli
        image_url:
          type: string
          format: uri
          description: Presigned URL to access the meal image (expires in 24 hours)
          example: https://s3.amazonaws.com/bucket/meals/image.jpg?X-Amz-...
        portion_multiplier:
          type: number
          description: Multiplier for portion size
          default: 1
          minimum: 0.1
          maximum: 10
          example: 1.5
        comment:
          type: string
          description: Additional comment about the meal
          maxLength: 500
          example: Homemade healthy lunch
        analysis_status:
          type: string
          description: Status of nutrition analysis
          enum:
            - pending
            - complete
            - failed
          example: complete
        analysis_error:
          type: string
          description: >-
            Error message when analysis_status is 'failed' (max 500 characters,
            truncated if longer)
          maxLength: 500
          example: 'Failed to analyze meal: Image is not food-related'
        summary_id:
          type: string
          description: >-
            Reference to the AI-generated MealSummary (set when analysis
            completes)
          example: aisummary_01JCXVK5N3P4Q2R7S8T9U0V1W2
        ai_generated:
          type: boolean
          description: True if this meal has been analyzed by AI
          example: true
        title:
          type: string
          description: AI-generated title for the meal summary
          example: Meal Summary
        text:
          type: string
          description: AI-generated analysis text
          example: >-
            Great balanced meal! This chicken with broccoli and brown rice
            provides excellent protein (35g) with moderate carbs.
        name:
          type: string
          description: AI-identified meal name
          example: Grilled Chicken with Vegetables
        ingredients:
          type: string
          description: AI-identified ingredients list
          example: chicken breast, broccoli, brown rice, olive oil
        calories:
          type: integer
          description: Estimated calories (kcal)
          example: 450
        protein_grams:
          type: number
          description: Estimated protein in grams
          example: 35
        fat_grams:
          type: number
          description: Estimated fat in grams
          example: 12
        carbohydrate_grams:
          type: number
          description: Estimated carbohydrates in grams
          example: 45
        sugar_grams:
          type: number
          description: Estimated sugar in grams
          example: 5
        fiber_grams:
          type: number
          description: Estimated fiber in grams
          example: 6
        glucose_spike_mg_dl:
          type: integer
          description: Estimated glucose spike in mg/dL
          example: 25
        healthiness_score:
          type: string
          description: >-
            Overall healthiness grade (A-E, where A is healthiest and E is least
            healthy)
          example: A
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the meal was created
          example: '2024-10-28T12:05:00Z'
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the meal was last updated
          example: '2024-10-28T12:10:00Z'
    ValidationError:
      type: object
      title: ValidationError
      required:
        - error
      properties:
        error:
          type: string
          minLength: 1
      additionalProperties: false
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth bearer token for Health API authentication

````