Introduction

Welcome to ZeroSix.ai API. You can use our API to access ZeroSix.ai database, and retrieve information about products, orders and customers.

With our API, you can easily integrate our products, and place an order in your website. Detailed information on each endpoint is listed below.

ZeroSix.ai provides a client tool, making it easy for a provider to verify and test any requests to ZeroSix. Please see ZeroSix API Client on GitHub.

If you have any questions regarding using this API, or if you encountered with problem - please feel free to contact us here.

Formats

The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a 200 OK HTTP status. Some general information about responses:

Dates are returned in ISO8601 format: YYYY-MM-DDTHH:MM:SS or in timestamp format. You can choose.
Resource IDs are returned as integers.
Any decimal monetary amount, such as prices or totals, will be returned as strings with two decimal places.
Other amounts, such as item counts, are returned as integers.
Blank fields are generally included as null or emtpy string instead of being omitted.

Errors

Occasionally you might encounter errors when accessing the REST API. There are four possible types:

Error Code	Error Type
`400 Bad Request`	Invalid request, e.g. using an unsupported HTTP method
`401 Unauthorized`	Authentication or permission error, e.g. incorrect API keys
`404 Not Found`	Requests to resources that don't exist or are missing
`500 Internal Server Error`	Server error

Errors return both an appropriate HTTP status code and response object which contains a code, message and data attribute.

Parameters

Almost all endpoints accept optional parameters which can be passed as a HTTP query string parameter, e.g. GET /bookings?status=completed. All parameters are documented along each endpoint.

Authentication

REST API Keys

Pre-generated keys can be used to authenticate use of the REST API endpoints.

ZeroSix uses API keys to allow access to our API. For now, you can't automatically create your own API keys. If you want to start using our API, please contact us.

ZeroSix expects for the API keys to be included in all API requests to the server in a header that looks like the following:

OAuth

You must use OAuth 1.0a "one-legged" authentication to ensure REST API credentials cannot be intercepted by an attacker. Typically you will use any standard OAuth 1.0a library in the language of your choice to handle the authentication, or generate the necessary parameters by following the following instructions.

Example of using OAuth library to sign the request.

<?php
    /** Creating OAuth1.0 object
     * @param array $requestParams
     * @return OAuth
     */
    private function getOauth(array $requestParams)
    {
        $oauth = new OAuth($requestParams['consumerKey'], $requestParams['consumerSecret']);
        $oauth->setNonce($requestParams['nonce']);
        $oauth->setTimestamp($requestParams['timestamp']);
        $oauth->setVersion($requestParams['oauthVersion']);
        return $oauth;
    }
?>

You should use the OAuth library. Please see ZeroSix API Client examples on GitHub.

Creating a signature

Collect the request method and URL

First you need to determine the HTTP method you will be using for the request, and the URL of the request.

The HTTP method will be GET in our case.

The Request URL will be the endpoint you are posting to, e.g. https://www.zerosix.ai/wp-json/api/v1/products

Collect parameters

Collect and normalize your parameters. This includes all oauth_* parameters except for the oauth_signature itself.

These values need to be encoded into a single string which will be used later on. The process to build the string is very specific:

Percent encode every key and value that will be signed.
Sort the list of parameters alphabetically by encoded key.
For each key/value pair:
- Append the encoded key to the output string.
- Append the = character to the output string.
- Append the encoded value to the output string.
- If there are more key/value pairs remaining, append a & character to the output string.

When percent encoding in PHP for example, you would use rawurlencode().

When sorting parameters in PHP for example, you would use uksort( $params, 'strcmp' ).

Paramaters example:

oauth_consumer_key=abc123&oauth_signature_method=HMAC-SHA1

Create the signature base string

The above values collected so far must be joined to make a single string, from which the signature will be generated. This is called the signature base string in the OAuth specification.

To encode the HTTP method, request URL, and parameter string into a single string:

Set the output string equal to the uppercase HTTP Method.
Append the & character to the output string.
Percent encode the URL and append it to the output string.
Append the & character to the output string.
Percent encode the parameter string and append it to the output string.

Example signature base string:

GET&https%3A%2F%2Fwww.zerosix.ai%2Fwp-json%2Fapi%2Fv1%2Fproducts&oauth_consumer_key%3Dabc123%26oauth_signature_method%3DHMAC-SHA1

