Ambient Session User Feedback

POST

api

ambient

session

{session_id}

{entity}

feedback

cURL

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>'

import requests

url = "https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback"

payload = {
    "ratingFeedback": {
        "min_rating": 0,
        "max_rating": 1,
        "rating": 1
    },
    "qualitative_comments": "The generated content was accurate and helpful"
}
headers = {
    "sdp_suki_token": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {sdp_suki_token: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ratingFeedback: {min_rating: 0, max_rating: 1, rating: 1},
    qualitative_comments: 'The generated content was accurate and helpful'
  })
};

fetch('https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ratingFeedback' => [
        'min_rating' => 0,
        'max_rating' => 1,
        'rating' => 1
    ],
    'qualitative_comments' => 'The generated content was accurate and helpful'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "sdp_suki_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback"

	payload := strings.NewReader("{\n  \"ratingFeedback\": {\n    \"min_rating\": 0,\n    \"max_rating\": 1,\n    \"rating\": 1\n  },\n  \"qualitative_comments\": \"The generated content was accurate and helpful\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("sdp_suki_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback")
  .header("sdp_suki_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ratingFeedback\": {\n    \"min_rating\": 0,\n    \"max_rating\": 1,\n    \"rating\": 1\n  },\n  \"qualitative_comments\": \"The generated content was accurate and helpful\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["sdp_suki_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ratingFeedback\": {\n    \"min_rating\": 0,\n    \"max_rating\": 1,\n    \"rating\": 1\n  },\n  \"qualitative_comments\": \"The generated content was accurate and helpful\"\n}"

response = http.request(request)
puts response.read_body

{
  "feedback_id": "fb_abc123def456-789xyz-012uvw"
}

{
  "code": 400,
  "message": "invalid request"
}

{
  "code": 401,
  "message": "invalid token"
}

{
  "code": 403,
  "message": "forbidden"
}

{
  "code": 404,
  "message": "not found"
}

{
  "code": 500,
  "message": "internal server error"
}

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

For when to show rating UI in your product, once-per-entity rules, and product placement, refer to Give feedback on a clinical note guide for recommendations.

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

Within a single (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.

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.

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.

Character limits

qualitative_comments: Maximum 2000 characters.

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

Code examples

Python
TypeScript

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())

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);
}

Authorizations

sdp_suki_token

string

header

required

Suki access token (suki_token) from Login or Register. Expires after one hour.

Headers

sdp_provider_id

string

Optional for standard partners.

Required for:

Bearer authentication. Use the same provider_id returned by the Login or Register API.
Single Auth Token authentication. Include the same provider_id on every request as sdp_provider_id.

Example:

"provider-123"

Path Parameters

session_id

string

required

UUID for the ambient session you are rating. Use the same ambient_session_id from Create Ambient Session.

entity

string

required

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.

Body

application/json

Quantitative rating and optional qualitative comments for the specified entity.

ratingFeedback

object

required

Required quantitative rating. Set min_rating, max_rating, and rating to define the scale and score.

Show child attributes

qualitative_comments

string

Optional - Qualitative feedback comments for detailed insights. Maximum 2000 characters allowed.

Maximum string length: 2000

Example:

"The generated content was accurate and helpful"

Response

Resource created successfully.

Response body for successful feedback submission

feedback_id

string

Unique identifier for the submitted feedback

Example:

"fb_abc123def456-789xyz-012uvw"

Last modified on August 20, 2026

cURL

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>'

import requests

url = "https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback"

payload = {
    "ratingFeedback": {
        "min_rating": 0,
        "max_rating": 1,
        "rating": 1
    },
    "qualitative_comments": "The generated content was accurate and helpful"
}
headers = {
    "sdp_suki_token": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {sdp_suki_token: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ratingFeedback: {min_rating: 0, max_rating: 1, rating: 1},
    qualitative_comments: 'The generated content was accurate and helpful'
  })
};

fetch('https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ratingFeedback' => [
        'min_rating' => 0,
        'max_rating' => 1,
        'rating' => 1
    ],
    'qualitative_comments' => 'The generated content was accurate and helpful'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "sdp_suki_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback"

	payload := strings.NewReader("{\n  \"ratingFeedback\": {\n    \"min_rating\": 0,\n    \"max_rating\": 1,\n    \"rating\": 1\n  },\n  \"qualitative_comments\": \"The generated content was accurate and helpful\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("sdp_suki_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback")
  .header("sdp_suki_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ratingFeedback\": {\n    \"min_rating\": 0,\n    \"max_rating\": 1,\n    \"rating\": 1\n  },\n  \"qualitative_comments\": \"The generated content was accurate and helpful\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/ambient/session/{session_id}/{entity}/feedback")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["sdp_suki_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ratingFeedback\": {\n    \"min_rating\": 0,\n    \"max_rating\": 1,\n    \"rating\": 1\n  },\n  \"qualitative_comments\": \"The generated content was accurate and helpful\"\n}"

response = http.request(request)
puts response.read_body

{
  "feedback_id": "fb_abc123def456-789xyz-012uvw"
}

{
  "code": 400,
  "message": "invalid request"
}

{
  "code": 401,
  "message": "invalid token"
}

{
  "code": 403,
  "message": "forbidden"
}

{
  "code": 404,
  "message": "not found"
}

{
  "code": 500,
  "message": "internal server error"
}

Get Started

API References

Ambient Session User Feedback

Supported entity types

Rating system

Character limits

Code examples

Authorizations

Headers

Path Parameters

Body

Response

​Supported entity types

​Rating system

​Character limits

​Code examples

Authorizations

Headers

Path Parameters

Body

Response

Supported entity types

Rating system

Character limits

Code examples