Initiate a Session

1.0 Session

A session comprises exactly two key interactions that result in a single prediction:

1. First, you submit an audio file of the recording of the patient’s voice to KV.

2. Next, you receive a response containing a prediction.

You will need to initiate a session with KV in order to proceed to the next steps of submitting an audio file with the patient’s voice sample and receiving a prediction associated with that sample. Optionally submit patient demographic information including age, gender, race, ethnicity, the patient's 5-digit US zipcode of residence, English language proficiency, and body weight before sending an audio file for prediction. Kintsugi will associate the metadata with the audio file and prediction.

When you successfully initiate a session with KV, the KV API generates and returns to you in its response a unique session identifier that you will then use in a subsequent request to Get a Prediction from KV.

NOTE
A single session can only ever be associated with a single prediction. In other words, you will need to create a new session for every new prediction.

To initiate a session, use the Initiate endpoint as follows:

2.0 Endpoint

POST /initiate

2.1 Full URL

https://api.kintsugihealth.com/v1/initiate

3.0 Request

3.1 Headers

NAME

VALUE

NOTE

user_id
*required

application/json

--

Content type

application/x-www-form-urlencoded

--

X-API Key

Your API Key

This is your API key. To learn how to obtain your API key, please refer to the Getting Started section.

3.3 Body

NAME

VALUE

NOTE

user_id
*required

application/json

Use this identifier to identify and track the patient. You are free to use any identifier you choose – this helps you track the patient and their associated KV predictions for your documentation.

is-initiated
*required

Boolean

+

True

+

False

Use this flag to indicate to KV whether the patient provides consent for KV to process their voice recording. Please refer to the Regulatory and Compliance section for information about collecting the patient's consent.

+

Use True to indicate that the patients has given their consent.

+

Use False to indicate that the patient has not given their consent.

Note that if the user does not provide their consent and the flag is “false" - then a session is not created, and no further processing occurs until the patient gives their consent and the user creates a new session with the flag set to "true".

age

Integer

Use this field to provide the patient's age at the time of audio collection as optional metadata for association with the patient's audio file and prediction. Integer must be >0.

gender

Enum

+

Female

+

Male

+

Other

+

Prefer Not to Specify

+

Transgender Female

+

Transgender Male

Use this field to provide the patient's gender identity as optional metadata for association with the patient's audio file and prediction.

race

Enum

+

American Indian or Alaskan Native

+

Asian

+

Black or African American

+

Native Hawaiian or Pacific Islander

+

Prefer Not to Specify

+

Two or More Races

+

White

Use this field to provide the patient's racial identity as optional metadata for association with the patient's audio file and prediction.

ethnicity

Enum

+

Hispanic, Latino, or Spanish Origin

+

Not Hispanic, Latino, or Spanish Origin

Use this field to provide the patient's age at the time of audio collection as optional metadata for association with the patient's audio file and prediction. Integer must be >0.

zipcode

String

Use this field to provide the patient's 5-digit US zipcode of current residence as optional metadata for association with the patient's audio file and prediction. String pattern: ^[0-9]{5}$.

language

Boolean

+

True

+

False

Use this field to indicate if the patient's first language is English as optional metadata for association with the patient's audio file and prediction.

weight

Integer

Use this field to provide the patient's most recent body weight in pounds (lbs) as optional metadata for association with the patient's audio file and prediction. Integer must be > 0.

4.0 Responses

NAME

VALUE

NOTE

200

{  "session_id": "string"}

KV processes the request successfully and successfully initiates a session.

401

{  "error": "invalid_api_key"}

KV fails to authenticate the request. The API Key is invalid, and you are not an authenticated user. Ensure you provide an API key, not an activation token or other identifier.

403

{  "error": "unauthorized_account"}

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your request will be processed accordingly.

404

{  "error": "path_not_found"}

KV is unable to find the requested resource.

422

{  “error”: “unsupported_metadata_spec”:}

KV is unable to use the parameters sent in the request body. More specifically, the parameters are either empty or invalid. Please use the following error responses to address the specific problem. The error is customized to the specific parameter that is either empty or valid.

For instance, if your request does not have “user_id” in the body, then you will get the following response:

{
  "error": "unsupported_metadata_spec",
  "context": {
    "user_id": "unprovided"
  }
}

If KV expects the "zipcode" to be 5 characters long and finds it to be 6 instead, then KV gives the following response:

{
  "error": "unsupported_metadata_spec",
  "context": {
    "user_id": "malformed"
  }
}

5.0 Example

To initiate a session with an API Key “abcdefghijklmnopqrstuvwxyz0123456789”, for a user with user_id, “loreum123”, who has given their consent to KV to process their voice recording, use the following curl command:

REQUEST