Generate the signature

Generate the signature using the signature base string and your consumer secret key with a & character with the HMAC-SHA1 hashing algorithm.

In PHP you can use the hash_hmac function.

HMAC-SHA1 or HMAC-SHA256 are the only accepted hash algorithms.

OAuth Tips

The OAuth parameters may be added as query string parameters or included in the Authorization header.
Note there is no reliable cross-platform way to get the raw request headers in our system, so query string should be more reliable in some cases.
The required parameters are: oauth_consumer_key, oauth_timestamp, oauth_nonce, oauth_signature, and oauth_signature_method. oauth_version is not required and should be omitted.
The OAuth timestamp should be the unix timestamp at the time of the request. The REST API will deny any requests that include a timestamp outside of a 15 minute window to prevent replay attacks.
Twitter has great instructions on generating signatures with OAuth 1.0a, but remember tokens are not used with this implementation.
Note that the request body is not signed as per the OAuth spec, see Google's OAuth 1.0 extension for details on why.
If including parameters in your request, it saves a lot of trouble if you can order your items alphabetically.

Products

The products API allows you to view individual or a batch of products.

Product properties

Product

Attribute	Type	Description
`id`	`integer`	Unique identifier for the product.
`title`	`string`	Product name
`slug`	`string`	Product slug
`description`	`string`	Product description
`permalink`	`string`	Product URL
`hourly-price`	`integer`	Product price
`currency`	`string`	Default is: `USD`.
`attributes`	`array`	Listed below.

Product Attributes

The options for the attribute is listed from the lower efficiency to higher.

Attribute	Description
`cpu`	Options are: `intel-celeron`, `amd-fx-8320`, `intel-i3`, `amd-ryzen-5`, `intel-i5`, `intel-i7`, `xeon-e5-2667`
`geo`	Options are: `asia-pacific`, `australia`, `europe`, `united-states` or `global` (Worldwide)
`gpu`	Options are: `nvidia-1060`, `nvidia-1060ti`, `nvidia-1070`, `nvidia-1070ti`, `nvidia-1080`, `nvidia-1080ti`, `nvidia-titan-xp`, `nvidia-tesla-v`.
`network-speed`	Options are: `50mbps`, `50-100mbps`, `100-200mbps`, `500-600mbps`
`ram`	Options are: `8gb`, `12gb`, `16gb`, `32gb`, `192gb`

List all Products

<?php

// Config params
$config = array(
    'consumer_key' => 'CONSUMER KEY',
    'consumer_secret' => 'SECRET KEY',
);

// Connect to ZeroSix API
$apiClient = new ZeroSix_API_Client($config['consumer_key'], $config['consumer_secret']);

// Get all listed products in ZeroSix
$result = $apiClient->getAllProducts();

// Print the results
print_r($result);

?>

curl  --request GET "https://zerosix.ai/wp-json/api/v1/products/" \
      --header "Content-Type: application/json" \
      --data "{}"

The above command returns JSON structured like this:

[
 {
        "id": 1,
        "title": "NVIDIA 1060, 100 GB SSD",
        "slug": "nvidia-1060-100-gb-ssd",
        "description": "NVIDIA 1060 with 100 GB SSD ",
        "permalink": "product/nvidia-1060-100-gb-ssd/",
        "hourly-price": "0.25",
        "currency": "USD",
        "attributes": {
            "cpu": "intel-i3",
            "geo": "asia-pacific",
            "network-speed": "50-100mbps",
            "ram": "8gb",
            "gpu": "nvidia-1060"
        }
    },
    {
        "id": 2,
        "title": "NVIDIA 1080ti, 100GB SSD",
        "slug": "nvidia-1080ti-100gb-ssd",
        "description": "NVIDIA 1080ti with 250 GB SSD",
        "permalink": "product/nvidia-1080ti-100gb-ssd/",
        "hourly-price": "0.5",
        "currency": "USD",
        "attributes": {
            "cpu": "intel-i3",
            "ram": "8gb",
            "gpu": "nvidia-1080ti",
            "geo": "europe",
            "network-speed": "50mbps"
        }
    }   
]

This API helps you to view all the products.

HTTP Request

GET

https://www.zerosix.ai/wp-json/api/v1/products

Query Parameters

none.

