API overview and quickstart

Foundry's Spot API

Foundry currently supports managing Spot Instances, Storage Volumes, and SSH Keys via API. An equivalent API for Reservations is coming soon!

Prerequisites

1. Create an API key in the Foundry 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:

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:

import requests

response = requests.get(
    "https://api.mlfoundry.com/v2/projects",
    headers=headers
)
projects = response.json()

2. Creating a Storage Volume

Create a persistent storage volume for your instances:

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.mlfoundry.com/v2/volumes",
    headers=headers,
    data=volume_data
)
volume = response.json()

3. Add or generate SSH key

# 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.mlfoundry.com/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.mlfoundry.com/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:

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.mlfoundry.com/v2/spot/bids",
    headers=headers,
    data=bid_data
)
bid = response.json()

5. Monitor Your Instances

Track the status of your instances:

response = requests.get(
    "https://api.mlfoundry.com/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 Foundry 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.