Search

Guide

Using the Helios API

The Helios API

Here we'll take a step back and explain the fundamentals of the Helios API in some more detail.

A REST API

First of all, the Helios API is a REST API, meaning it follows certain standards or best practices.

At its heart are resources, which are exposed, created and managed through the API. An example of a resource is a Model Run, which is a single execution of the Helios wellness model.

Resources are specified in the URL of the endpoint that you call on the API. All endpoints start with a root path of:

When each endpoint is called, an HTTP "method" (or "verb") must be supplied too. The combination of method and URL determine what function of the API is being invoked. Examples are:

  • 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

Some endpoints require a request body and all endpoints return a response body. Both of these use JSON.

Errors are indicated using HTTP response status codes - for example:

  • 401 (Unauthorized) if something is wrong with your Activation Key in the request

  • 410 (Bad Request) or 422 (Unprocessable Entity) if your request is incorrectly formed

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.

Some endpoints accept or return timestamp fields in their JSON payloads. Unless stated otherwise these are in ISO 8601 format:

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'

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?