# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/automation-overview/rest-api/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.