Getting Started with the REST API

Build custom integrations, trigger executions from CI/CD pipelines, sync training metadata to internal dashboards, or programmatically manage your entire ML workflow.

What You Can Do

The Valohai REST API gives you full programmatic control:

• Trigger executions from external systems or CI/CD workflows

• Query execution metadata for custom analytics and monitoring

• Manage projects and their configurations

• Download outputs and artifacts programmatically

• Monitor pipeline status and retrieve logs

API Documentation

The interactive API documentation is available in your Valohai environment:

• API Explorer: https://app.valohai.com/api/v0/

• API Docs: https://app.valohai.com/api/docs/

💡 Self-hosted installations use your custom domain, e.g., https://youraddress/api/v0/

Prerequisites

This guide uses Python 3.8+ for examples. You'll also need the requests library:

pip install requests

Verify your Python installation:

python --version

💡 You can use any programming language that makes HTTP requests. The API accepts standard REST calls.

Create an Authentication Token

To generate your token:

1. Click on "Hi, <username>!" in the top-right corner

2. Go to My Profile → Authentication

3. Click Manage Tokens and scroll to the bottom

4. Click Generate New Token

5. Copy the token immediately — it's only shown once

⚠️ Keep your token safe. This token grants full access to your Valohai account. Store it securely in an environment variable, configuration file, or secrets manager. Never commit tokens to version control.

Make Your First API Call

Python

Store your token as an environment variable:

# Linux/Mac
export VH_API_TOKEN=your_token_value

# Windows
set VH_API_TOKEN=your_token_value

List all projects in your account:

import requests
import json
import os

# Retrieve your authentication token
auth_token = os.environ["VH_API_TOKEN"]
headers = {"Authorization": f"Token {auth_token}"}

# Fetch all projects
resp = requests.get("https://app.valohai.com/api/v0/projects/", headers=headers)
resp.raise_for_status()

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

Save as test.py and run:

python test.py

cURL

For quick testing without a full script:

curl -H "Authorization: Token YOUR_TOKEN_HERE" https://app.valohai.com/api/v0/projects/

Expected Response

{
  "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": "https://app.valohai.com/api/v0/projects/015f25c1-0101-1010-fefe-a0a0a0a0a0a0/",
      "urls": {
        "display": "https://app.valohai.com/p/myusername/my-project/",
        "display_repository": "https://app.valohai.com/p/myusername/my-project/settings/repository/"
      },
      "execution_count": 0,
      "last_execution_ctime": null
    }
  ]
}

Next Steps

Explore practical API automation examples:

• Auto-fetch repository changes

• Trigger executions when new S3 data arrives

• Query and rerun failed executions

• Implement retry logic for connection errors

Browse the full API reference at https://app.valohai.com/api/docs/ for all available endpoints and parameters.