CURL
curl -X 'POST' \
'https://api.kintsugihealth.com/v1/initiate' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'X-API-Key: <your_api_key>' \
  -d 'gender=male&zipcode=12345&user_id=test&race=white&is_initiated=true&weight=100&language=true&ethnicity=Hispanic%2C%20Latino%2C%20or%20Spanish%20Origin&age=20'

responses

CODE
BODY
200

{ "session_id": "ipsum345" }

Once you successfully initiate a session, you can then Get a Prediction with KV.

Get a Prediction

1.0 Predictions

KV is able to ingest a WAV audio file of the recording of the patient speaking in a single session and respond with its prediction about the presence of current symptoms of depression from their vocal features. KV supports binary predictions for the presence or absence of current significant symptoms of depression, as well as a 3-class model to stratify patients by symptom severity.



Please refer to the Audio File Specification section for detailed information about the requirements of the audio file. Different audio file types have features that can influence KV’s ability to predict signs of depression. Thus, the file must adhere to the minimum recommended standards to generate an accurate prediction. To learn how to help Kintsugi continue to ensure the accuracy of our device - please refer to the Submit Feedback section. 

Once you are ready with an audio file that meets recommended standards, use the Predict endpoint to get a prediction as follows:

NOTE
KV currently supports ingesting a pre-recorded audio file. Most commonly, as a pre-onboarding checklist item, a patient sends a voice memo describing why they are scheduling a visit along with any pre-existing conditions to note to the practitioner, typically no more than a few minutes in length. KV receives the voice memo with consent from the patient to get a prediction. While this is the most common workflow in which clients use KV today, it will soon support the ability to ingest streaming audio and predict in real-time. Stay tuned!

KV offers a binary prediction flow to detect the presence or absence of current symptoms consistent with depression.

2.0 Endpoint

POST /predict/server/depression/binary

2.1 Full URL

https://api.kintsugihealth.com/v1/predict/server/depression/binary

To help clinicians allocate their limited resources, KV's severity prediction flow also stratifies the magnitude of the patient's current depressive symptoms into one of three categories: No to Mild, Mild to Moderate, and Moderate to Severe.

2.0 Endpoint

POST /predict/server/depression/severity

2.1 Full URL

https://api.kintsugihealth.com/v1/predict/server/depression/severity

3.0 Request

3.1 Headers

NAME

VALUE

NOTE

Accept

application/json

--

Content-Type

multipart/ form-data

--

X-API Key

Your API Key

This is your API key. To learn how to obtain your API key, please refer to the Getting Started section.

3.2 Parameters

None

3.3 Body

NAME

VALUE

NOTE

file

String

Use this field to upload binary data from the single-channel WAV 44.1 kHz audio file uploaded using a multipart/form-data POST action.

session_id

Boolean

This is the session identifier that you receive when you successfully initiate the session using the “Initiate” endpoint.

4.0 Responses

NAME

VALUE

NOTE

200

{   "name":
"no_to_mild",   
 "value": 0, }

KV processes the request successfully and returns a positive prediction for an audio file with sufficient signal consistent with current significant symptoms of depression.

201

{  
 "name":"mild_to_moderate",    
 "value": 1,
}

KV processes the request successfully and returns a prediction for an audio file with sufficient signal consistent with mild to moderate current symptoms of depression.

201

{   "name": "moderate_to_severe",   "value": 2, }

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your request will be processed accordingly.

401

{   "error": "invalid_api_key" }

KV fails to authenticate the request. The API Key is invalid, and you are not an authenticated user. Ensure you provide an API key, not an activation token or other identifier.

403

{   "error": "unauthorized_account" }

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your requests will start going through.

404

{   "error": "nonexistent_initiation" }

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your requests will start going through.

409

{   "error": "existent_session" }

The request conflicts with a previous request. The session ID was used with a previous precision request. Use a unique session ID for each prediction request.

422

{   "error": "unsupported_audio_spec" }

The specification of the provided audio does not match the expected specification. Please refer to the Audio File Specification section for detailed information about the requirements of the audio file.

422

{   "error": "unstandard_audio" }

The provided audio file is not a WAV file. Double check that it is an audio file and a WAV file instead of an MP3 or other audio format. Please refer to the Audio File Specification section for detailed information about the requirements of the audio file.

422

{   "error": "insufficient_audio_length" }

The provided audio file does not contain at least 30 seconds of voice. While it may be longer than 30 seconds, removing silence and non-voice brings the length below 30 seconds. Please ensure that audio files have sufficient voice content. Please refer to the Audio File Specification section for detailed information about the requirements of the audio file.

5.0 Example

To get a prediction for a session with id, “ipsum345” and a file called “dolor678.wav”, use the following curl command:

REQUEST