Filter Products by attributes

GET

https://www.zerosix.ai/wp-json/api/v1/products/

To see the full list of the attributes, please refer to "Product Properties"

<?php
// Config params
$config = array(
    'consumer_key' => 'CONSUMER KEY',
    'consumer_secret' => 'SECRET KEY',
);

// Connect to ZeroSix API
$apiClient = new ZeroSix_API_Client($config['consumer_key'], $config['consumer_secret']);

// Attributes to filter products
// For example: we are searching for product that:
//              greater (or equal) GPU than nvidia-1070,
//              greater (or equal) RAM than 16GB
//              placed in Europe
//              price range between 0.3 and 0.8 per hour

$params = array(
    "relation" => "greater",
    "attributes" =>  array(
        "gpu" => "nvidia-1070",
        "geo" => "europe",
        "ram" => "16gb"
    ),
    "min_price" => 0.3,
    "max_price" => 0.8
);

// Get all listed products in ZeroSix
$result = $apiClient->filterProducts($params);

// Print the results
print_r($result);

    ?>

curl --request GET "https://zerosix.ai/wp-json/api/v1/products/" \
  --header "Content-Type: application/json" \
  --data "{
    \"relation\": \"greater\",
    \"attributes\": 
    {
      \"gpu\": \"nvidia-1070\",
        \"geo\": \"europe\",
        \"ram\": \"16gb\",
    },
    \"min_price\": 0.3,
    \"max_price\": 0.8
}"

The response of this JSON will be:

[
    {
        "id": 1,
        "title": "NVIDIA TitanXP",
        "slug": "nvidia-titanxp",
        "description": "NVIDIA TitanXp with 250 GB SSD ",
        "permalink": "/product/nvidia-titanxp/",
        "hourly-price": "0.7",
        "currency": "USD",
        "attributes": {
            "cpu": "intel-i7",
            "ram": "16gb",
            "gpu": "nvidia-titan-xp",
            "geo": "europe",
            "network-speed": "50mbps"
        }
    }
]

HTTP Requests

Parameter	Description
`relation`	Relation of the attributes. Must be `greater`, `equal` or `less`.
`attributes`	JSON Object of the required attributes. See example.
`min_price`	Minimum hourly-price per product
`max_price`	Maximum hourly-price per product

HTTP Responses

Parameter	Status	Description
`products_invalid_relation`	`400`	Invalid relation type. Please use: greater, equal or less.
`products_invalid_prices`	`400`	Invalid min or max price type. Please valid your input to numbers only
`products_invalid_prices`	`400`	min price must be less than max price.
`products_invalid_attribute`	`400`	Please input valid attributes according to the attributes table.

Retrieve a Product

<?php
// Config params
$config = array(
    'consumer_key' => 'CONSUMER KEY',
    'consumer_secret' => 'SECRET KEY',
);

// Connect to ZeroSix API
$apiClient = new ZeroSix_API_Client($config['consumer_key'], $config['consumer_secret']);

// The productId we want to retrieve
$productId = 1;

// Get product by ID
$result = $apiClient->getProductById($productId);

// Print the results
print_r($result);
?>

  curl  https://www.zerosix.ai/wp-json/api/v1/products/1  \
        -u consumer_key:consumer_secret \
        -H "Content-Type: application/json"

The above command returns JSON structured like this:

{

        "id": 1,
        "title": "NVIDIA 1060, 100 GB SSD",
        "slug": "nvidia-1060-100-gb-ssd",
        "description": "NVIDIA 1060 with 100 GB SSD ",
        "permalink": "product/nvidia-1060-100-gb-ssd/",
        "hourly-price": "0.25",
        "currency": "USD",
        "attributes": {
            "cpu": "intel-i3",
            "geo": "asia-pacific",
            "network-speed": "50-100mbps",
            "ram": "8gb",
            "gpu": "nvidia-1060"
        }

}

This API lets you retrieve and view a specific product by ID.

HTTP Request

GET

https://www.zerosix.ai/wp-json/api/v1/products/(ID)

Query Parameters

Parameter	Description
`ID`	The ID of the product to retrieve

Orders

This API endpoints allows you to create new order with multiple machines , retrieve information about specific order and more.

Order properties

Order object

