Search

Guide

Getting Started

Getting started

Embark on a seamless integration journey with Helios to enhance the wellbeing of your users. This guide is crafted to navigate you through your first interaction with the Helios API. By the end of this section you'll have successfully made an API call, completed a thymia activity and retrieved wellness results for your users.

Sign up

If you don't already have an Activation Key for Helios, please sign up now to a plan. You'll receive an email with your Activation key granting you access to the Helios API.

Multi-Region Support

If you have requested for your data to be stored in a specific region, then you will need to adjust the root path of your API requests based on your desired locale.

  • Canada - https://ca.api.thymia.ai/

  • United States - https://us.api.thymia.ai/

Make your first API call

You can make calls to the Helios API from any scripting or programming language that supports HTTP. As a starting point you can use the command line tool curl to make your first API call.

Execute the following command, replacing your_key_here with your Activation Key:

curl -H 'x-api-key: your_key_here'

Requested to have your data stored in a specific region? See our Multi-Region Support page.

Upon successful execution, you’ll receive a simple JSON object as the response, containing your unique customer number. This example demonstrates the use of the x-api-key header, which must be included in all your API requests - see our in-depth API guide for more details.

Encountered an issue? If your API call didn’t succeeded, rerun the curl command in verbose mode to diagnose the problem, or contact our support team:

curl -v -H 'x-api-key: your_key_here'

Requested to have your data stored in a specific region? See our Multi-Region Support page.

Try the API playground

curl is great but for experimenting with the Helios API you may find our interactive API Playground easier. This lets you call any endpoint of the API without writing any code.

To start with, click on the Authorize button near the top right. This will open a dialog into which you can enter your Activation Key:

One you've entered your key, click Authorize again and then close the dialog. The API Playground will now remember the key for your session and add it to all requests you make to the Helios API.

Now let's call the same /v1/account endpoint we called from curl. Scroll down until you see the Account section, then expand the endpoint so you can see a Try it out button. Click that and you should see a new Execute button:

Click Execute and the endpoint will be called. Scroll down slightly and you should see the same JSON response body you received from your earlier curl call.

Note that the API Playground is not a separate testing or sandbox environment - every API call you make in the Playground is calling the Helios API and you are interacting with your real data.

Also any model runs you request through the Playground count towards your usage - although see the FAQs for details of flexible usage we give you while you're starting out with Helios.

Complete a thymia activity

Now we'll call an endpoint that does something useful. Scroll back up and find the /v1/models/mental-wellness-activity endpoint. Again, expand the endpoint and click Try it out:

This is the endpoint you would use to begin the process of running the Helios wellness model, making use of the Thymia Activity Plugin to capture a recording of your users.

Note that this endpoint is a POST call because it will be creating a new resource in Helios (a new mental wellness model run). The previous /v1/account endpoint was a GET call because it retrieved information about an existing resource (your account record).

This endpoint requires several fields to be passed in the JSON request - for example, a unique label for your user and their year of birth. We'll explain more about these in the guide to building your integration, but for now you can use the example values the Playground supplies.

Click Execute and then scroll down to see the result of calling this endpoint. You should see a JSON response similar to this:

{
  "id": "ddebd75b-99b3-42b4-ac65-5ce852c688e9",
  "activityLink": "https://app.thymia.ai/access?token=aef9bb3f-ec08-44ad-8888-c1929973f9ec-au"
}

The API Playground also shows you the curl call that would have made the API request you just performed. This can be useful for learning and debugging when building your integration.

The id field is a unique identifier for the new Model Run that was created for you. We'll use this shortly to retrieve results of the wellness model.

The activityLink field is a URL that you would usually embed in your website or app. For now though, copy this URL and paste into your browser. You should see an intro screen similar to this:

This is what your users would see when using the Thymia Activity Widget. Click Start and you'll be taken to some checks to test your device's ability to capture audio or video. Once you complete the checks you'll be presented with a simple activity that you can perform.

After you've spoken for at least 30 seconds, complete the activity and you should end at a screen like this:

In a real integration you would detect the activity has completed and take your users somewhere else - possibly to then poll the Helios API until wellness results are available - but for now you can close this page.

Get your wellness results

Now the activity has been completed the wellness model will be automatically invoked with the recording we captured. In order to retrieve the results you can call another endpoint - /v1/models/mental-wellness/{model_run_id}. This endpoint must be given the id of the Model Run in its URL; this will be the id field returned earlier.

Find the new endpoint in the API Playground and, as usual, expand it and click Try it out:

Before you can execute this endpoint you have to enter the id of your Model Run in the required input box. Then click Execute.

The model may not have completed yet, in which case you will receive a response looking something like this:

{
  "id": "ddebd75b-99b3-42b4-ac65-5ce852c688e9",
  "createdAt": "2023-09-15T15:18:07.637267+00:00",
  "status": "RUNNING",
  "runAt": "2023-09-15T15:19:25.423603+00:00",
  "userLabel": "575da5a9-c84c-442b-858d-b947108f0935",
  "activityType": "read-aloud"
}

Note the value of the status field - RUNNING means the model is still running. If this is the case, wait a few seconds and try calling the endpoint again.

Soon you should receive results looking similar to this, with the status field saying COMPLETE_OK:

{
  "id": "ddebd75b-99b3-42b4-ac65-5ce852c688e9",
  "createdAt": "2023-09-15T15:18:07.637267+00:00",
  "status": "COMPLETE_OK",
  "runAt": "2023-09-15T15:19:25.423603+00:00",
  "completedAt": "2023-09-15T15:19:45.423603+00:00",
  "userLabel": "575da5a9-c84c-442b-858d-b947108f0935",
  "results": {
    "sections": [
      {
        "startSecs": 0,
        "finishSecs": 28.6,
        "transcript": "The North Wind and the Sun had a quarrel ...",
        "distress": {
          "value": 0.333
        },
        "stress": {
          "value": 0.333
        },
        "exhaustion": {
          "value": 0.333
        },
        "sleepPropensity": {
          "value": 0.333
        },
        "lowSelfEsteem": {
          "value": 0.333
        },
        "mentalStrain": {
          "value": 0.333
        }
      }
    ]
  },
  "activityType": "read-aloud"
}

Note that the wellness result you receive in this simple test will not be accurate as we didn't modify any of the default values when we created the Model Run (for example we used a default for year of birth).

If you're getting back results where the status field is COMPLETE_ERROR then something went wrong during model execution. Check the errorReason field for the cause. The most common cause is that the user didn't talk for long enough for the model to work - for example:

{
  "id": "ddebd75b-99b3-42b4-ac65-5ce852c688e9",
  "createdAt": "2023-09-15T15:18:07.637267+00:00",
  "status": "COMPLETE_ERROR",
  "runAt": "2023-09-15T15:19:25.423603+00:00",
  "completedAt": "2023-09-15T15:19:34.711235+00:00",
  "errorReason": "Recording supplied is too short. Please supply a recording containing at least 20 seconds of speech and that is under 3 minutes in length",
  "userLabel": "575da5a9-c84c-442b-858d-b947108f0935",
  "errorCode": "ERR_RECORDING_TOO_SHORT",
  "activityType": "read-aloud"
}

Congratulations!

Well done - you've now made several calls to the Helios API and executed your first run of the wellness model. Hopefully you're beginning to get familiar with calling the API and using the API Playground.

A real integration will obviously involve some code instead of clicking interactively in the Playground, but the core concepts are the same:

  • Call the Helios API to create a new Model Run

  • Present your users with the activity link and let them complete their activity

  • Call the API again to retrieve results

Where next?