CURL
curl -X 'POST' \   
 'https://api.kintsugihealth.com/v1/predict/server/depression/severity' \   
 -H 'accept: application/json' \   
 -H 'Content-Type: multipart/form-data' \   
 -H 'X-API-Key: <your_api_key>' \   
 -F 'file=@dolor678.wav;type=audio/wav' \   
 -F 'session_id=ipsum345'

responses

CODE
RESPONSE BODY
201

{"data": {"name": "mild_to_moderate", "value": 1}}

Learn how to ensure your patients' voice samples meet our Audio Specifications.

Audio File Specification

KV ingests a single recorded voice sample of a patient speaking and outputs a single prediction based on vocal features predicted using machine learning technology. Different audio file types (e.g., MP3 or M4A) and other audio characteristics, such as sampling rate, can impact the amount of information, in the form of sound waves, that is available. Because KV evaluates signals or features at specific frequencies, compressing audio files, capturing them in a noisy environment, or at a low frequency can degrade important information necessary to make accurate predictions using KV. To ensure that KV provides your clinical team with the most accurate insights, we have set up automatic audio guardrails that will prevent prediction issuing for audio files that fail to meet any of the audio specifications outlined below:

SPECIFICATION

CRITERIA

DESCRIPTIONS

Type

WAV

WAV files minimize compression. Ideally, users record audio files in WAV format to capture the vocal signal appropriately. Users can convert audio files to WAV format if they originally recorded audio in a different file format.

Sample Rate

8 kHz

This is the session identifier that you receive when you successfully iThe sample rate refers to the number of audio samples recorded per second. The higher the sample rate, the more vocal signals will be captured, which may improve KV’s accuracy. The 8 kHz represents the minimum sample rate. Higher sample rates are accepted and recommended when possible.nitiate the session using the “Initiate” endpoint.

Channel

Channel Separated (Single Channel)

Capture audio such that the voice of the medical professional and the voice of the patient are on a separate audio channel. The channel recording the patient’s audio is submitted. KV cannot distinguish between the patient and the medical provider.

Voice Content

30 seconds

KV requires sufficient vocal signal to make a reasonably reliable prediction. Patient speech content should be at least 30 seconds in duration. Speech content is distinct from audio file length. The uploaded file will likely exceed 30 seconds to meet this requirement.

To help us continue to improve our technology's performance, Submit Feedback.

Sample code of the complete flow


const axios = require('axios'); 
const FormData = require('form-data'); 
const fs = require('fs'); 

const URL_ROOT = "https://api.kintsugihello.com/" 
// Initiate endpoint URL.
const URL_INITIATE = new URL('/v1/initiate', URL_ROOT) 
// Predict endpoint URL. 
const URL_PREDICT = new URL('/v1/predict/server/depression/binary', URL_ROOT) 
// Feedback endpoint URL. 
const URL_FEEDBACK = new URL ('/v1/feedback/server/depression/binary', URL_ROOT) 

async function initiate(api_key) {
    console.log('Start initiate!')
    let data = new FormData();
    data.append('user_id', 'USER_ID');
    data.append('is_initiated', 'true');
    let config = {
        method: 'post',
        url: URL_INITIATE,
        headers: {
            'X-API-Key': api_key,
            ...data.getHeaders()
        },
        data: data
    };
    let response = await axios.request(config)
    console.log('Complete initiate! session_id: ' + response.data.session_id)
    return response.data.session_id
}

async function predict(session_id) {
    console.log('Start predict!')
    let data = new FormData();
    data.append('session_id', session_id);
    data.append('file', fs.createReadStream('Sub_PHQ0_GAD0_I.wav'));
    let config = {
        method: 'post',
        url: URL_PREDICT,
        headers: {
            ...data.getHeaders()
        },
        data: data
    };
    let response = await axios.request(config)
    console.log('Complete predict! data: ' + JSON.stringify(response.data))
}

async function feedback(session_id) {
    console.log('Start feedback!')
    let data = new FormData();
    data.append('session_id', session_id);
    // Available options of actual score are: true, false,
    // additional_consideration_required.
    // Feedback endpoint do not return any data.
    data.append('actual_score', 'true');
    let config = {
        method: 'patch',
        url: URL_FEEDBACK,
        headers: {
            ...data.getHeaders()
        },
        data: data
    };
    await axios.request(config)
    console.log('Complete feedback!')
}

async function main() {
    let session_id = await initiate("API_KEY")
    await predict(session_id)
    await feedback(session_id)
}

main().then((data) => {
    console.log("Finish!")
}).catch((error) => {
    console.log(error.message)
});


const axios = require('axios'); 
const FormData = require('form-data'); 
const fs = require('fs'); 

