Valohai API basics

In this tutorial, we will use the Valohai API to login and fetch a list of projects.


You can use any programming language you want to make HTTP requests.

In this tutorial we will be using Python 3 (version 3.4+ recommended). Installing Python and Pip is outside the scope of this tutorial, but a good place for information is

To validate your enviroment, open a terminal and run:

python --version

We also need to install the requests library to make HTTP requests:

pip install requests

Get an authentication token

Store your token in a secure location

The generated token is personal and it gives you access to Valohai features through your account. You might want to save the token in a local environment variable, a configuration file or a database.

Don’t include it directly in your version controlled files.

Getting auth token from the Valohai UI.

Make an API request

Let’s take the above code and extend it with another request.

We will fetch a list of all projects accessible from this user account.

import requests
import json
import os

# Get the Valohai API token you created earlier.
# Here it has been stored in a local environment variable.
# Remember to follow your organization's security standards when handling the token.
auth_token = os.environ['VH_API_TOKEN']
headers = {'Authorization': 'Token %s' % auth_token}

resp = requests.get('', headers=headers)

print(json.dumps(resp.json(), indent=4))

Save the code as and run it again with python

You should get a response like the one below:

    "count": 1,
    "next": null,
    "previous": null,
    "results": [
            "id": "015f25c1-0101-1010-fefe-a0a0a0a0a0a0",
            "name": "my-project",
            "description": "",
            "owner": {
                "id": 1337,
                "username": "myusername"
            "ctime": "2017-10-16T15:16:19.230872Z",
            "mtime": "2017-10-16T15:16:19.230895Z",
            "url": "",
            "urls": {
                "display": "",
                "display_repository": ""
            "execution_count": 0,
            "last_execution_ctime": null

Next steps

Next step is to parse it using your favorite parser and use the data to for amazing things!

The rest of the API is documented here, you must be logged in to read them: