Welcome to the Hivelocity API Quickstart Guide! As developers, we know how powerful APIs can be. In fact our entire company's infrastructure runs on a robust set of internal and external APIs. We know how important it is to be able to quickly get up and running with a new API, so this guide will walk you through the process needed to quickly deploy your first Instant Dedicated Servers using the Hivelocity Bare Metal Cloud API.

API Overview

The Hivelocity API allows you to purchase, deploy, and manage your Bare Metal machines and network resources within any Hivelocity data center in a straightforward, easy to use way using typical HTTP requests.

The endpoints conform to the OpenAPI Spec and we do our best to document them as thoroughly as possible. The docs and supporting tools are designed to allow easy access and modification of your infrastructure with minimal setup.

All API calls are authenticated by your API Keys in the X-API-KEY header.

Prereqs

This guide assumes you have completed the necessary steps to deploy a server through our API. If not, follow the 4 simple steps below:

1. Create an account in the Portal.
2. Retrieve your API Keys.
3. Add a Payment Method.
4. Complete Account Verification.

📘

Having trouble getting started?

If you have trouble completing the prereqs, open a chat or send an email to [email protected] and our team would be happy to help.

Deploy a Server

Step 0: Setting $API_KEY

This tutorial will be using curl commands via the command line. If you'd like to be able to copy-paste the curl commands in this tutorial, you will have to set your API Keys as the $API_KEY environment variable. To set your the environment variable, run the following command after replacing YOUR_API_KEY_HERE with your Hivelocity API Key:

export API_KEY=YOUR_API_KEY_HERE

Step 1: Choose your server

First, you need to select the configuration you want to deploy and your desired locations. We offer more configurations and more locations than any other bare metal cloud provider in the world, so you have a lot to choose from.

To get a list of available configurations - which we call products - and their respective locations - which we call facilities - make a GET request to the /inventory/product endpoint. This will return the available products along with the facility codesof where the servers are available. To read more about how to customize this request, see Facility Inventory.

curl -X 'GET' \
  'https://core.hivelocity.net/api/v2/inventory/product?location=MAIN&group_by=facility' \
  -H 'accept: application/json' \
  -H "X-API-KEY: $API_KEY"

From the returned products, choose one with a stock of available or limited and remember its product_id, as well as the location code. We will use them later. For example, you may want to deploy product id 501 into the facility with location code TPA2.

Step 2: Provision a Server

Now that you know the server you want, starting a provision is easy. Just make a POST request to the /bare-metal-devices endpoint with the following data in the request body:

• productId: The product ID you selected above
• locationName: The facility code you selected above
• osName: The name of one of the available Operating Systems options. For this demo we will use Ubuntu 20.x.
• hostname: A FQDN for your server. This can be whatever you'd like it to be.
• period: Your desired billing period. For this demo we will use hourly.

More optional deployment options are available such as SSH Keys, Cloud-init and Custom iPXE. See the API reference for a full list of options.

🚧

Account charges

Running this command will result in charges on your account. If you do not intend to keep the server for a long period of time, be sure to deploy with the hourly period selected in order to minimize charges.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-API-KEY: $API_KEY" \
    -d '{ \
        "productId": 501, \
        "locationName": "TPA1", \
        "osName": "Ubuntu 20.x", \
        "hostname": "test.hostname.com", \
        "period": "hourly" \
    }' \
https://core.hivelocity.net/api/v2/bare-metal-devices

This will have kicked off the provisioning process and the returned data will include an orderId. Remember this value for the last step.

Step 3: Access your Server

Now that your server provisioning has started, all that is left to do is to wait for it to finish and get your initial login credentials.

📘

Provisioning time

Most Linux based operating systems take ~7 minutes to provision. This time can be shorter or longer depening on the location, os, and other factors. Our engineering teams are constantly working to bring provisioning time down to 60 seconds or less.

Getting provisioning status

To get the status of your device's provisioning you need to check your Order by making a GET request to /order/YOUR_ORDER_ID . Replace YOUR_ORDER_ID with the orderId value you received from the previous step.

curl -X GET \
-H "Content-Type: application/json" \
-H "X-API-KEY: $API_KEY" \
https://core.hivelocity.net/api/v2/order/YOUR_ORDER_ID

When the returned status is complete your server will be done provisioning.

Getting your device ID and IP

Now that your provisioning is complete, it's time to retrieve your device and its login information. First, make a GET request to /device?orderId=YOUR_ORDER_ID endpoint and replace YOUR_ORDER_ID with the orderId value you received from the previous step.

curl -X GET \
-H "Content-Type: application/json" \
-H "X-API-KEY: $API_KEY" \
https://core.hivelocity.net/api/v2/device?orderId=YOUR_ORDER_ID

This will return your new device. Remember the id and primary_ip. You can learn more about initial credentials and IPs and Subnets on their respective pages.

Getting your initial ssh credentials

Now that you have the device's id, you can make a GET request to /device/YOUR_DEVICE_ID/initial-creds to retrieve the initial login information.

curl -X GET \
-H "Content-Type: application/json" \
-H "X-API-KEY: $API_KEY" \
https://core.hivelocity.net/api/v2/device/YOUR_DEVICE_ID/initial-creds

This will return the SSH user, password, and port.

Accessing your server over SSH for the first time

Using the primary_ip from above with these credentials, you will be able to access your server. Here is an example ssh command to access the server:

ssh YOUR_USER@YOUR_PRIMARYIP -p YOUR_PORT

When prompted to add the server into your list of known hosts, select yes, then enter your password when prompted.

Wrap Up

That's it! You've now deployed and accessed a server with the Hivelocity Bare Metal Cloud API. If you want more practice, or if you want to start over and try a different product, you may want to delete your server that you just created.