# API overview and quickstart

Mithril currently supports managing Spot Instances, Reservations, Storage Volumes, and SSH Keys via API.

### Prerequisites

1. Create an API key in the [Mithril](https://app.mlfoundry.com/account/apikeys) console. Remember to keep this key safe.
2. Note down your API key - it will look like `fkey_...`

### Authentication

All API requests require authentication using your API key in the Authorization header:

```python
key = "fkey_your_key_here" 
headers = {
    "Authorization": f"Bearer {key}"
}
```

### Common Operations

#### 1. List Your Projects

First, get a list of projects you have access to:

```python
import requests

response = requests.get(
    "https://api.mithril.ai/v2/projects",
    headers=headers
)
projects = response.json()
```

#### 2.  Creating a Storage Volume

Create a persistent storage volume for your instances:

```python
volume_data = {
    "name": "my-storage",  # Must be lowercase alphanumeric with hyphens
    "project": "proj_...",  # Your project FID
    "disk_interface": "Block",  # "Block" or "File"
    "region": "us-central1-a",
    "size_gb": 100
}

response = requests.post(
    "https://api.mithril.ai/v2/volumes",
    headers=headers,
    data=volume_data
)
volume = response.json()
```

#### 3.  Add or generate SSH key

```python
# Use your existing public key
ssh_key_data = {
    "project": "proj_...",  # Your project FID
    "name": "my-ssh-key",
    "public_key": "ssh-rsa AAAA..." # Your public key content
}

response = requests.post(
    "https://api.mithril.ai/v2/ssh-keys",
    headers=headers,
    data=ssh_key_data
)

# OR generate a new private key
ssh_key_data = {
    "project": "proj_...",  # Your project FID
    "name": "my-ssh-key"
}

response = requests.post(
    "https://api.mithril.ai/v2/ssh-keys",
    headers=headers,
    data=ssh_key_data
)
ssh_key = response.json()["private_key"]
```

#### 4. Creating a Spot Bid

Place a bid for Spot instances:

```python
bid_data = {
    "project": "proj_...",  # Your project FID
    "region": "us-central1-a", # Check /v2/spot/availability
    "instance_type": "it_5ECSoHQjLBzrp5YM",  # Check /v2/spot/availability
    "limit_price": "$15.50",  # Maximum price per hour you're willing to pay
    "instance_quantity": 1,
    "name": "my-training-job",
    "launch_specification": {
        "volumes": ["vol_..."],  # Your volume FID
        "ssh_keys": ["ssh_..."],  # Your SSH key FID
        "startup_script": "#!/bin/bash\necho 'Hello World'"
    }
}

response = requests.post(
    "https://api.mithril.ai/v2/spot/bids",
    headers=headers,
    json=bid_data
)
bid = response.json()
```

#### 5. Monitor Your Instances

Track the status of your instances:

```python
response = requests.get(
    "https://api.mithril.ai/v2/instances",
    headers=headers,
    params={"project": "proj_..."}  # Your project FID
)
instances = response.json()["data"]
```

### Tips

* Use the `/v2/spot/availability` endpoint to check current Spot capacity and pricing
* You'll need to configure billing on the Mithril Console before you can place bids with the API

For more detailed information about specific endpoints and their parameters, refer to the [full API documentation.](/compute-api/compute-api-reference.md)


---

# 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.mithril.ai/compute-api/api-overview-and-quickstart.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.