Attribute	Type	Description
`order_id`	`integer`	Unique identifier for the order.
`order_key`	`string`	Order key
`order_status`	`string`	Order status. Options: `unlimited`, `pending`, `processing`, `on-hold`, `completed`, `cancelled`, `refunded`, `failed` and `trash`. Default is `pending`.
`date_created`	`DateTime object`	The date the order was created, in the site's timezone. See properties below.
`hourly-price`	`integer`	Hourly price for this order
`currency`	`string`	The currency. Default is: `USD`.
`product`	`array`	Product properties: `id` - The ID of the product. `name` - Name of the ordered product.
`file_url`	`string`	File URL to be loaded initially on the rented machines.
`instances`	`Instances Object`	See properties below.

Instances object

Attribute	Type	Description
`instance_id`	`integer`	Unique identifier for the instance.
`status`	`string`	Instance status
`start_date`	`DateTime object`	Instance start date\time
`end_date`	`DateTime object`	Instance end date\time. If empty, there isn't ending time.
`machine`	`string`	Rented machine name
`rented_hours`	`integer`	Hours duration of the rented machine.

DateTime object

Attribute	Type	Description
`time`	`Time`	Time format: `YYYY-MM-DDTH:i:s`
`timezone_type`	`integer`	TimeZone type.
`timezone`	`TimeZone`	TimeZone

Create new order

  <?php
// Config params
$config = array(
    'consumer_key' => 'CONSUMER KEY',
    'consumer_secret' => 'SECRET KEY',
);

// Connect to ZeroSix API
$apiClient = new ZeroSix_API_Client($config['consumer_key'], $config['consumer_secret']);

// The productId we want to order
$productId = 171;

// Number of instances we want to create
$numOfInstances = 3;

// File URL. 
$fileUrl = "https://ww.zerosix.ai/docker.tar.gz";

// Script URL
$scriptUrl = "https://ww.zerosix.ai/script.tar.gz";

// Create a new order with the properties above
// In this example, we creating an order with productId 171, 3 instances, fileUrl and scriptUrl to be loaded on the instances.
$result = $apiClient->createOrder($productId, $numOfInstances, $fileUrl, $scriptUrl);

// Another example:
// Creating a new order, with only 1 instance, and without any script/file urls.
//$result = $apiClient->createOrder($productId, 1);


// Print the results
print_r($result);
?>

curl --location --request PUT "https://zerosix.ai/wp-json/api/v1/orders?product_id=171&instances=3&file_url=https://ww.zerosix.ai/docker.tar.gz&script_url=https://ww.zerosix.ai/script.tar.gz" \
  --data ""

The above command returns JSON structured like this:

[
{
    "order_id": 1,
    "order_key": "wc_order_randomKey",
    "order_status": "unlimited",
    "date_created": {
        "time": "2019-01-01T04:20:00",
        "timezone_type": 3,
        "timezone": "America/Los_Angeles"
    },
    "hourly-price": "0.5",
    "currency": "USD",
    "product": {
        "id": 171,
        "name": "NVIDIA 1080ti, 100GB SSD"
    },
    "file_url": "https://ww.zerosix.ai/docker.tar.gz",
    "script_url": "https://ww.zerosix.ai/script.tar.gz",
    "instances": [
        {
            "instance_id": 2,
            "status": "wc-unlimited",
            "start_date": {
                "time": "2019-01-01T04:20:00",
                "timezone_type": 3,
                "timezone": "America/Los_Angeles"
            },
            "end_date": "",
            "machine": "-p80 renter@127.0.0.1",
            "rented_hours": "1"
        },
        {
            "instance_id": 3,
            "status": "wc-unlimited",
            "start_date": {
                "time": "2019-01-01T04:20:00",
                "timezone_type": 3,
                "timezone": "America/Los_Angeles"
            },
            "end_date": "",
            "machine": "-p81 renter@127.0.0.1",
            "rented_hours": "1"
        },
        {
            "instance_id": 4,
            "status": "wc-unlimited",
            "start_date": {
                "time": "2019-01-01T04:20:00",
                "timezone_type": 3,
                "timezone": "America/Los_Angeles"
            },
            "end_date": "",
            "machine": "-p82 renter@127.0.0.1",
            "rented_hours": "1"
        }        
    ]
}
]

You can place an order with multiple instances.

PUT

https://www.zerosix.ai/wp-json/api/v1/orders

