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

# Capture User Feedback and Ratings

> Record user feedback and ratings for conversations or individual messages.

Use this endpoint to collect feedback about response quality or overall conversation experiences. You can rate either a specific message (using `messageId` or `externalMessageId`) or an entire conversation (using `conversationId` or `externalConversationId`).



## OpenAPI

````yaml https://www.greenflash.ai/api/openapi post /ratings
openapi: 3.1.0
info:
  title: Greenflash API Reference
  version: 1.0.0
  description: >-
    Greenflash endpoints for capturing interactions, managing prompts, and
    identifying users.
servers:
  - url: https://www.greenflash.ai/api/v1
    description: Greenflash API v1
security: []
tags:
  - name: Interactions
    description: Capture interactions between users and AI
  - name: Business Events
    description: Capture business events
  - name: Analytics
    description: Understand chat and agentic interactions analyses
  - name: Inbox
    description: Review flagged conversations
  - name: Segments
    description: Manage user segments
  - name: Prompts
    description: Manage prompts
  - name: Chat
    description: Stream chat and agentic conversations
  - name: Models
    description: Manage AI models
  - name: Products
    description: Manage products
  - name: Users
    description: Manage users
  - name: Organizations
    description: Manage organizations
paths:
  /ratings:
    post:
      tags:
        - Interactions
      summary: Capture User Feedback and Ratings
      description: >-
        Record user feedback and ratings for conversations or individual
        messages.


        Use this endpoint to collect feedback about response quality or overall
        conversation experiences. You can rate either a specific message (using
        `messageId` or `externalMessageId`) or an entire conversation (using
        `conversationId` or `externalConversationId`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RatingsRequest'
            example:
              externalConversationId: 123e4567-e89b-12d3-a456-426614174000
              rating: 4
              ratingMin: 1
              ratingMax: 5
              feedback: Helpful response!
              ratedAt: '2025-07-09T09:00:00Z'
      responses:
        '200':
          description: Rating logged successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatingsResponse'
              example:
                success: true
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the API call was successful (false for errors).
                  error:
                    type: string
                    description: Error message describing what went wrong.
                description: Error response for rating logging operations.
              example:
                success: false
                error: Internal server error
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Greenflash from 'greenflash';

            const client = new Greenflash({
              apiKey: process.env['GREENFLASH_API_KEY'], // This is the default and can be omitted
            });

            const logRatingResponse = await client.ratings.log({
              productId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
              rating: 4,
              ratingMax: 5,
              ratingMin: 1,
              externalConversationId: '123e4567-e89b-12d3-a456-426614174000',
              feedback: 'Helpful response!',
              ratedAt: '2025-07-09T09:00:00Z',
            });

            console.log(logRatingResponse.success);
        - lang: Python
          source: |-
            import os
            from datetime import date
            from greenflash import Greenflash

            client = Greenflash(
                api_key=os.environ.get("GREENFLASH_API_KEY"),  # This is the default and can be omitted
            )
            log_rating_response = client.ratings.log(
                product_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
                rating=4,
                rating_max=5,
                rating_min=1,
                external_conversation_id="123e4567-e89b-12d3-a456-426614174000",
                feedback="Helpful response!",
                rated_at=date.fromisoformat("2025-07-09T09:00:00Z"),
            )
            print(log_rating_response.success)
components:
  schemas:
    RatingsRequest:
      type: object
      properties:
        productId:
          type: string
          format: uuid
          description: The Greenflash product ID to rate.
        conversationId:
          type: string
          format: uuid
          description: >-
            The Greenflash conversation ID to rate. Either conversationId,
            externalConversationId, messageId, or externalMessageId must be
            provided.
        externalConversationId:
          type: string
          description: >-
            Your external conversation identifier to rate. Either
            conversationId, externalConversationId, messageId, or
            externalMessageId must be provided.
        messageId:
          type: string
          description: >-
            The Greenflash message ID to rate. Either conversationId,
            externalConversationId, messageId, or externalMessageId must be
            provided.
        externalMessageId:
          type: string
          description: >-
            Your external message identifier to rate. Either conversationId,
            externalConversationId, messageId, or externalMessageId must be
            provided.
        rating:
          type: number
          description: >-
            The rating value. Must be between ratingMin and ratingMax
            (inclusive).
        ratingMin:
          type: number
          description: The minimum possible rating value (e.g., 1 for a 1-5 scale).
        ratingMax:
          type: number
          description: The maximum possible rating value (e.g., 5 for a 1-5 scale).
        ratedAt:
          type: string
          format: date
          description: When the rating was given. Defaults to current time if not provided.
        feedback:
          type: string
          description: Optional text feedback accompanying the rating.
      required:
        - productId
        - rating
        - ratingMin
        - ratingMax
      description: Request payload for logging ratings.
    RatingsResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the API call was successful.
      required:
        - success
      description: Success response for rating logging.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````