const URL_ROOT = "https://api.kintsugihello.com/" 
// Initiate endpoint URL.
const URL_INITIATE = new URL('/v1/initiate', URL_ROOT) 
// Predict endpoint URL. 
const URL_PREDICT = new URL('/v1/predict/server/depression/binary', URL_ROOT) 
// Feedback endpoint URL. 
const URL_FEEDBACK = new URL ('/v1/feedback/server/depression/binary', URL_ROOT) 

async function initiate(api_key) {
    console.log('Start initiate!')
    let data = new FormData();
    data.append('user_id', 'USER_ID');
    data.append('is_initiated', 'true');
    let config = {
        method: 'post',
        url: URL_INITIATE,
        headers: {
            'X-API-Key': api_key,
            ...data.getHeaders()
        },
        data: data
    };
    let response = await axios.request(config)
    console.log('Complete initiate! session_id: ' + response.data.session_id)
    return response.data.session_id
}

async function predict(session_id) {
    console.log('Start predict!')
    let data = new FormData();
    data.append('session_id', session_id);
    data.append('file', fs.createReadStream('Sub_PHQ0_GAD0_I.wav'));
    let config = {
        method: 'post',
        url: URL_PREDICT,
        headers: {
            ...data.getHeaders()
        },
        data: data
    };
    let response = await axios.request(config)
    console.log('Complete predict! data: ' + JSON.stringify(response.data))
}

async function feedback(session_id) {
    console.log('Start feedback!')
    let data = new FormData();
    data.append('session_id', session_id);
    // Available options of actual score are: true, false,
    // additional_consideration_required.
    // Feedback endpoint do not return any data.
    data.append('actual_score', 'true');
    let config = {
        method: 'patch',
        url: URL_FEEDBACK,
        headers: {
            ...data.getHeaders()
        },
        data: data
    };
    await axios.request(config)
    console.log('Complete feedback!')
}

async function main() {
    let session_id = await initiate("API_KEY")
    await predict(session_id)
    await feedback(session_id)
}

main().then((data) => {
    console.log("Finish!")
}).catch((error) => {
    console.log(error.message)
});


import requests

API_KEY = '<your api key>'
USER_ID = '<user_id from your system>'
VOICE_SAMPLE = "Sub_PHQ0_GAD0_I.wav"

# Create an HTTP Client. Provide authentication credentials.
session = requests.Session()
session.headers.update({"X-API-Key": API_KEY})

# Initiate session between the patient and a doctor.
initiate_resp = session.post(
    url="https://api.kintsugihealth.com/v1/initiate",
    data={"user_id": USER_ID, "is_initiated": True},
)
initiate_resp.raise_for_status()

# Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
session_id = initiate_resp.json()["session_id"]

# Make a prediction for the specified patient's voice sample.
with open(VOICE_SAMPLE, 'rb') as patient_voice_sample:
    prediction_resp = session.post(
        url="https://api.kintsugihealth.com/v1/predict/server/depression/binary",
        files={'file': patient_voice_sample},
        data={"session_id": session_id},
    )
    prediction_resp.raise_for_status()

# *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/2",
    json={"session_id": session_id, "actual_score": [1, 2]},
)
feedback_resp.raise_for_status()

# *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/9",
    json={"session_id": session_id, "actual_score": [1, 2, 3, 1, 2, 3, 1, 2, 3]},
)
feedback_resp.raise_for_status()

# *Binary: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/depression/binary",
    data={"session_id": session_id, "actual_score": "true"},
)
feedback_resp.raise_for_status()

print("The prediction was completed successfully!")


import requests

API_KEY = '<your api key>'
USER_ID = '<user_id from your system>'
VOICE_SAMPLE = "Sub_PHQ0_GAD0_I.wav"

# Create an HTTP Client. Provide authentication credentials.
session = requests.Session()
session.headers.update({"X-API-Key": API_KEY})

# Initiate session between the patient and a doctor.
initiate_resp = session.post(
    url="https://api.kintsugihealth.com/v1/initiate",
    data={"user_id": USER_ID, "is_initiated": True},
)
initiate_resp.raise_for_status()

# Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
session_id = initiate_resp.json()["session_id"]

# Make a prediction for the specified patient's voice sample.
with open(VOICE_SAMPLE, 'rb') as patient_voice_sample:
    prediction_resp = session.post(
        url="https://api.kintsugihealth.com/v1/predict/server/depression/severity",
        files={'file': patient_voice_sample},
        data={"session_id": session_id},
    )
    prediction_resp.raise_for_status()

# *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/2",
    json={"session_id": session_id, "actual_score": [1, 2]},
)
feedback_resp.raise_for_status()

# *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/9",
    json={"session_id": session_id, "actual_score": [1, 2, 3, 1, 2, 3, 1, 2, 3]},
)
feedback_resp.raise_for_status()

print("The prediction was completed successfully!")