Authentication

Most endpoints require a Bearer token in the Authorization header:

Authorization: Bearer $HYPERBOLIC_API_KEY

Endpoints

1. List Available Machines

Lists all available machines in the marketplace. This endpoint does not require a Bearer token in the Authorization header.

Endpoint

POST https://api.hyperbolic.xyz/v1/marketplace

Request Headers

Header	Value	Required
Content-Type	application/json	Yes

Request Body

{
    "filters": {}
}

Example Request

curl https://api.hyperbolic.xyz/v1/marketplace -X POST \
    -H "Content-type: application/json" \
    -d '{"filters":{}}'

Response Format

{
    "instances": [
        {
            "id": string,                // Node identifier
            "status": string,            // e.g., "node_ready"
            "hardware": {
                "cpus": [{
                    "hardware_type": "cpu",
                    "model": string,
                    "cores": number,
                    "virtual_cores": number
                }],
                "gpus": [{
                    "hardware_type": "gpu",
                    "model": string,
                    "clock_speed": number,
                    "compute_power": number,
                    "ram": number,
                    "interface": string
                }],
                "storage": [{
                    "hardware_type": "storage",
                    "capacity": number
                }],
                "ram": [{
                    "hardware_type": "ram",
                    "capacity": number
                }]
            },
            "instances": [{
                "id": string,
                "status": string,
                "hardware": [{
                    "gpu": {
                        "hardware_type": "gpu",
                        "model": string,
                        "ram": number
                    }
                }]
            }],
            "location": {
                "region": string
            },
            "network": {},
            "gpus_total": number,
            "gpus_reserved": number,
            "has_persistent_storage": boolean,
            "supplier_id": string,
            "pricing": {
                "price": {
                    "amount": number,
                    "period": string,
                    "agent": string
                }
            },
            "reserved": boolean,
            "cluster_name": string
        }
    ]
}

Important Fields

id: Node identifier (used as node_name in create instance)
cluster_name: Required for instance creation
gpus_total: Total GPUs available on the machine
gpus_reserved: Number of GPUs currently in use
reserved: Whether the machine is totally reserved or currently available
pricing.price.amount: Hourly cost in USD

Notes

Check reserved status and gpus_reserved vs gpus_total to determine availability
The status field indicates if the machine is ready for use (node_ready)
Each machine has different GPU configurations and pricing
Storage and RAM specifications are included in the hardware details

2. Create Instance

Endpoint

POST https://api.hyperbolic.xyz/v1/marketplace/instances/create

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer $HYPERBOLIC_API_KEY	Yes

Request Body

{
    "cluster_name": string,
    "node_name": string,
    "gpu_count": number,
    "image": {
        "name": string,
        "tag": string,
        "port": number
    }
}

Example Request

curl -X POST "https://api.hyperbolic.xyz/v1/marketplace/instances/create" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $HYPERBOLIC_API_KEY" \
    -d '{
        "cluster_name": "extrasmall-chamomile-duck",
        "node_name": "prd-acl-msi-02.fen.intra",
        "gpu_count": 1
    }'

Important Fields

cluster_name: Name of the cluster to create instance in
node_name: Name of the node (from List Available Machines endpoint)
gpu_count: Number of GPUs to allocate
image: Optional container configuration

Notes

The image object is optional
gpu_count must not exceed available GPUs on the node

3. List User Instances

Endpoint

POST https://api.hyperbolic.xyz/v1/marketplace/instances

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer $HYPERBOLIC_API_KEY	Yes

Example Request

curl -X GET "https://api.hyperbolic.xyz/v1/marketplace/instances" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $HYPERBOLIC_API_KEY"

4. View Instance History

Endpoint

GET https://api.hyperbolic.xyz/v1/marketplace/instances/history

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer $HYPERBOLIC_API_KEY	Yes

Example Request

curl -X GET "https://api.hyperbolic.xyz/v1/marketplace/instances/history" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $HYPERBOLIC_API_KEY"