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

# Ambient Session User Feedback

> Submit user feedback on generated clinical content for continuous improvement

Use the **Feedback API** to collect quantitative (ratings) and qualitative (comments) feedback. Capturing feedback helps drive AI model improvement and increases client confidence.

The API supports the following actions:

* **Quantitative Feedback**: Rate content using a scale with configurable minimum and maximum values.

* **Qualitative Feedback**: Provide optional, free-form comments for detailed insights.

* **Entity-Level Tracking**: Tie feedback to specific entities within sessions.

## Supported entity types

Provide feedback on the following entity types:

| Entity type | Description                |
| ----------- | -------------------------- |
| `content`   | Generated clinical content |

<Warning>
  Within a single <Tooltip tip="A single, time-bound instance of an ambient recording for a specific patient encounter that captures clinical conversations." cta="View in Glossary" href="/Glossary/a">ambient session</Tooltip> (session\_id), you can provide feedback for each `entity type` only **once**. If you provide feedback for the same `entity type` multiple times, the feedback will not be valid.

  Also, a single `session_id` can contain **multiple feedbacks**, provided each entry corresponds to a **different** entity type.
</Warning>

## Rating system

The `ratingFeedback` object provides quantitative feedback. It includes the following fields:

* `min_rating`: The minimum rating value (e.g., 0).

* `max_rating`: The maximum rating value.

* `rating`: The actual rating you provide within the min-max range.

<Note>
  Configure the rating scale by setting the `min_rating` and `max_rating` values. The range is **inclusive**, so both the `min_rating` and `max_rating` values are valid ratings.

  For example:

  * To create a rating scale of 0 to 5, set `min_rating` to 0 and `max_rating` to 5. A user can provide any integer rating from 0 to 5.

  * To create a binary scale, set `min_rating` to 0 and `max_rating` to 1. A user can provide a rating of either 0 or 1.

  * Suki suggests using a scale of 1 to 5 for the rating.
</Note>

## Character limits

* `qualitative_comments`: Maximum **2000** characters.

<Note>
  Your feedback helps Suki to improve the AI-generated content. All feedback is reviewed and used to enhance quality.
</Note>

## Code examples

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import requests

    session_id = "session_abc_123"
    entity = "content"
    url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{session_id}/{entity}/feedback"

    headers = {
        "sdp_suki_token": "<sdp_suki_token>",
        "sdp_provider_id": "<sdp_provider_id>",
        "Content-Type": "application/json"
    }

    payload = {
        "ratingFeedback": {
            "min_rating": 0,
            "max_rating": 5,
            "rating": 4
        },
        "qualitative_comments": "The generated content was accurate and helpful. Great job!"  # Optional, max 2000 chars
    }

    response = requests.post(url, json=payload, headers=headers)

    if response.status_code == 201:
        data = response.json()
        feedback_id = data.get("feedback_id")
        print(f"Feedback submitted successfully. Feedback ID: {feedback_id}")
    else:
        print(f"Failed to submit feedback: {response.status_code}")
        print(response.json())
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const sessionId = 'session_abc_123';
    const entity = 'content';
    const response = await fetch(
      `https://sdp.suki-stage.com/api/v1/ambient/session/${sessionId}/${entity}/feedback`,
      {
        method: 'POST',
        headers: {
          'sdp_suki_token': '<sdp_suki_token>',
          'sdp_provider_id': '<sdp_provider_id>',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          ratingFeedback: {
            min_rating: 0,
            max_rating: 5,
            rating: 4
          },
          qualitative_comments: 'The generated content was accurate and helpful. Great job!' // Optional, max 2000 chars
        })
      }
    );

    if (response.status === 201) {
      const data = await response.json();
      const feedbackId = data.feedback_id;
      console.log(`Feedback submitted successfully. Feedback ID: ${feedbackId}`);
    } else {
      const error = await response.json();
      console.error(`Failed to submit feedback: ${response.status}`, error);
    }
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml POST /api/v1/ambient/session/{session_id}/{entity}/feedback
openapi: 3.0.1
info:
  title: Suki Developer Platform
  description: >-
    REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
    Login or Register to obtain a Suki access token, then integrate ambient
    clinical documentation, form filling, transcription, and reference metadata
    endpoints.
  contact: {}
  version: '1.0'
servers:
  - url: https://sdp.suki.ai
    description: >-
      Production base URL for Suki Developer Platform REST APIs. WebSocket
      endpoints use the same host with `wss://`.
security:
  - SukiTokenAuth: []
