API¶
Information
The API is currently limited to a select few users.
Authorization¶
If you've been granted access to the API, you may generate a token from your control panel.
You must then attach your token as the Authorization: Bearer {token} header with every request.
Requests¶
Every request requires the Accept: application/json & Authorization: Bearer {token} headers.
curl --request GET \
--url 'https://cloud.hosthatch.com/api/v1/products' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
Responses¶
| Attribute | Type | Description |
|---|---|---|
result |
string | A successful response will always have the value of success |
data |
mixed | The data attribute depends on the endpoint, refer to their individual documentation |
{
"result": "success",
"data": null
}
The value of the message attribute may be adjusted and should not be relied upon, it would be recommended to rely on the status code instead.
Validation errors will always be sent with the 422 status code.
| Attribute | Type | Description |
|---|---|---|
result |
string | A failed response will always have the value of error |
message |
string | A brief explaination of what went wrong |
errors |
array<int, string> | Any validation errors will appear here, and may be omitted entirely if no validation errors exist |
{
"result": "error",
"message": "Access forbidden"
}
{
"result": "error",
"message": "Validation failed",
"errors": [
"The product field is required.",
"The image field is required."
]
}
Endpoints¶
GET /api/v1/products¶
Retrieve a list of all the products we offer through our API. This may or may not vary from the products listed on our website and/or control panel.
curl --request GET \
--url 'https://cloud.hosthatch.com/api/v1/products' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
Optionally, you may append the ?prices query parameter to include pricing information for the product and it's various features.
curl --request GET \
--url 'https://cloud.hosthatch.com/api/v1/products?prices' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
| Attribute | Type | Description |
|---|---|---|
_id |
string | The product identifier, used for creating or upgrading servers |
name |
string | The human readable product name |
description |
string | The product description |
options.locations |
object<string, bool> | An object of locations where the product is available. The key is the location identifier (e.g. AMS or LON) and the value is a representation of the current stock status |
options.images |
array<int, string> | An array of available images. |
options.features |
array<int, object> | An array of available optional features objects |
options.features.*._id |
string | The identifier of the optional feature |
options.features.*.name |
string | The human readable name of the optional feature |
options.features.*.values |
array<int, mixed> | An array containing all of the available optional feature values |
options.billing_cycles |
array<int, string> | An array of all the available billing cycles |
{
"result": "success",
"data": {
"products": [
{
"_id": "nvme-2gb",
"name": "NVMe 2 GB",
"description": "1 AMD EPYC Milan core (fair share)\n2 GB DDR4 RAM\n10 GB NVMe Storage\n1 TB bandwidth (500GB in HKG, TOK, SYD, SGP)",
"options": {
"locations": {
"AMS": true,
"STO": false,
"LON": true
},
"images": [
"almalinux8",
"ubuntu22",
"centos7",
"centosstream8",
"debian11",
"debian10",
"ubuntu20",
"ubuntu18"
],
"features": [
{
"_id": "ipv6",
"name": "IPv6",
"values": [
true,
false
]
},
{
"_id": "additional-ipv4",
"name": "Additional IPv4",
"values": [
"0",
"1",
"2",
"3",
"4"
]
}
],
"billing_cycles": [
"monthly",
"quarterly"
]
}
},
...
]
}
}
| Attribute | Type | Description |
|---|---|---|
_id |
string | The product identifier, used for creating or upgrading servers |
name |
string | The human readable product name |
description |
string | The product description |
options.locations |
object<string, bool> | An object of locations where the product is available. The key is the location identifier (e.g. AMS or LON) and the value is a representation of the current stock status |
options.images |
array<int, string> | An array of available images. |
options.features |
array<int, object> | An array of available optional features objects |
options.features.*._id |
string | The identifier of the optional feature |
options.features.*.name |
string | The human readable name of the optional feature |
options.features.*.values |
object<string, object> | An object containing all the available values of the optional feature. Keyed by their identifiers. |
options.features.*.values.*._id |
mixed | The identifier of the optional feature value |
options.features.*.values.*.billing_cycles |
object | The billing cycles the optional feature value is available for. Please refer to the options.billing_cycles attribute below for further information about the structure |
options.billing_cycles |
object<string, object> | An object of all available billing cycles. Keyed by their identifiers. |
options.billing_cycles.*._id |
string | The identifier of the billing cycle |
options.billing_cycles.*.price |
float | The recurring price of the billing cycle |
options.billing_cycles.*.setupfee |
float | The initial setup fee of the billing cycle |
options.billing_cycles.*.currency |
string | The currency in which the billing cycle's prices are displayed in |
{
"result": "success",
"data": {
"products": [
{
"_id": "nvme-2gb",
"name": "NVMe 2 GB",
"description": "1 AMD EPYC Milan core (fair share)\n2 GB DDR4 RAM\n10 GB NVMe Storage\n1 TB bandwidth (500GB in HKG, TOK, SYD, SGP)",
"options": {
"locations": {
"AMS": true,
"STO": false,
"LON": true
},
"images": [
"almalinux8",
"ubuntu22",
"centos7",
"centosstream8",
"debian11",
"debian10",
"ubuntu20",
"ubuntu18"
],
"features": [
{
"_id": "ipv6",
"name": "IPv6",
"values": {
"true": {
"_id": true,
"billing_cycles": {
"monthly": {
"price": 0,
"setupfee": 0,
"currency": "USD"
},
"quarterly": {
"price": 0,
"setupfee": 0,
"currency": "USD"
}
}
},
"false": {
"_id": false
}
}
},
{
"_id": "additional-ipv4",
"name": "Additional IPv4",
"values": [
{
"_id": "0",
"billing_cycles": {
"monthly": {
"price": 0,
"setupfee": 0,
"currency": "USD"
},
"quarterly": {
"price": 0,
"setupfee": 0,
"currency": "USD"
}
}
},
{
"_id": "1",
"billing_cycles": {
"monthly": {
"price": 2,
"setupfee": 0,
"currency": "USD"
},
"quarterly": {
"price": 6,
"setupfee": 0,
"currency": "USD"
}
}
},
{
"_id": "2",
"billing_cycles": {
"monthly": {
"price": 4,
"setupfee": 0,
"currency": "USD"
},
"quarterly": {
"price": 12,
"setupfee": 0,
"currency": "USD"
}
}
},
{
"_id": "3",
"billing_cycles": {
"monthly": {
"price": 6,
"setupfee": 0,
"currency": "USD"
},
"quarterly": {
"price": 18,
"setupfee": 0,
"currency": "USD"
}
}
},
{
"_id": "4",
"billing_cycles": {
"monthly": {
"price": 8,
"setupfee": 0,
"currency": "USD"
},
"quarterly": {
"price": 24,
"setupfee": 0,
"currency": "USD"
}
}
}
]
}
],
"billing_cycles": {
"monthly": {
"_id": "monthly",
"price": 16,
"setupfee": 4,
"currency": "USD"
},
"quarterly": {
"_id": "quarterly",
"price": 48,
"setupfee": 12,
"currency": "USD"
}
}
}
},
...
]
}
}
POST /api/v1/deploy¶
Deploy a new server.
| Attribute | Type | Required | Value |
|---|---|---|---|
product |
string | true | The product identifier of your choice. See GET /api/v1/products for more information |
location |
string | true | The location identifier of your choice. See GET /api/v1/products for more information |
billing |
string | true | The billing cycle identifier of your choice. See GET /api/v1/products for more information |
image |
string | true | The image identifier of your choice. See GET /api/v1/products for more information |
hostname |
string | true | The hostname of your new server |
features |
object<string, mixed> | false | An object containing the optional feature identifiers as the object key and their respective value as the object value . See GET /api/v1/products for more information |
features.ssh_keys |
array<integer> | false | An array containing the optional and identifiers of your choice . See GET /api/v1/keys for more information |
curl --request POST \
--url https://cloud.hosthatch.com/api/v1/deploy \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
"product": "nvme-2gb",
"location": "AMS",
"billing": "monthly",
"image": "almalinux8",
"hostname": "my-new-server",
"features": {
"ipv6": true,
"additional-ipv4": 2,
"ssh_keys": [118, 119]
}
}'
| Attribute | Type | Description |
|---|---|---|
invoice_id |
int | The identifier of the generated invoice |
invoice_url |
int | The control panel link to the generated invoice |
server_id |
int | The identifier of the newly created server |
server_url |
int | The control panel link to the newly created server |
requires_payment |
bool | Indicates whether the user manually has to complete the payment because their credit balance didn't cover the entire cost |
outstanding_balance.price |
float | The outstanding invoice cost. Only exists if the requires_payment attribute is true |
outstanding_balance.currency |
string | The currency in which the outstanding balance price is displayed in. Only exists if the requires_payment attribute is true |
Covered entirely by your account's credit balance
If the cost was entirely covered by your account's credit balance, the response will contain the requires_payment attribute with a false value. You don't need to do anything else from this point and the server creation process should have begun.
// Status Code 201
{
"result": "success",
"data": {
"invoice_id": 445566,
"invoice_url": "https://cloud.hosthatch.com/invoices/445566",
"server_id": 112233,
"server_url": "https://cloud.hosthatch.com/servers/112233",
"requires_payment": false
}
}
Not covered by the account's credit balance
If the cost wasn't entirely covered by your account's credit balance, the response will contain the requires_payment attribute with a true value. This means that you will manually have to pay the outstanding balance of your server invoice by logging into the control panel before the creation process can proceed.
// Status Code 200
{
"result": "success",
"data": {
"invoice_id": 445566,
"invoice_url": "https://cloud.hosthatch.com/invoices/445566",
"server_id": 112233,
"server_url": "https://cloud.hosthatch.com/servers/112233",
"requires_payment": true,
"outstanding_balance": {
"price": 10,
"currency": "USD"
}
}
}
GET /api/v1/servers¶
Retrieve all of your active servers.
curl --request GET \
--url 'https://cloud.hosthatch.com/api/v1/servers' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
| Attribute | Type | Description |
|---|---|---|
servers |
array<int, object> | An array of server objects. Please refer to the GET /api/v1/server/{server} endpoint documentation for more information regarding the structure of each server object. |
{
"result": "success",
"data": {
"servers": [
{
"id": 112233,
"hostname": "example-server",
"state": "Active",
"created": "2023-05-09",
"product": {
"_id": "nvme-2gb",
"name": "NVMe 2 GB",
"location": "AMS",
"image": "Alma Linux 8 64-bit",
"available_upgrades": [
"nvme-4gb",
"nvme-8gb",
"nvme-16gb"
]
},
"network": {
"primary_ipaddress": "127.0.0.1"
},
"billing": {
"billing_cycle": "monthly",
"next_due": "2023-06-09",
"initial_cost": 20,
"recurring_cost": 16,
"currency": "USD"
}
},
...
]
}
}
GET /api/v1/servers/{server}¶
Retrieve one of your active servers.
curl --request GET \
--url 'https://cloud.hosthatch.com/api/v1/servers/{server}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
| Attribute | Type | Description |
|---|---|---|
server.id |
int | The identifier of the server |
server.hostname |
string | The hostname of the server |
server.state |
string | The current state of the server (e.g. Active or Suspended). Not to be confused with the status (e.g. online or offline) of the server |
server.created |
string | The creation date of the server in the YYYY-MM-DD format |
server.product._id |
string | The identifier of the product |
server.product.name |
string | The human readable name of the product |
server.product.location |
string | The location identifier |
server.product.image |
string | The server's installed image |
server.product.available_upgrades |
array<int, string> | An array of available upgrade product identifiers |
server.network.primary_ipaddress |
string | The primary IP address of the server |
server.billing.billing_cycle |
string | The billing cycle identifier |
server.billing.next_due |
string | The date of the next due invoice date in the YYYY-MM-DD format |
server.billing.initial_cost |
float | The initial setup fee that was paid for the server |
server.billing.recurring_cost |
float | The recurring cost according to the server's billing cycle |
server.billing.currency |
string | The currency in which the server.billing.initial_cost and server.billing.recurring_cost are displayed in |
{
"result": "success",
"data": {
"server": {
"id": 112233,
"hostname": "example-server",
"state": "Active",
"created": "2023-05-09",
"product": {
"_id": "nvme-2gb",
"name": "NVMe 2 GB",
"location": "AMS",
"image": "Alma Linux 8 64-bit",
"available_upgrades": [
"nvme-4gb",
"nvme-8gb",
"nvme-16gb"
]
},
"network": {
"primary_ipaddress": "127.0.0.1"
},
"billing": {
"billing_cycle": "monthly",
"next_due": "2023-06-09",
"initial_cost": 20,
"recurring_cost": 16,
"currency": "USD"
}
}
}
}
GET /api/v1/servers/{server}/status¶
Retrieve the status of one of your active servers.
curl --request GET \
--url 'https://cloud.hosthatch.com/api/v1/servers/{server}/status' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
| Attribute | Type | Description |
|---|---|---|
status |
string | The status (e.g. online or offline) of the server |
{
"result": "success",,
"data": {
"status": "online"
}
}
POST /api/v1/servers/{server}/boot¶
Attempt to boot up one of your active servers.
Note
Please note that the response from this endpoint is indicative of the request to boot your server being successful or not, and not the actual boot up process.
curl --request POST \
--url 'https://cloud.hosthatch.com/api/v1/servers/{server}/boot' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
{
"result": "success",
"data": null
}
POST /api/v1/servers/{server}/shutdown¶
Attempt to shutdown one of your active servers.
Note
Please note that the response from this endpoint is indicative of the request to shutdown your server being successful or not, and not the actual shutting down process.
curl --request POST \
--url 'https://cloud.hosthatch.com/api/v1/servers/{server}/shutdown' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
{
"result": "success",
"data": null
}
POST /api/v1/servers/{server}/reboot¶
Attempt to reboot one of your active servers.
Note
Please note that the response from this endpoint is indicative of the request to reboot your server being successful or not, and not the actual rebooting process.
curl --request POST \
--url 'https://cloud.hosthatch.com/api/v1/servers/{server}/reboot' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
{
"result": "success",
"data": null
}
PUT /api/v1/servers/{server}/upgrade¶
Generate an invoice for a server upgrade.
Note
Please note that when this request is sent, we will automatically attempt to charge the upgrade cost from your account's credit balance. If there isn't enough credit to cover the invoice, you will have to manually pay the remaining invoice balance from our control panel.
| Attribute | Type | Required | Value |
|---|---|---|---|
product |
string | true | The identifier of a product. These can be found as the _id value from each available product in the GET /api/v1/products endpoint response |
upgrade_disk |
bool | false | Whether to upgrade the disk or not. Defaults to false |
curl --request PUT \
--url https://cloud.hosthatch.com/api/v1/servers/{server}/upgrade \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
"product": "nvme-4gb",
"upgrade_disk": false
}'
| Attribute | Type | Description |
|---|---|---|
invoice_id |
int | The identifier of the generated invoice |
invoice_url |
int | The control panel link to the generated invoice |
requires_payment |
bool | Indicates whether the user manually has to complete the payment because their credit balance didn't cover the entire cost |
outstanding_balance.price |
float | The outstanding invoice cost. Only exists if the requires_payment attribute is true |
outstanding_balance.currency |
string | The currency in which the outstanding balance price is displayed in. Only exists if the requires_payment attribute is true |
Covered entirely by your account's credit balance
If the upgrade cost was entirely covered by your account's credit balance, the response will contain the requires_payment attribute with a false value. You don't need to do anything else from this point and the upgrade process should have begun.
// Status Code 201
{
"result": "success",
"data": {
"invoice_id": 112233,
"invoice_url": "https://cloud.hosthatch.com/invoices/112233",
"requires_payment": false
}
}
Not covered by the account's credit balance
If the upgrade cost wasn't entirely covered by your account's credit balance, the response will contain the requires_payment attribute with a true value. This means that you will manually have to pay the outstanding balance of your upgrade invoice by logging into the control panel before the upgrade process can proceed.
// Status Code 200
{
"result": "success",
"data": {
"invoice_id": 112233,
"invoice_url": "https://cloud.hosthatch.com/invoices/112233",
"requires_payment": true,
"outstanding_balance": {
"price": 10,
"currency": "USD"
}
}
}
PUT /api/v1/servers/{server}/cancel¶
Generate a cancel request for a server.
| Attribute | Type | Required | Value |
|---|---|---|---|
reason |
string | true | A short message explaining why you want to cancel the server |
immediate |
bool | false | Set to true to cancel immediately or false to cancel at the end of the current billing cycle. Defaults to false |
curl --request POST \
--url https://cloud.hosthatch.com/api/v1/servers/{server}/cancel \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
"reason": "I no longer need this service",
"immediate": true
}'
{
"result": "success",
"data": null
}
GET /api/v1/keys¶
Retrieve all of your keys.
curl --request GET \
--url 'https://cloud.hosthatch.com/api/v1/keys' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
| Attribute | Type | Description |
|---|---|---|
keys |
array<int, object> | An array of key objects. Please refer to the GET /api/v1/keys/{key} endpoint documentation for more information regarding the structure of each key object. |
{
"result": "success",
"data": {
"keys": [
{
"id": 112233,
"type": "sshkey",
"description": "Key description",
"value": "ssh-ed25519 AAAAC3NzaC1/zQkg9farf3PVC2GKSAdqBtZY4vv1X2M+VcZ [email protected]",
},
...
]
}
}
GET /api/v1/keys/{key}¶
Retrieve one of your active key.
curl --request GET \
--url 'https://cloud.hosthatch.com/api/v1/keys/{key}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
| Attribute | Type | Description |
|---|---|---|
key.id |
int | The identifier of the key |
key.type |
string | The type of the key (e.g. sshkey). |
key.description |
string | The decription of the key |
key.value |
string | The value of the key |
{
"result": "success",
"data": {
"key": {
"id": 112233,
"type": "sshkey",
"state": "Your key description",
"created": "ssh-ed25519 AAAAC3NzaC1/zQkg9farf3PVC2GKSAdqBtZY4vv1X2M+VcZ [email protected]",
}
}
}
POST /api/v1/keys¶
Create a new key.
| Attribute | Type | Required | Value |
|---|---|---|---|
description |
string | true | The description of the key |
type |
string | true | The type of the key (e.g. sshkey). |
value |
string | true | The value of the key |
curl --request POST \
--url https://cloud.hosthatch.com/api/v1/keys \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
"description": "new key",
"type": "sshkey",
"value": "ssh-ed25519 AAAAC3NzaC1/zQkg9farf3PVC2GKSAdqBtZY4vv1X2M+VcZ"
}'
| Attribute | Type | Description |
|---|---|---|
id |
int | The identifier of created key |
type |
string | The type of the created key |
description |
string | The description of the created key |
value |
string | The value of the created key |
// Status Code 200
{
"result": "success",
"data": {
"key": {
"id": 1234,
"description": "new key description",
"type": "sshkey",
"value": "ssh-ed25519 AAAAC3NzaC1/zQkg9farf3PVC2GKSAdqBtZY4vv1X2M+VcZ"
}
}
}
DELETE /api/v1/keys/{key}¶
Delete created key.
Note
Please note that the key you are not using some active server.
curl --request DELETE \
--url 'https://cloud.hosthatch.com/api/v1/keys/{key}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'
{
"result": "success",
"data": null
}