HTTP Request

Parameter	Description
`product_id`	The product ID we want to book
`instances`	Number of instances to start with.
`file_url`	Optional. URL of the file to be loaded on the machines.
`script_url`	Optional. URL of the script file to be executed on the machines.

HTTP Respones

Parameter	Status	Description
`order_invalid_product_id`	`400`	Invalid ProductID.
`order_invalid_instances`	`400`	Invalid number of instances
`order_not_available_resources`	`200`	Number of requested instances unavailable at this moment.

Complete an order

<?php
// Config params
$config = array(
    'consumer_key' => 'CONSUMER KEY',
    'consumer_secret' => 'SECRET KEY',
);

// Connect to ZeroSix API
$apiClient = new ZeroSix_API_Client($config['consumer_key'], $config['consumer_secret']);

// OrderId
$orderId = 1;

// Complete a order
$result = $apiClient->completeOrder($orderId);

// Print the results
print_r($result);
?>

If order completed successfully, the response will be 204 HTTP status.

Once you completed your order, all the machines (instances) will be marked as completed, and the total cost of your rental time will be updated accordingly.

DEL

https://www.zerosix.ai/wp-json/api/v1/orders/(ID)

HTTP Requests

Parameter	Description
`id`	`integer`

HTTP Respones

Parameter	Status	Description
`order_invalid_id`	`400`	Invalid Order ID.
`order_invalid_permissions`	`401`	You are not authorized to modify this order.
`order_invalid_status`	`404`	Order has been marked already as completed. You cant delete this order.

List all Orders

<?php
// Config params
$config = array(
    'consumer_key' => 'CONSUMER KEY',
    'consumer_secret' => 'SECRET KEY',
);

// Connect to ZeroSix API
$apiClient = new ZeroSix_API_Client($config['consumer_key'], $config['consumer_secret']);

// Get all your orders
$result = $apiClient->getAllOrders();

// Print the results
print_r($result);
?>

List all the orders made by you.

GET

https://www.zerosix.ai/wp-json/api/v1/orders/

HTTP Requests

Parameter	Description

HTTP Respones

Parameter	Status	Description

Retrieve an Order

<?php
// Config params
$config = array(
    'consumer_key' => 'CONSUMER KEY',
    'consumer_secret' => 'SECRET KEY',
);

// Connect to ZeroSix API
$apiClient = new ZeroSix_API_Client($config['consumer_key'], $config['consumer_secret']);

// OrderId
$orderId = 1;

// Get order by ID
$result = $apiClient->getOrderById($orderId);

// Print the results
print_r($result);
?>

GET

https://www.zerosix.ai/wp-json/api/v1/orders/(ID)

HTTP Requests

Parameter	Description
`id`	The ID of the order we want to retrieve.

HTTP Respones

Parameter	Status	Description
`order_invalid_id`	`400`	Invalid Order ID.
`order_invalid_permissions`	`401`	You are not authorized to modify this order.

Credentials

In order to receive the credentials of the order, a request should be made.

Receive Credentials

<?php
// Config params
$config = array(
    'consumer_key' => 'CONSUMER KEY',
    'consumer_secret' => 'SECRET KEY',
);

// Connect to ZeroSix API
$apiClient = new ZeroSix_API_Client($config['consumer_key'], $config['consumer_secret']);

// Order Key
$orderKey = "wc_order_randomKey";

// Get the credentials by OrderKey
$result = $apiClient->getCredentials($orderKey);

// Print the results
print_r($result);
?>

The response of credentials:

{
    "order_id": 1,
    "order_key": "wc_order_randomKey",
    "ssh_key": "SSH KEY URL HERE",
    "instances": [
        {
            "instance_id": 2,
            "ssh_hostname": "renter@127.0.0.1",
            "ssh_port": "80"
        }
    ]
}

GET

https://zerosix.ai/wp-json/api/v1/credentials/(key)

HTTP Request

Parameter	Description
`order_key`	Must mention an `order_key` to receive the credentials.

HTTP Respones

Parameter	Status	Description
`credentials_invalid_order_key`	`400`	Invalid Order Key.
`credentials_invalid_id`	`400`	Problem with order_key. Please mention valid order_key.
`credentials_order_complete`	`403`	Not authorized to see order credentials. Order is completed.