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

Headers

sdp_provider_id

string

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.

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 June 12, 2026

User Feedback API

Send Notifications API

⌘I

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"
}

​Supported entity types

​Rating system

​Character limits

​Code examples

Authorizations

Headers

Path Parameters

Body

Response

Supported entity types

Rating system

Character limits

Code examples