# 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 <a href="#what-you-can-do" id="what-you-can-do"></a>

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 <a href="#api-documentation" id="api-documentation"></a>

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 <a href="#prerequisites" id="prerequisites"></a>

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

```shell
pip install requests
```

Verify your Python installation:

```shell
python --version
```

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

### Create an Authentication Token <a href="#create-an-authentication-token" id="create-an-authentication-token"></a>

**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 <a href="#make-your-first-api-call" id="make-your-first-api-call"></a>

#### Python <a href="#python" id="python"></a>

Store your token as an environment variable:

```shell
# Linux/Mac
export VH_API_TOKEN=your_token_value

# Windows
set VH_API_TOKEN=your_token_value
```

List all projects in your account:

```python
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:

```shell
python test.py
```

#### cURL <a href="#curl" id="curl"></a>

For quick testing without a full script:

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

#### Expected Response <a href="#expected-response" id="expected-response"></a>

```json
{
  "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 <a href="#next-steps" id="next-steps"></a>

Explore practical API automation examples:

* [Auto-fetch repository changes](https://docs.valohai.com/automation-overview/rest-api/examples/auto-fetch-repository-on-push)
* [Trigger executions when new S3 data arrives](https://docs.valohai.com/automation-overview/rest-api/examples/launch-job-on-new-s3-data)
* [Query and rerun failed executions](https://docs.valohai.com/automation-overview/rest-api/examples/fetch-failed-executions)
* [Implement retry logic for connection errors](https://docs.valohai.com/automation-overview/rest-api/examples/retry-after-connection-error)

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