paths:
  /api/v1/ambient/session/{session_id}/{entity}/feedback:
    post:
      tags:
        - /api/v1/ambient/session/{session_id}/{entity}/feedback
      summary: Submit ambient session feedback
      description: >-
        Submits quantitative and qualitative feedback on AI-generated clinical
        content for an ambient session. You can submit feedback once per entity
        type per session.
      parameters:
        - name: session_id
          in: path
          description: >-
            UUID for the ambient session you are rating. Use the same
            `ambient_session_id` from Create Ambient Session.
          required: true
          schema:
            type: string
          example: session_abc_123
        - name: entity
          in: path
          description: >-
            Entity type you are rating. For ambient sessions, use `content` for
            generated clinical note content. You can submit feedback once per
            entity type per session.
          required: true
          schema:
            type: string
          example: content
        - $ref: '#/components/parameters/ProviderIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/controllers.FeedbackRequest'
        required: true
      responses:
        '201':
          description: Resource created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.FeedbackResponse'
        '400':
          description: Bad request. The request body or parameters failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized - Authentication failed or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '403':
          description: Forbidden - Access denied to the requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ForbiddenError'
        '404':
          description: Not found. The session, encounter, or resource ID does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.NotFoundError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.InternalServerError'
      security:
        - SukiTokenAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request POST \
              --url https://sdp.suki.ai/api/v1/ambient/session/<ambient_session_id>/<entity>/feedback \
              --header 'Content-Type: application/json' \
              --header 'sdp_suki_token: <sdp_suki_token>' \
              --header 'sdp_provider_id: <sdp_provider_id>'
components:
  parameters:
    ProviderIdHeader:
      name: sdp_provider_id
      in: header
      description: >-
        **Optional** - Stable identifier for the active provider. Omit for
        standard partners whose `partner_token` identifies the user.
        **Required** for Bearer partners and Single Auth Token authentication
        where multiple providers share one `partner_token`. Use the same
        `provider_id` you sent on Login or Register.
      required: false
      schema:
        type: string
        example: provider-123
  schemas:
    controllers.FeedbackRequest:
      type: object
      required:
        - ratingFeedback
      properties:
        ratingFeedback:
          type: object
          required:
            - min_rating
            - max_rating
            - rating
          properties:
            min_rating:
              type: integer
              description: >-
                Minimum rating value - you can choose any number as the minimum
                i.e 0 and above
              example: 0
            max_rating:
              type: integer
              description: >-
                Maximum rating value - you can choose any number that is greater
                than the minimum value
              example: 1
            rating:
              type: integer
              minimum: 0
              maximum: 1
              description: The actual rating given within the min-max range
              example: 1
          description: >-
            Required quantitative rating. Set `min_rating`, `max_rating`, and
            `rating` to define the scale and score.
        qualitative_comments:
          type: string
          maxLength: 2000
          description: >-
            **Optional** - Qualitative feedback comments for detailed insights.
            Maximum 2000 characters allowed.
          example: The generated content was accurate and helpful
      description: >-
        Quantitative rating and optional qualitative comments for the specified
        entity.
    controllers.FeedbackResponse:
      type: object
      properties:
        feedback_id:
          type: string
          description: Unique identifier for the submitted feedback
          example: fb_abc123def456-789xyz-012uvw
      description: Response body for successful feedback submission
    controllers.BadRequestError:
      type: object
      properties:
        code:
          type: integer
          example: 400
          description: HTTP status code for the error.
        message:
          type: string
          example: invalid request
          description: Human-readable description of the validation or request error.
      description: Error response when the request fails validation.
    controllers.AuthenticationError:
      type: object
      properties:
        code:
          type: integer
          example: 401
          description: HTTP status code for the error.
        message:
          type: string
          example: invalid token
          description: Human-readable description of the authentication failure.
      description: Error response when authentication fails.
    controllers.ForbiddenError:
      type: object
      properties:
        code:
          type: integer
          example: 403
          description: HTTP status code for the error.
        message:
          type: string
          example: forbidden
          description: Human-readable description of the authorization failure.
      description: Error response when the caller lacks permission.
    controllers.NotFoundError:
      type: object
      properties:
        code:
          type: integer
          example: 404
          description: HTTP status code for the error.
        message:
          type: string
          example: not found
          description: Human-readable description of the missing resource.
      description: Error response when the requested resource was not found.
    controllers.InternalServerError:
      type: object
      properties:
        code:
          type: integer
          example: 500
          description: HTTP status code for the error.
        message:
          type: string
          example: internal server error
          description: Human-readable description of the server error.
      description: Error response when the server encounters an unexpected error.
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token for the authenticated provider. Obtain this by calling
        Login or Register with a valid `partner_token`. Pass the `suki_token`
        value from the JSON response as the `sdp_suki_token` header on REST
        requests and non-browser WebSocket upgrades. Browser WebSocket clients
        pass the token in `Sec-WebSocket-Protocol` instead. Tokens expire after
        one hour; call Login again to refresh.

````