Search

Guide

Using the Helios API

The Helios API

Let’s delve into the fundamentals of the Helios API. The Helios API is a REST API, adhering to standard best practices. It revolves around resources, such as a Model Run, representing a single execution of the Helios wellness model. These resources are specified in the URL of the API endpoint you call, all starting with the root path:

https://api.thymia.ai

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

HTTP Methods

When calling each endpoint, supply an HTTP "method" (or "verb"). The combination of the method and URL determines the API function being invoked. For example:

  • POST https://api.thymia.ai/v1/models/mental-wellness-activity to create a new Model Run

  • GET https://api.thymia.ai/v1/models/{model_run_id} to retrieve results of a existing Model Run

Request and Response Body

Some endpoints require a request body and all return a response body. Both of these use JSON. Errors are indicated using HTTP response status codes, such as 401 (Unauthorized) for issues with your Activation Key or 410 (Bad Request) and 422 (Unprocessable Entity) for incorrectly formed requests.

You can usually look at the response body to help debug your error, but unless stated otherwise don't programatically rely on the structure of an error response body.

Endpoints accepting or returning timestamp fields in their JSON payloads use the ISO 8601 format unless stated otherwise:

YYYY-MM-DDTHH:MM:SS+HH:MM<offset

Authentication

All requests to the Helios API must be authenticated. This is so we know who's making the request, and so we can restrict access to your resources to just you. For example, only you should be able to retrieve the results of a wellness check you previously submitted.

Authentication is performed by passing your Activation Key in the x-api-key HTTP header. You will have been emailed your key when you first signed up to a Helios plan.

Here's an example of supplying an Activation Key, using curl:

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.

It is important to keep your Activation Key secret and not to share it with anyone. If your key is accidentally leaked, contact us immediately at support@thymia.ai to revoke it and issue a new one.

Similarly, when building your Helios integration don't embed your Activation Key in any client-side code as you no longer have control over who can view and use it. Only use your key to call the Helios API in code running on the backend that you control. For more details about structuring your integration see our full guide.

Where next?