Mammoth Cloud API (0.24.3)

Download OpenAPI specification:Download

Mammoth Cloud Support: [email protected] URL: https://support.mammoth.com.au

Introduction

This API is used by Mammoth Cloud's 'mPanel' website, so you'll find everything you need here to automate your use of Mammoth Cloud or develop tools for others. You could even build your own version of 'mPanel' if you wanted!

Getting Started Guide

We are working on a complete 'Getting Started' guide as well as this introductory section.

Developer Preview Notes

Warning: this specification is currently in active development. Until this warning is removed breaking changes are possible without the version changing. However, this API is relatively mature and we are actively developing a new website and other tools against this API so breaking changes should be rare at this point.

We currently have a CLI (command line interface) tool in development and are in the early stage of planning other tools.

We welcome all feedback from API users at the support email address above.

Active Development Status

This is the list of Mammoth Cloud features that are not yet available through the API but are currently under active development. If you need an ETA on when these will be available please contact support.

Domains

Future Development Status

This is the list of Mammoth Cloud features that are not yet available through the API and are not currently in active development. This list is in a rough order of priority. If you need an ETA or want to ask for increased priority on any of these please contact support, we are happy to hear any feedback on this.

Account Updates
Payments

API Tools

This section will include links to tools to assist with consuming this API. We have a CLI tool and a GO library in active development, and are planning libraries for other languages.

Version Information

This section will contain a link to our changelog once the developer preview period is complete.

Accounts

Fetch Information About the Current Account

Authorizations:

apiToken

Responses

Response Schema: application/json

required

object

email

required

string non-empty

The email address registered for this account.

email_verified

required

boolean

Whether this account has been verified. Un-verified accounts are subject to some restrictions.

two_factor_authentication_enabled

required

boolean

Whether this account has enabled two factor authentication.

status

required

string

Enum: "incomplete" "active" "warning" "locked"

The status of this account.

Value	Description
incomplete	An account that exists but is not ready for use. The most common reason for this is a lack of payment information.
active	An account in the normal state.
warning	An account that is under review. If you are unsure why your account has this status please urgently contact support.
locked	An account that is no longer permitted to access the service.

required

object

The tax code that currently applies to transactions for this account.

configured_payment_methods

required

Array of strings (PaymentMethod)

Items Enum: "credit-card" "paypal"

The payment methods that are configured (available) for this account.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/account"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"account": {"email": "string",
"email_verified": true,
"two_factor_authentication_enabled": true,
"status": "incomplete",
"tax_code": {"name": "string",
"type": "none",
"fixed_percent": 0
},
"configured_payment_methods": ["credit-card"
]
}
}

Billing Information

Fetch Current Balance Information

Authorizations:

apiToken

Responses

Response Schema: application/json

required

object

unbilled_total required	number <double> The total of any un-billed charges in AU$.
available_credit required	number <double> Available credit in AU$.
required	Array of objects (ChargeInformation) A list of all of the individual charges that contribute to the un-billed total.
generated_at	string or null <date-time> The timestamp of the most recent charge.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/customers/my/balance"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"balance": {"unbilled_total": 0,
"available_credit": 0,
"charges": [{"created": "2019-08-24T14:15:22Z",
"description": "string",
"total": 0,
"ongoing": true
}
],
"generated_at": "2019-08-24T14:15:22Z"
}
}

Fetch an Invoice

Authorizations:

apiToken

path Parameters

invoice_id

required

integer <int64>

The ID of the invoice to fetch.

Responses

Response Schema: application/json

required

object

invoice_id required	integer <int64> The ID of the invoice.
reference	string or null The reference for this invoice. If this invoice is for a single service this may identify the service, otherwise it will be the account reference.
invoice_number required	string non-empty The invoice number for this invoice.
amount required	number <double> The amount of the invoice in AU$.
required	object The tax code that was applied to transactions on this invoice.
tax required	number <double> The amount of tax (if any) that was charged on the transactions on this invoice.
created required	string <date-time> The date in ISO8601 format this invoice was created.
date_due required	string <date-time> The date in ISO8601 format this invoice is due for payment.
date_overdue required	string <date-time> The date in ISO8601 format this invoice is considered overdue.
paid required	boolean If this is true the invoice has been paid.
refunded required	boolean If this is true the payment for this invoice has been refunded.
payment_failure_count	integer or null <int32> If this is included it indicates the number of failed attempts at processing payment for this invoice that have occurred.
required	Array of objects (InvoiceLineItem) The individual items that make up invoice.
invoice_download_url	string or null The download URL for the rendered version of the invoice.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/customers/my/invoices/${invoice_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"invoice": {"invoice_id": 0,
"reference": "string",
"invoice_number": "string",
"amount": 0,
"tax_code": {"name": "string",
"type": "none",
"fixed_percent": 0
},
"tax": 0,
"created": "2019-08-24T14:15:22Z",
"date_due": "2019-08-24T14:15:22Z",
"date_overdue": "2019-08-24T14:15:22Z",
"paid": true,
"refunded": true,
"payment_failure_count": 0,
"invoice_items": [{"name": "string",
"amount": 0,
"amount_includes_tax": true
}
],
"invoice_download_url": "string"
}
}

Fetch Invoices

Authorizations:

apiToken

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Invoice)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/customers/my/invoices?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"invoices": [{"invoice_id": 0,
"reference": "string",
"invoice_number": "string",
"amount": 0,
"tax_code": {"name": "string",
"type": "none",
"fixed_percent": 0
},
"tax": 0,
"created": "2019-08-24T14:15:22Z",
"date_due": "2019-08-24T14:15:22Z",
"date_overdue": "2019-08-24T14:15:22Z",
"paid": true,
"refunded": true,
"payment_failure_count": 0,
"invoice_items": [{"name": "string",
"amount": 0,
"amount_includes_tax": true
}
],
"invoice_download_url": "string"
}
]
}

Fetch Unpaid Failed Invoices

Any invoices that are unpaid and have a failed payment attempt may block the ability to renew existing services or add new services.

Authorizations:

apiToken

Responses

Response Schema: application/json

required

Array of objects (Invoice)

Array

invoice_id required	integer <int64> The ID of the invoice.
reference	string or null The reference for this invoice. If this invoice is for a single service this may identify the service, otherwise it will be the account reference.
invoice_number required	string non-empty The invoice number for this invoice.
amount required	number <double> The amount of the invoice in AU$.
required	object The tax code that was applied to transactions on this invoice.
tax required	number <double> The amount of tax (if any) that was charged on the transactions on this invoice.
created required	string <date-time> The date in ISO8601 format this invoice was created.
date_due required	string <date-time> The date in ISO8601 format this invoice is due for payment.
date_overdue required	string <date-time> The date in ISO8601 format this invoice is considered overdue.
paid required	boolean If this is true the invoice has been paid.
refunded required	boolean If this is true the payment for this invoice has been refunded.
payment_failure_count	integer or null <int32> If this is included it indicates the number of failed attempts at processing payment for this invoice that have occurred.
required	Array of objects (InvoiceLineItem) The individual items that make up invoice.
invoice_download_url	string or null The download URL for the rendered version of the invoice.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/customers/my/unpaid-payment-failed-invoices"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"invoices": [{"invoice_id": 0,
"reference": "string",
"invoice_number": "string",
"amount": 0,
"tax_code": {"name": "string",
"type": "none",
"fixed_percent": 0
},
"tax": 0,
"created": "2019-08-24T14:15:22Z",
"date_due": "2019-08-24T14:15:22Z",
"date_overdue": "2019-08-24T14:15:22Z",
"paid": true,
"refunded": true,
"payment_failure_count": 0,
"invoice_items": [{"name": "string",
"amount": 0,
"amount_includes_tax": true
}
],
"invoice_download_url": "string"
}
]
}

Servers

Fetch an Existing Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server to fetch.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this server.

name

required

string non-empty

The hostname of this server.

memory

required

integer <int32>

The memory in MB of this server.

vcpus

required

integer <int32>

The number of virtual CPUs of this server.

disk

required

integer <int32>

The total disk in GB of this server.

vpc_id

integer or null <int64>

The VPC ID that this server is allocated to. If this value is null the server is in the default (public) network for the region.

created_at

required

string <date-time>

The date and time in ISO8601 format of this server's initial creation.

status

required

string

Enum: "new" "active" "archive" "off"

Value	Description
new	The server is currently in the process of building and is not yet available for use.
active	The server is available for use.
archive	The server is powered off due to cancellation or non payment.
off	The server has been powered off, but may be powered back on.

backup_ids

required

Array of integers <int64> [ items <int64 > ]

A list of the currently existing backup image IDs for this server (if any).

features

required

Array of strings

A list of the currently enabled features on this server.

required

object

The region this server is allocated to.

required

object

The base image used to create this server.

required

object

The currently selected size for this server.

size_slug

required

string non-empty

The slug of the currently selected size for this server.

object or null

An object that details the selected options for the current size.

required

object

A list of the networks of the server.

object or null

The currently selected kernel for the server.

object or null

The details of the next scheduled backup, if any.

required

Array of objects (Disk)

A list of the disks that are currently attached to the server.

required

object

Detailed backup settings for the server.

cancelled_at

string or null <date-time>

If the server has been cancelled, this is the date and time in ISO8601 format of that cancellation.

failover_ips

required

Array of strings

A list of any assigned failover IP addresses for this server.

required

object

Summary information about the host of this server.

partner_id

integer or null <int64>

The server ID of the partner of this server, if one has been assigned.

password_change_supported

required

boolean

If this is true the password_reset server action can be called to change a user's password. If this is false the password_reset server action will merely clear the root/administrator password allowing the password to be changed via the web console.

permalink

string or null

A randomly generated two-word identifier assigned to servers in regions that support this feature.

object or null

An object that provides details of any backup image currently attached to the server..

required

object

The currently enabled advanced features, machine type and processor flags.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"server": {"id": 0,
"name": "string",
"memory": 0,
"vcpus": 0,
"disk": 0,
"vpc_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"status": "new",
"backup_ids": [0
],
"features": ["string"
],
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"image": {"id": 0,
"name": "string",
"type": "custom",
"distribution": "string",
"full_name": "string",
"slug": "string",
"public": true,
"regions": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"min_disk_size": 0,
"size_gigabytes": 0,
"description": "string",
"status": "NEW",
"error_message": "string",
"min_memory_megabytes": 0,
"distribution_surcharges": {"surcharge_base_cost": 0,
"surcharge_per_memory_megabyte": 0,
"surcharge_per_memory_max_megabytes": 0,
"surcharge_per_vcpu": 0,
"surcharge_min_vcpu": 0
},
"distribution_info": {"image_id": 0,
"password_recovery": "manual",
"remote_access_user": "string",
"features": ["ssh"
]
},
"backup_info": {"type": "daily",
"server_id": 0,
"offsite": true,
"locked": true,
"iso": true,
"backup_disks": [{"id": 0,
"size_gigabytes": 0,
"min_disk_size": 0,
"description": "string"
}
]
}
},
"size": {"slug": "string",
"description": "string",
"cpu_description": "string",
"storage_description": "string",
"size_type": {"slug": "string",
"name": "string",
"description": "string"
},
"available": true,
"regions": ["string"
],
"regions_out_of_stock": ["string"
],
"price_monthly": 0,
"price_hourly": 0,
"distribution_surcharge_credit_monthly": 0,
"disk": 0,
"memory": 0,
"transfer": 0,
"excess_transfer_cost_per_gigabyte": 0,
"vcpus": 0,
"vcpu_units": "string",
"options": {"disk_min": 0,
"disk_max": 0,
"disk_cost_per_additional_gigabyte": 0,
"restricted_disk_values": [0
],
"memory_max": 0,
"memory_cost_per_additional_megabyte": 0,
"transfer_max": 0,
"transfer_cost_per_additional_gigabyte": 0,
"ipv4_addresses_max": 0,
"ipv4_addresses_cost_per_address": 0,
"discount_for_no_public_ipv4": 0,
"daily_backups": 0,
"weekly_backups": 0,
"monthly_backups": 0,
"backups_cost_per_backup_per_gigabyte": 0,
"offsite_backups_cost_per_gigabyte": 0,
"offsite_backup_frequency_cost": {"daily_per_gigabyte": 0,
"weekly_per_gigabyte": 0,
"monthly_per_gigabyte": 0
}
}
},
"size_slug": "string",
"selected_size_options": {"daily_backups": 0,
"weekly_backups": 0,
"monthly_backups": 0,
"offsite_backups": true,
"service_level_id": 0,
"ipv4_addresses": 0,
"memory": 0,
"disk": 0,
"transfer": 0
},
"networks": {"v4": [{"ip_address": "string",
"netmask": 5,
"gateway": "string",
"type": "private",
"reverse_name": "string",
"nat_target": "string"
}
],
"v6": [{"ip_address": "string",
"netmask": 5,
"gateway": "string",
"type": "private",
"reverse_name": "string",
"nat_target": "string"
}
],
"port_blocking": true,
"separate_private_network_interface": true,
"source_and_destination_check": true,
"recent_ddos": true,
"ipv6_reverse_nameservers": ["string"
]
},
"kernel": {"id": 0,
"name": "string",
"version": "string"
},
"next_backup_window": {"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z"
},
"disks": [{"id": 0,
"size_gigabytes": 0,
"description": "string",
"primary": true
}
],
"backup_settings": {"backup_hour_of_day": 0,
"backup_day_of_week": 0,
"backup_day_of_month": 0,
"offsite_backup_settings": {"use_custom_backup_location": true,
"offsite_backup_location": "string",
"manage_offsite_copies": true
}
},
"cancelled_at": "2019-08-24T14:15:22Z",
"failover_ips": ["string"
],
"host": {"display_name": "string",
"uptime_ms": 0,
"status_page": "string"
},
"partner_id": 0,
"password_change_supported": true,
"permalink": "string",
"attached_backup": {"id": 0,
"disk_identifiers": ["string"
],
"attached_at": "2019-08-24T14:15:22Z",
"attachment_expires": "2019-08-24T14:15:22Z"
},
"advanced_features": {"processor_model": 0,
"machine_type": "pc_i440fx_1point5",
"video_device": "cirrus-logic",
"enabled_advanced_features": ["emulated-hyperv"
]
}
}
}

Cancel an Existing Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server to be cancelled.

query Parameters

reason

string [ 0 .. 250 ] characters

The reason for cancelling the server.

Responses

Request samples

Curl

curl -X DELETE "https://api.mammoth.com.au/v2/servers/${server_id}?reason=${reason}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

404

Content type

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}

List All Servers

Authorizations:

apiToken

query Parameters

hostname	string Providing a hostname restricts the results to the server that has this hostname (case insensitive). If this parameter is provided at most 1 server will be returned.
page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Server)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers?hostname=${hostname}&page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"servers": [{"id": 0,
"name": "string",
"memory": 0,
"vcpus": 0,
"disk": 0,
"vpc_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"status": "new",
"backup_ids": [0
],
"features": ["string"
],
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"image": {"id": 0,
"name": "string",
"type": "custom",
"distribution": "string",
"full_name": "string",
"slug": "string",
"public": true,
"regions": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"min_disk_size": 0,
"size_gigabytes": 0,
"description": "string",
"status": "NEW",
"error_message": "string",
"min_memory_megabytes": 0,
"distribution_surcharges": {"surcharge_base_cost": 0,
"surcharge_per_memory_megabyte": 0,
"surcharge_per_memory_max_megabytes": 0,
"surcharge_per_vcpu": 0,
"surcharge_min_vcpu": 0
},
"distribution_info": {"image_id": 0,
"password_recovery": "manual",
"remote_access_user": "string",
"features": ["ssh"
]
},
"backup_info": {"type": "daily",
"server_id": 0,
"offsite": true,
"locked": true,
"iso": true,
"backup_disks": [{"id": 0,
"size_gigabytes": 0,
"min_disk_size": 0,
"description": "string"
}
]
}
},
"size": {"slug": "string",
"description": "string",
"cpu_description": "string",
"storage_description": "string",
"size_type": {"slug": "string",
"name": "string",
"description": "string"
},
"available": true,
"regions": ["string"
],
"regions_out_of_stock": ["string"
],
"price_monthly": 0,
"price_hourly": 0,
"distribution_surcharge_credit_monthly": 0,
"disk": 0,
"memory": 0,
"transfer": 0,
"excess_transfer_cost_per_gigabyte": 0,
"vcpus": 0,
"vcpu_units": "string",
"options": {"disk_min": 0,
"disk_max": 0,
"disk_cost_per_additional_gigabyte": 0,
"restricted_disk_values": [0
],
"memory_max": 0,
"memory_cost_per_additional_megabyte": 0,
"transfer_max": 0,
"transfer_cost_per_additional_gigabyte": 0,
"ipv4_addresses_max": 0,
"ipv4_addresses_cost_per_address": 0,
"discount_for_no_public_ipv4": 0,
"daily_backups": 0,
"weekly_backups": 0,
"monthly_backups": 0,
"backups_cost_per_backup_per_gigabyte": 0,
"offsite_backups_cost_per_gigabyte": 0,
"offsite_backup_frequency_cost": {"daily_per_gigabyte": 0,
"weekly_per_gigabyte": 0,
"monthly_per_gigabyte": 0
}
}
},
"size_slug": "string",
"selected_size_options": {"daily_backups": 0,
"weekly_backups": 0,
"monthly_backups": 0,
"offsite_backups": true,
"service_level_id": 0,
"ipv4_addresses": 0,
"memory": 0,
"disk": 0,
"transfer": 0
},
"networks": {"v4": [{"ip_address": "string",
"netmask": 5,
"gateway": "string",
"type": "private",
"reverse_name": "string",
"nat_target": "string"
}
],
"v6": [{"ip_address": "string",
"netmask": 5,
"gateway": "string",
"type": "private",
"reverse_name": "string",
"nat_target": "string"
}
],
"port_blocking": true,
"separate_private_network_interface": true,
"source_and_destination_check": true,
"recent_ddos": true,
"ipv6_reverse_nameservers": ["string"
]
},
"kernel": {"id": 0,
"name": "string",
"version": "string"
},
"next_backup_window": {"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z"
},
"disks": [{"id": 0,
"size_gigabytes": 0,
"description": "string",
"primary": true
}
],
"backup_settings": {"backup_hour_of_day": 0,
"backup_day_of_week": 0,
"backup_day_of_month": 0,
"offsite_backup_settings": {"use_custom_backup_location": true,
"offsite_backup_location": "string",
"manage_offsite_copies": true
}
},
"cancelled_at": "2019-08-24T14:15:22Z",
"failover_ips": ["string"
],
"host": {"display_name": "string",
"uptime_ms": 0,
"status_page": "string"
},
"partner_id": 0,
"password_change_supported": true,
"permalink": "string",
"attached_backup": {"id": 0,
"disk_identifiers": ["string"
],
"attached_at": "2019-08-24T14:15:22Z",
"attachment_expires": "2019-08-24T14:15:22Z"
},
"advanced_features": {"processor_model": 0,
"machine_type": "pc_i440fx_1point5",
"video_device": "cirrus-logic",
"enabled_advanced_features": ["emulated-hyperv"
]
}
}
]
}

Create a New Server

Authorizations:

apiToken

Request Body schema: application/json

name	string or null The hostname of your server, such as vps01.yourcompany.com. If not provided, the server will be created with a random name.
backups	boolean or null If true this will enable two daily backups for the server. Options.daily_backups will override this value if provided. Setting this to false has no effect.
ipv6	boolean or null If true this will enable IPv6 for this server.
size required	string non-empty The slug of the selected size.
required	integer or string The slug or id of the selected operating system.
region required	string non-empty The slug of the selected region.
vpc_id	integer or null <int64> Leave null to use default (public) network for the selected region.
	Array of integers or strings or null This may be either the SSH keys Ids or fingerprints. If this is null or not provided any SSH keys that have been marked as default will be deployed (if the operating system supports SSH keys). Submit an empty array to disable deployment of default keys.
payment_frequency	string or null Enum: "hourly" "single" "quarterly" "half-yearly" "yearly" This may be left null to accept the default payment frequency.
	object or null This may be left null to accept all of the defaults for the selected size.
	Array of objects or null (License) The desired set of licenses.
user_data	string or null <= 65536 characters If provided this will be used to initialise the new server. This must be left null if the Image does not support UserData, see DistributionInfo.Features for more information.
port_blocking	boolean or null Port blocking of outgoing connections for email, SSH and Remote Desktop (TCP ports 22, 25, and 3389) is enabled by default for all new servers. If this is false port blocking will be disabled. Disabling port blocking is only available to reviewed accounts.
password	string or null If this is provided the default remote user account's password will be set to this value. If this is null a random password will be generated and emailed to the account email address.

Responses

Response Schema: application/json

required	object
required	object

Request samples

Payload
Curl

Content type

application/json

{"name": "string",
"backups": true,
"ipv6": true,
"size": "string",
"image": 5,
"region": "string",
"vpc_id": 0,
"ssh_keys": [5
],
"payment_frequency": "hourly",
"options": {"daily_backups": 14,
"weekly_backups": 13,
"monthly_backups": 12,
"offsite_backups": true,
"service_level_id": 0,
"ipv4_addresses": 2147483647,
"memory": 0,
"disk": 0,
"transfer": 0
},
"licenses": [{"software_id": 0,
"count": 0
}
],
"user_data": "string",
"port_blocking": true,
"password": "string"
}

Response samples

200
400

Content type

application/json

{"server": {"id": 0,
"name": "string",
"memory": 0,
"vcpus": 0,
"disk": 0,
"vpc_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"status": "new",
"backup_ids": [0
],
"features": ["string"
],
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"image": {"id": 0,
"name": "string",
"type": "custom",
"distribution": "string",
"full_name": "string",
"slug": "string",
"public": true,
"regions": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"min_disk_size": 0,
"size_gigabytes": 0,
"description": "string",
"status": "NEW",
"error_message": "string",
"min_memory_megabytes": 0,
"distribution_surcharges": {"surcharge_base_cost": 0,
"surcharge_per_memory_megabyte": 0,
"surcharge_per_memory_max_megabytes": 0,
"surcharge_per_vcpu": 0,
"surcharge_min_vcpu": 0
},
"distribution_info": {"image_id": 0,
"password_recovery": "manual",
"remote_access_user": "string",
"features": ["ssh"
]
},
"backup_info": {"type": "daily",
"server_id": 0,
"offsite": true,
"locked": true,
"iso": true,
"backup_disks": [{"id": 0,
"size_gigabytes": 0,
"min_disk_size": 0,
"description": "string"
}
]
}
},
"size": {"slug": "string",
"description": "string",
"cpu_description": "string",
"storage_description": "string",
"size_type": {"slug": "string",
"name": "string",
"description": "string"
},
"available": true,
"regions": ["string"
],
"regions_out_of_stock": ["string"
],
"price_monthly": 0,
"price_hourly": 0,
"distribution_surcharge_credit_monthly": 0,
"disk": 0,
"memory": 0,
"transfer": 0,
"excess_transfer_cost_per_gigabyte": 0,
"vcpus": 0,
"vcpu_units": "string",
"options": {"disk_min": 0,
"disk_max": 0,
"disk_cost_per_additional_gigabyte": 0,
"restricted_disk_values": [0
],
"memory_max": 0,
"memory_cost_per_additional_megabyte": 0,
"transfer_max": 0,
"transfer_cost_per_additional_gigabyte": 0,
"ipv4_addresses_max": 0,
"ipv4_addresses_cost_per_address": 0,
"discount_for_no_public_ipv4": 0,
"daily_backups": 0,
"weekly_backups": 0,
"monthly_backups": 0,
"backups_cost_per_backup_per_gigabyte": 0,
"offsite_backups_cost_per_gigabyte": 0,
"offsite_backup_frequency_cost": {"daily_per_gigabyte": 0,
"weekly_per_gigabyte": 0,
"monthly_per_gigabyte": 0
}
}
},
"size_slug": "string",
"selected_size_options": {"daily_backups": 0,
"weekly_backups": 0,
"monthly_backups": 0,
"offsite_backups": true,
"service_level_id": 0,
"ipv4_addresses": 0,
"memory": 0,
"disk": 0,
"transfer": 0
},
"networks": {"v4": [{"ip_address": "string",
"netmask": 5,
"gateway": "string",
"type": "private",
"reverse_name": "string",
"nat_target": "string"
}
],
"v6": [{"ip_address": "string",
"netmask": 5,
"gateway": "string",
"type": "private",
"reverse_name": "string",
"nat_target": "string"
}
],
"port_blocking": true,
"separate_private_network_interface": true,
"source_and_destination_check": true,
"recent_ddos": true,
"ipv6_reverse_nameservers": ["string"
]
},
"kernel": {"id": 0,
"name": "string",
"version": "string"
},
"next_backup_window": {"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z"
},
"disks": [{"id": 0,
"size_gigabytes": 0,
"description": "string",
"primary": true
}
],
"backup_settings": {"backup_hour_of_day": 0,
"backup_day_of_week": 0,
"backup_day_of_month": 0,
"offsite_backup_settings": {"use_custom_backup_location": true,
"offsite_backup_location": "string",
"manage_offsite_copies": true
}
},
"cancelled_at": "2019-08-24T14:15:22Z",
"failover_ips": ["string"
],
"host": {"display_name": "string",
"uptime_ms": 0,
"status_page": "string"
},
"partner_id": 0,
"password_change_supported": true,
"permalink": "string",
"attached_backup": {"id": 0,
"disk_identifiers": ["string"
],
"attached_at": "2019-08-24T14:15:22Z",
"attachment_expires": "2019-08-24T14:15:22Z"
},
"advanced_features": {"processor_model": 0,
"machine_type": "pc_i440fx_1point5",
"video_device": "cirrus-logic",
"enabled_advanced_features": ["emulated-hyperv"
]
}
},
"links": {"actions": [{"id": 0,
"rel": "string",
"href": "string"
}
]
}
}

Fetch an Action for a Server

Authorizations:

apiToken

path Parameters

server_id required	integer <int64> The ID of the server for which the action should be fetched.
action_id required	integer <int64> The ID of the action to fetch.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}/actions/${action_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Fetch All Advanced Firewall Rules for a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server for which firewall rules should be listed.

Responses

Response Schema: application/json

required

Array of objects (AdvancedFirewallRule)

The advanced firewall rules for the selected server. Please note that the order of the rules is critical as the first matching rule is applied, and if no rules match the traffic is permitted.

Array

source_addresses required	Array of strings non-empty The source addresses to match for this rule. Each address may be an individual IPv4 address or a range in IPv4 CIDR notation.
destination_addresses required	Array of strings non-empty The destination addresses to match for this rule. Each address may be an individual IPv4 address or a range in IPv4 CIDR notation.
destination_ports	Array of strings or null The destination ports to match for this rule. Leave null or empty to match on all ports.
protocol required	string Enum: "all" "icmp" "tcp" "udp" The protocol to match for this rule.
action required	string Enum: "drop" "accept" The action to take when there is a match on this rule.
description	string or null [ 0 .. 250 ] characters A description to assist in identifying this rule. Commonly used to record the reason for the rule or the intent behind it, e.g. "Block access to RDP" or "Allow access from HQ".

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}/advanced_firewall_rules"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"firewall_rules": [{"source_addresses": ["string"
],
"destination_addresses": ["string"
],
"destination_ports": ["string"
],
"protocol": "all",
"action": "drop",
"description": "string"
}
]
}

Fetch the Currently Available Advanced Features for a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server for which advanced features should be listed.

Responses

Response Schema: application/json

required

object

required	Array of objects (ProcessorModel) A list of the processor models available for this server.
machine_types required	Array of strings (VmMachineType) Items Enum: "pc_i440fx_1point5" "pc_i440fx_2point11" "pc_i440fx_4point1" "pc_i440fx_4point2" "pc_i440fx_5point0" "pc_i440fx_5point1" A list of the machine types available for this server.
advanced_features required	Array of strings (AdvancedFeature) Items Enum: "emulated-hyperv" "emulated-devices" "nested-virt" "driver-disk" "unset-uuid" "local-rtc" "emulated-tpm" "cloud-init" "qemu-guest-agent" "uefi-boot" A list of the advanced features available for this server.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}/available_advanced_features"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"available_advanced_server_features": {"processor_models": [{"id": 0,
"name": "string",
"description": "string"
}
],
"machine_types": ["pc_i440fx_1point5"
],
"advanced_features": ["emulated-hyperv"
]
}
}

List All Backups for a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server for which backups should be listed.

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Image)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}/backups?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"backups": [{"id": 0,
"name": "string",
"type": "custom",
"distribution": "string",
"full_name": "string",
"slug": "string",
"public": true,
"regions": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"min_disk_size": 0,
"size_gigabytes": 0,
"description": "string",
"status": "NEW",
"error_message": "string",
"min_memory_megabytes": 0,
"distribution_surcharges": {"surcharge_base_cost": 0,
"surcharge_per_memory_megabyte": 0,
"surcharge_per_memory_max_megabytes": 0,
"surcharge_per_vcpu": 0,
"surcharge_min_vcpu": 0
},
"distribution_info": {"image_id": 0,
"password_recovery": "manual",
"remote_access_user": "string",
"features": ["ssh"
]
},
"backup_info": {"type": "daily",
"server_id": 0,
"offsite": true,
"locked": true,
"iso": true,
"backup_disks": [{"id": 0,
"size_gigabytes": 0,
"min_disk_size": 0,
"description": "string"
}
]
}
}
]
}

Upload a Backup for a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server for which the backup is to be uploaded.

Request Body schema: application/json

backup_type	string or null Enum: "daily" "weekly" "monthly" "temporary" If replacement_strategy is anything other than 'specified', this must be provided.
replacement_strategy required	string Enum: "none" "specified" "oldest" "newest" The strategy for selecting which backup to replace (if any).
backup_id_to_replace	integer or null <int64> If replacement_strategy is 'specified' this property must be set to an existing backup.
label	string or null <= 250 characters An optional label to identify the backup.
url required	string <uri> non-empty The source URL for the image to upload. Only HTTP and HTTPS sources are currently supported.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"backup_type": "daily",
"replacement_strategy": "none",
"backup_id_to_replace": 0,
"label": "string",
"url": "http://example.com"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

List all Available Kernels for a Server

Only servers based on one of our Linux distribution images may change kernels.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server for which kernels should be listed.

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Kernel)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}/kernels?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"kernels": [{"id": 0,
"name": "string",
"version": "string"
}
]
}

List all Snapshots for a Server

Server snapshots are not implemented. This will always return 0 results.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server for which snapshots should be listed.

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Image)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}/snapshots?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"snapshots": [{"id": 0,
"name": "string",
"type": "custom",
"distribution": "string",
"full_name": "string",
"slug": "string",
"public": true,
"regions": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"min_disk_size": 0,
"size_gigabytes": 0,
"description": "string",
"status": "NEW",
"error_message": "string",
"min_memory_megabytes": 0,
"distribution_surcharges": {"surcharge_base_cost": 0,
"surcharge_per_memory_megabyte": 0,
"surcharge_per_memory_max_megabytes": 0,
"surcharge_per_vcpu": 0,
"surcharge_min_vcpu": 0
},
"distribution_info": {"image_id": 0,
"password_recovery": "manual",
"remote_access_user": "string",
"features": ["ssh"
]
},
"backup_info": {"type": "daily",
"server_id": 0,
"offsite": true,
"locked": true,
"iso": true,
"backup_disks": [{"id": 0,
"size_gigabytes": 0,
"min_disk_size": 0,
"description": "string"
}
]
}
}
]
}

Fetch the Currently Set Threshold Alerts for a Server

Includes the current values for the most recent threshold alert period.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server for which threshold alerts should be fetched.

Responses

Response Schema: application/json

required

Array of objects (ThresholdAlert)

Array

alert_type

required

string

Enum: "cpu" "storage-requests" "network-incoming" "network-outgoing" "data-transfer-used" "storage-used" "memory-used"

Value	Description
cpu	The alert is based off the average percentage of all CPU; 100% is the maximum possible even with multiple processors. A high average will prevent the server from responding quickly.
storage-requests	The alert is based off The average number of requests (combined read and write) received by the storage subsystem. A high number of requests often indicates swap usage (due to memory exhaustion) and is associated with poor performance.
network-incoming	The alert is based off the amount of data going into the server (from the internet and the LAN). A sudden increase may indicate the server is the victim of a DOS attack.
network-outgoing	The alert is based off the amount of data coming out of the server (to the internet and the LAN). A sudden increase may indicate the server has been hacked and is being used for spam delivery.
data-transfer-used	The alert is based off the percentage of your monthly data transfer limit.
storage-used	The alert is based off the disk space consumed as a percentage of your total disk space. If the server runs out of disk space programs may fail to execute or be unable to create new files, or the server may become unresponsive.
memory-used	The alert is based off the virtual memory consumed as a percentage of your physical memory. Virtual memory includes the swap file so the percentage may exceed 100% indicating that the server has run out of physical memory and is relying on swap space, which will generally cause poor performance.

enabled

required

boolean

If a threshold alert is not enabled it will not generate warnings for the user.

value

required

integer <int32>

The threshold value of the alert. Refer to the documentation for each threshold alert type for what this value measures in the context of the alert type.

current_value

integer or null <int32>

The last measured value for this alert type over the threshold alert period. Refer to the documentation for each threshold alert type for what this value measures in the context of the alert type. If there is no measured value in the threshold alert period this will be null.

last_raised

string or null <date-time>

The date and time (if any) in ISO8601 format of the last time this alert was raised. An alert may not be raised again until it has been cleared.

last_cleared

string or null <date-time>

The date and time (if any) in ISO8601 format of the last time this alert was cleared. An alert may not be raised again until a minimum duration has passed since it was last cleared.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}/threshold_alerts"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"threshold_alerts": [{"alert_type": "cpu",
"enabled": true,
"value": 0,
"current_value": 0,
"last_raised": "2019-08-24T14:15:22Z",
"last_cleared": "2019-08-24T14:15:22Z"
}
]
}

List any Servers that have a Current Exceeded Threshold Alert

Authorizations:

apiToken

Responses

Response Schema: application/json

server_ids

required

Array of integers <int64> [ items <int64 > ]

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/threshold_alerts"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"server_ids": [0
]
}

List all Enabled Software for a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server for which software should be fetched.

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (LicensedSoftware)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}/software?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"licensed_software": [{"software": {"id": 0,
"enabled": true,
"name": "string",
"description": "string",
"cost_per_licence_per_month": 0,
"minimum_licence_count": 0,
"maximum_licence_count": 0,
"licence_step_count": 0,
"group": "string",
"supported_operating_systems": ["string"
]
},
"licence_count": 0
}
]
}

Fetch the Currently Set UserData for a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server for which userdata should be fetched.

Responses

Response Schema: application/json

user_data

string or null

The UserData that was last used to initialise the server.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}/user_data"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"user_data": "string"
}

Fetch the Console URLs for a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server for which console URLs will be fetched.

Responses

Response Schema: application/json

required

object

iframe required	string non-empty The URL for the embedded version of the console.
browser required	string non-empty The URL for the full screen and full featured version of the console.
width required	integer <int32> Rescue console native width.
height required	integer <int32> Rescue console native height.
expiry required	string <date-time> The expiry time of the provided URLs.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}/console"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
400
404

Content type

application/json

{"console": {"iframe": "string",
"browser": "string",
"width": 0,
"height": 0,
"expiry": "2019-08-24T14:15:22Z"
}
}

Server Actions

List All Actions for a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server for which actions should be listed.

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Action)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/servers/${server_id}/actions?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"actions": [{"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
]
}

Perform an Action on a Server

Review the ServerAction schema for a list of available actions. Review the description in each individual schema for each type of server action for further information. For actions that 'query' something (e.g. "Ping") fetch the completed action from the action endpoint for the response.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty add_disk
size_gigabytes required	integer <int32> [ 1 .. 2147483647 ] The size of the new disk in GB. The server must have at least this much unallocated storage space.
description	string or null [ 0 .. 255 ] characters An optional description for the disk. If this is null a default description will be added. Submit an empty string to prevent the default description being added.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

Example

add_disk

{"type": "add_disk",
"size_gigabytes": 1,
"description": "string"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Set or Update the Threshold Alerts for a Server

This is used to set threshold alerts (also known as resource alerts) for the server.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_threshold_alerts"
required	Array of objects (ThresholdAlertRequest) Any alert type not listed will not be updated.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_threshold_alerts",
"threshold_alerts": [{"alert_type": "cpu",
"enabled": true,
"value": 0
}
]
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Check if a Server is Running

This is used to check if the server is running, but not the state of the server. For example, the server may be running but be unresponsive, rebooting etc.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "is_running"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "is_running"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Attempt to Ping a Server

This is used to determine if the server responds to a ping. The ping attempt is normally made to the public interface, so it may be blocked by your firewall settings etc.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "ping"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "ping"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Revert the Cancellation of a Server

NB: this is only available before the server is suspended and we make no guarantees that un-cancellation is possible.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "uncancel"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "uncancel"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Check the Uptime of a Server

This is used to determine how long the server has been continuously running.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "uptime"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "uptime"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Attach a Backup to a Server

This is most often used to restore an individual file from a backup. It may also be used to boot the server from an ISO image.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "attach_backup"
image required	integer <int64> Only attaching backup images is currently supported.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "attach_backup",
"image": 0
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Change the Backup Schedule of a Server

This changes when the backups are taken, not the frequency or retention of backups.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_backup_schedule"
backup_hour_of_day	integer or null <int32> [ 0 .. 23 ] Do not provide a value to keep the current setting.
backup_day_of_week	integer or null <int32> [ 0 .. 6 ] Sunday is 0, Monday is 1 etc. Do not provide a value to keep the current setting.
backup_day_of_month	integer or null <int32> [ 1 .. 28 ] Do not provide a value to keep the current setting.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_backup_schedule",
"backup_hour_of_day": 23,
"backup_day_of_week": 6,
"backup_day_of_month": 1
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Change the Management of Offsite Backup Copies

This is used to alter whether old offsite backups will be removed when the replacement upload is complete if offsite backups have been selected and a custom offsite location is used.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_manage_offsite_backup_copies"
manage_offsite_backup_copies required	boolean This only has effect if a custom offsite location is being used: the internal offsite backup location always manages copies. If this is true old offsite backups will be removed once the replacement upload is complete. If this is false backups must be removed from the Amazon S3 bucket manually. Amazon will charge your S3 account at their standard rate for every backup stored.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_manage_offsite_backup_copies",
"manage_offsite_backup_copies": true
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Change the Offsite Backup Location of a Server

If offsite backups have been selected this is used to change the offsite backup location, either to a valid Amazon S3 bucket or our internal offsite backup location.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_offsite_backup_location"
offsite_backup_location	string or null Do not provide or set to null to use the internal offsite backup location, otherwise this must be a valid Amazon S3 bucket address. If this is provided Amazon will charge your S3 account at their standard rate for every backup stored.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_offsite_backup_location",
"offsite_backup_location": "string"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Restore a Backup of a Server to a Different Existing Server

This is used to clone a new server from the backup of an existing server.
The action is 'performed' on the source server. The target server must have finished the initial building process: this will fail if the target server is does not have the status 'available'.
NB: This is a destructive operation on the target server and no further confirmation will be requested.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "clone_using_backup"
image_id required	integer <int64> The ID of the image to clone. Only backup type images are currently supported. This must be a backup of the server ID in the action endpoint URL.
target_server_id required	integer <int64> The target server ID. This server's current disks will be wiped and replaced with the selected backup image.
name	string or null The new hostname for the target server. If this is not supplied the target server's existing hostname will be used.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "clone_using_backup",
"image_id": 0,
"target_server_id": 0,
"name": "string"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Detach Any Attached Backup from a Server

This is used to detach a backup that was attached with the Attach Backup action.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "detach_backup"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "detach_backup"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Disable Backups for an Existing Server

This will disable backups for a server only if it has the backup configuration that is created by the EnabledBackups action, i.e. two daily backups.
This is not a 'pause' for backups, this will change the server's options to remove the backups.
For greater control over the backup options use Options property on the Resize action.
NB: This is a destructive operation (previous backups will no longer be available) and no further confirmation will be requested.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "disable_backups"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "disable_backups"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Enable Two Daily Backups for an Existing Server

This will enable two daily backups if the server currently has no backups. This is not an 'un-pause' for backups. It will change the server's options to enable two daily backups.
For greater control over the backup options use Options property on the Resize action.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "enable_backups"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "enable_backups"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Restore a Backup to a Server

This will remove the server's existing disks and restore the selected backup.
NB: This is a destructive operation and no further confirmation will be requested.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "restore"
required	integer or string The ID of the specific backup to use. Snapshots are not currently supported.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "restore",
"image": 5
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Take a Backup of a Server

This creates an immediate backup of the server.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "take_backup"
backup_type	string or null Enum: "daily" "weekly" "monthly" "temporary" If replacement_strategy is anything other than 'specified', this must be provided.
replacement_strategy required	string Enum: "none" "specified" "oldest" "newest" The strategy for selecting which backup to replace (if any).
backup_id_to_replace	integer or null <int64> If replacement_strategy is 'specified' this property must be set to an existing backup.
label	string or null <= 250 characters An optional label to identify the backup.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "take_backup",
"backup_type": "daily",
"replacement_strategy": "none",
"backup_id_to_replace": 0,
"label": "string"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Reset the Password of a Server

This will reset the password of the specified or default remote user if possible (e.g. on most Unix derived operating systems) or clear the administrator password on Windows operating systems.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "password_reset"
username	string or null The username of the user to change the password. Only valid if the server supports password change actions (check server.password_change_supported via the servers endpoint). If omitted and the server supports password change actions this will default to the username of the remote user that was configured when the server was created (normally 'root').
password	string or null If this is provided the specified or default remote user's account password will be set to this value. Only valid if the server supports password change actions (check server.password_change_supported via the servers endpoint). If omitted and the server supports password change actions a random password will be generated and emailed to the account email address.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "password_reset",
"username": "string",
"password": "string"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Power a Server Off and then On

This is a 'hard' reboot, equivalent to turning the server's power switch off and on.
This should be used only if the server is unresponsive when the 'Reboot' action is attempted.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "power_cycle"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "power_cycle"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Power a Server Off

This is a 'hard' power off, equivalent to turning the server's power switch off.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "power_off"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "power_off"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Power a Server On

This may be used if the server has previous been powered off either from inside the server's operating system or via an action.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "power_on"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "power_on"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Request a Server Perform a Reboot

This is a 'soft' reboot, equivalent to tapping the power button on the server or selecting 'restart' in the operating system to trigger an orderly shutdown, waiting for that shutdown, then starting the server.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "reboot"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "reboot"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Request a Server Perform a Shutdown

This is a 'soft' shutdown, equivalent to tapping the power button on the server or selecting 'shutdown' in the operating system to trigger an orderly shutdown, then waiting for that shutdown.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "shutdown"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "shutdown"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Change the Advanced Features of a Server

This is used to change the virtual processor model, emulated video card and other virtualization options.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_advanced_features"
enabled_advanced_features	Array of strings or null (AdvancedFeature) Enum: "emulated-hyperv" "emulated-devices" "nested-virt" "driver-disk" "unset-uuid" "local-rtc" "emulated-tpm" "cloud-init" "qemu-guest-agent" "uefi-boot" Do not provide or set to null to keep existing advanced features. Provide an empty array to disable all advanced features, otherwise provide an array with selected advanced features. If provided, any currently enabled advanced features that aren't included will be disabled.
processor_model	integer or null <int64> Do not provide or set to null to keep existing processor model.
automatic_processor_model	boolean or null Set to true to use best available processor model. If this is provided the processor_model property must not be provided.
machine_type	string or null Enum: "pc_i440fx_1point5" "pc_i440fx_2point11" "pc_i440fx_4point1" "pc_i440fx_4point2" "pc_i440fx_5point0" "pc_i440fx_5point1" Do not provide or set to null to keep existing machine type.
automatic_machine_type	boolean or null Set to true to use best available machine type. If this is provided the machine_type property must not be provided.
video_device	string or null Enum: "cirrus-logic" "standard" "virtio" "virtio-wide" Do not provide or set to null to keep existing video device.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_advanced_features",
"enabled_advanced_features": ["emulated-hyperv"
],
"processor_model": 0,
"automatic_processor_model": true,
"machine_type": "pc_i440fx_1point5",
"automatic_machine_type": true,
"video_device": "cirrus-logic"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Change the Advanced Firewall Rules for a Server

This is used to configure the external firewall. Please see our documentation for more information.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_advanced_firewall_rules"
required	Array of objects (AdvancedFirewallRule) A list of rules for the server. NB: that any existing rules that are not included will be removed. Submit an empty list to clear all rules.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_advanced_firewall_rules",
"firewall_rules": [{"source_addresses": ["string"
],
"destination_addresses": ["string"
],
"destination_ports": ["string"
],
"protocol": "all",
"action": "drop",
"description": "string"
}
]
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Change the Kernel of a Server

This is most often used to boot using our provided Finnix recovery CD. Please review the 'servers/{server_id}/kernels' endpoint for more information.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_kernel"
kernel required	integer <int64> The ID of the kernel to use.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_kernel",
"kernel": 0
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Add, Update or Remove a Partner Server for a Server

Making servers 'partners' prevents them from being co-located on the same hardware.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_partner"
partner_server_id	integer or null <int64> Leave this null to remove the server partnership. The partner server must be in the same region as the target server.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_partner",
"partner_server_id": 0
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Disable SE Linux for a Server

If you have upgraded to CentOS 7.6 and rebooted your server (or an automated update has done so on your behalf) then SELinux may be preventing your system from working correctly.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "disable_selinux"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "disable_selinux"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Rebuild an Existing Server

This will restore the server to the base image provided.
NB: This is a destructive operation and no further confirmation will be requested.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "rebuild"
	(integer or null) or (string or null) The Operating System ID or slug or Backup image ID to use as a base for the rebuild.
	object or null Additional options. Leaving this entirely null or any of the properties included null will use the defaults from the existing server.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "rebuild",
"image": 5,
"options": {"name": "string",
"ssh_keys": [5
],
"user_data": "string",
"password": "string"
}
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Update the Size and Related Options for a Server

This is used to change the base size (also known as 'change plan') or many of the additional options that are available.
NB: This may be a destructive operation (e.g. if a new base image is provided the server will be rebuilt, or if the weekly backups are reduced to 0 all weekly backups will be removed) and no further confirmation will be requested.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "resize"
size	string or null The slug of the selected size. Do not provide to keep the current size.
	object or null If this is null and the server has no selected size options the defaults for the size will be used. If this is null and the server has currently selected size options those will be preserved. If this is provided any option fields that are not included will be removed from the existing server.
	object or null This may be left null to keep the current base image for the server. If this is provided the server disks will be destroyed and the server will be rebuilt from the selected image.
	object or null This may be left null to keep the current licenses for the server. If this is provided any licenses that are not included will be removed.
	object or null Specify this to create a backup before any actions are taken, or leave null to skip.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "resize",
"size": "string",
"options": {"daily_backups": 14,
"weekly_backups": 13,
"monthly_backups": 12,
"offsite_backups": true,
"service_level_id": 0,
"ipv4_addresses": 2147483647,
"memory": 0,
"disk": 0,
"transfer": 0,
"ipv4_addresses_to_remove": ["string"
]
},
"change_image": {"image": 5,
"options": {"name": "string",
"ssh_keys": [5
],
"user_data": "string",
"password": "string"
}
},
"change_licenses": {"licenses": [{"software_id": 0,
"count": 0
}
]
},
"pre_action_backup": {"type": "take_backup",
"backup_type": "daily",
"replacement_strategy": "none",
"backup_id_to_replace": 0,
"label": "string"
}
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Create an Additional Disk for a Server

This is used to add an additional disk in unallocated storage space.
This does not alter the total disk space available to your server: to add additional disk space for your server use the 'Resize' action.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "add_disk"
size_gigabytes required	integer <int32> [ 1 .. 2147483647 ] The size of the new disk in GB. The server must have at least this much unallocated storage space.
description	string or null [ 0 .. 255 ] characters An optional description for the disk. If this is null a default description will be added. Submit an empty string to prevent the default description being added.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "add_disk",
"size_gigabytes": 1,
"description": "string"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Alter the Size of an Existing Disk for a Server

This is used to alter the size of an existing disk, either to use or create unallocated storage space.
This does not alter the total disk space available to your server: to add or remove disk space for your server use the 'Resize' action.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "resize_disk"
disk_id required	integer <int64> The ID of the existing disk. See server.disks for a list of IDs.
size_gigabytes required	integer <int32> [ 1 .. 2147483647 ] The new size of the disk in GB. If increasing the size of the disk the server must have sufficient unallocated storage space.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "resize_disk",
"disk_id": 0,
"size_gigabytes": 1
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Delete an Additional Disk for a Server

This is used to delete a disk added using the 'AddDisk' action.
NB: This is a destructive operation and no further confirmation will be requested.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "delete_disk"
disk_id required	integer <int64> The ID of the existing disk. See server.disks for a list of IDs.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "delete_disk",
"disk_id": 0
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Update the IPv6 Reverse Name Servers for a Server

This is used to alter the IPv6 reverse name servers for this server.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_ipv6_reverse_nameservers"
ipv6_reverse_nameservers required	Array of strings A list of all IPv6 reverse name servers for this server. Any existing reverse name servers that are omitted from the list will be removed from the server.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_ipv6_reverse_nameservers",
"ipv6_reverse_nameservers": ["string"
]
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Change the Reverse Name for an IPv4 Address on a Server

This is used to change the reverse name for an IPv4 on this server.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_reverse_name"
ipv4_address required	string non-empty The IPv4 address to set or clear the reverse name for.
reverse_name	string or null Leave this null to clear the custom reverse name.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_reverse_name",
"ipv4_address": "string",
"reverse_name": "string"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Rename a Server

This is used to change the name of the server in our system. The name in the server's operating system will not be changed.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "rename"
name required	string non-empty The new hostname of your server, such as vps01.yourcompany.com.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "rename",
"name": "string"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Enable or Disable IPv6 for a Server

This is used to enable or disable IPv6 networking support for this server.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_ipv6"
enabled required	boolean The desired enabled status of IPv6.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_ipv6",
"enabled": true
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Change the Port Blocking for a Server

Port blocking is a security feature. In the majority of cases when a server is hacked, the attacker will then use the server to either send spam or perform brute-force authentication attacks against other servers on the internet.
This is used to enable or disable blocking of outgoing connections for email, SSH and Remote Desktop (TCP ports 22, 25, and 3389).

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_port_blocking"
enabled required	boolean The desired enabled status for port blocking.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_port_blocking",
"enabled": true
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Enable IPv6 for a Server

This is used to enable IPv6 networking support for this server.
This action is provided for compatibility reasons and as the same effect as enabling IPv6 via the "ChangeIpv6" action.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type

required

string non-empty

Value: "enable_ipv6"

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "enable_ipv6"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Move a Server to an Existing Network

This is used to move a server either to an already defined virtual private cloud, or the default public network in the server's region.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_network"
vpc_id	integer or null <int64> If this is null the server will be moved into the default public network for the server's region.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_network",
"vpc_id": 0
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Enable or Disable a Separate Private Network Interface for a Server in a VPC

This is used to enable or disable a separate second network interface for VPC network traffic (if the server is in a VPC).

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_separate_private_network_interface"
enabled required	boolean The desired enabled status of the separate second network interface.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_separate_private_network_interface",
"enabled": true
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Enable or Disable Network Source and Destination Checks for a Server in a VPC

This is used to enable or disable source and destination checks for network packets.
Source/Destination Check is a feature that controls what packets are allowed to be sent and received by your Cloud Server. When enabled (which it is by default), your server will only be able to send or receive packets that are directly addressed to one of the IP addresses associated with the Cloud Server. Generally, this is desirable behaviour because it prevents IP conflicts and other hard-to-diagnose networking faults due to incorrect network configuration.
When Source/Destination Check is disabled, your Cloud Server will be able to send and receive packets addressed to any server whatsoever. This is typically used when you want to use your Cloud Server as a VPN endpoint, a NAT server to provide internet access, or IP forwarding.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_source_and_destination_check"
enabled required	boolean The desired enabled status of the source and destination checks for network packets.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_source_and_destination_check",
"enabled": true
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Change the IPv4 Address for a Server in a VPC

This is used to change the private IPv4 address for a server in a VPC.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The ID of the server on which the action should be performed.

Request Body schema: application/json

type required	string non-empty Value: "change_vpc_ipv4"
current_ipv4_address required	string non-empty The existing Ipv4 address for the private VPC network adapter you wish to change.
new_ipv4_address required	string non-empty The new Ipv4 address for the private VPC network adapter.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"type": "change_vpc_ipv4",
"current_ipv4_address": "string",
"new_ipv4_address": "string"
}

Response samples

200
400
404
422

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Actions

Fetch an Existing Action

Authorizations:

apiToken

path Parameters

action_id

required

integer <int64>

The ID of the action to fetch.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/actions/${action_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

List All Actions

Authorizations:

apiToken

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Action)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/actions?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"actions": [{"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
]
}

Respond to a UserInteractionRequired Action

Authorizations:

apiToken

path Parameters

action_id

required

integer <int64>

The ID of the action for which this is a response.

Request Body schema: application/json

proceed

required

boolean

Please see the documentation for each type of interaction for the effect of providing 'true' or 'false' here.

Responses

Request samples

Payload
Curl

Content type

application/json

{"proceed": true
}

Response samples

404

Content type

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}

Data Usage

Fetch the Current Data Usage (Transfer) for a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The target server id.

Responses

Response Schema: application/json

required

object

server_id required	integer <int64> The ID of the server that this data transfer usage refers to.
expires required	string <date-time> The date and time in ISO8601 format that the current billing period expires.
transfer_gigabytes required	integer <int64> The included data transfer for this server in this period in GB.
current_transfer_usage_gigabytes required	number <double> The used data transfer for this server in this period in GB. If you have more than one server, please see our data pooling policy: this value may include excess data transfer used by other servers or may have 'offloaded' excess data transfer to other servers with spare capacity.
transfer_period_end required	string <date-time> The date and time in ISO8601 format that the data transfer limit period ended (if it is completed) or when it will end (if this is the current period).

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/data_usages/${server_id}/current"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"data_usage": {"server_id": 0,
"expires": "2019-08-24T14:15:22Z",
"transfer_gigabytes": 0,
"current_transfer_usage_gigabytes": 0,
"transfer_period_end": "2019-08-24T14:15:22Z"
}
}

Fetch all Current Data Usage (Transfer) for All Servers

Authorizations:

apiToken

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (DataUsage)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/data_usages/current?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"data_usages": [{"server_id": 0,
"expires": "2019-08-24T14:15:22Z",
"transfer_gigabytes": 0,
"current_transfer_usage_gigabytes": 0,
"transfer_period_end": "2019-08-24T14:15:22Z"
}
]
}

Failover IPs

Fetch the Failover IPs for a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The target server id.

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
failover_ips required	Array of strings

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/failover_ips/${server_id}?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"failover_ips": ["string"
]
}

Sets the List of Failover IPs that are Assigned to a Server

This overwrites the current list, i.e. submit the entire list, not just updates. If NoContent is returned no changes were made. If an action is returned the changes have been saved but the effect may not be complete until the action is complete. If the action does not complete the network changes can be forced by rebooting the server.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The target server id.

Request Body schema: application/json

failover_ips

required

Array of strings

The list of IP Failover addresses to assign to this server. This overwrites the current list, so any current IP Failover addresses that are omitted will be removed from the server.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"failover_ips": ["string"
]
}

Response samples

200
400
404

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Fetch a List of all Failover IPs that are Available to be Assigned to a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The target server id.

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
failover_ips required	Array of strings

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/failover_ips/${server_id}/available?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"failover_ips": ["string"
]
}

Images

List All Images

Authorizations:

apiToken

query Parameters

type	string Enum: "distribution" "backup" Queries for distribution will include images that have pre-installed applications.
private	boolean Provide 'true' to only list private images. 'false' has no effect.
page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Image)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/images?type=${type}&private=${private}&page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
400

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"images": [{"id": 0,
"name": "string",
"type": "custom",
"distribution": "string",
"full_name": "string",
"slug": "string",
"public": true,
"regions": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"min_disk_size": 0,
"size_gigabytes": 0,
"description": "string",
"status": "NEW",
"error_message": "string",
"min_memory_megabytes": 0,
"distribution_surcharges": {"surcharge_base_cost": 0,
"surcharge_per_memory_megabyte": 0,
"surcharge_per_memory_max_megabytes": 0,
"surcharge_per_vcpu": 0,
"surcharge_min_vcpu": 0
},
"distribution_info": {"image_id": 0,
"password_recovery": "manual",
"remote_access_user": "string",
"features": ["ssh"
]
},
"backup_info": {"type": "daily",
"server_id": 0,
"offsite": true,
"locked": true,
"iso": true,
"backup_disks": [{"id": 0,
"size_gigabytes": 0,
"min_disk_size": 0,
"description": "string"
}
]
}
}
]
}

Fetch an Existing Image

Authorizations:

apiToken

path Parameters

required

integer or string

Example: 5

The ID or Slug (if an operating system) of the image to retrieve.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this image.

name

required

string non-empty

If this is an operating system image, this is the name of the operating system version. If this is a backup image, this is the label of the backup if it exists, otherwise it is the UTC timestamp of the creation of the image.

type

required

string

Enum: "custom" "snapshot" "backup"

Value	Description
custom	An image uploaded by a user.
snapshot	A snapshot. Snapshot creation is not currently supported so only distribution images will have this value.
backup	A backup of a server.

distribution

string or null

If this is an operating system image, this is the name of the distribution. If this is a backup image, this is the name of the distribution the server is using.

full_name

string or null

If this is an operating system image, this is the name and version of the distribution. If this is a backup image, this is the server hostname and label of the backup if it exists, otherwise it is the server hostname and UTC timestamp of the creation of the image.

slug

string or null

If this is an operating system image this is a slug which may be used as an alternative to the ID as a reference.

public

required

boolean

A public image is available to all users. A private image is available only to the account that created the image.

regions

required

Array of strings

The slugs of the regions where the image is available for use.

created_at

string or null <date-time>

If this is a backup image this is the date and time in ISO8601 format when the image was created.

min_disk_size

required

integer <int32>

For a distribution image this is the minimum disk size in GB required to install the operating system. For a backup image this is the minimum total disk size in GB required to restore the backup.

size_gigabytes

required

number <double>

For a distribution image this is the disk size used in GB by the operating system on initial install. For a backup image this is the size of the compressed backup image in GB.

description

string or null

A description that may provide further details or warnings about the image.

status

required

string

Enum: "NEW" "available" "pending" "deleted"

Value	Description
NEW	The image is new.
available	The image is available for use.
pending	The image is pending and is not yet available for use.
deleted	The image has been deleted and is no longer available for use.

error_message

string or null

If the image creation failed this may provide further information.

min_memory_megabytes

integer or null <int32>

This is minimum memory in MB necessary to support this operating system (or the base operating system for a backup image).

object or null

If this is not null the use of this image may incur surcharges above the base cost of the server. All costs are in AU$.

required

object

This object may provide further information about the distribution.

object or null

If this image is a backup, this object will provide further information.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/images/${image_id_or_slug}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"image": {"id": 0,
"name": "string",
"type": "custom",
"distribution": "string",
"full_name": "string",
"slug": "string",
"public": true,
"regions": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"min_disk_size": 0,
"size_gigabytes": 0,
"description": "string",
"status": "NEW",
"error_message": "string",
"min_memory_megabytes": 0,
"distribution_surcharges": {"surcharge_base_cost": 0,
"surcharge_per_memory_megabyte": 0,
"surcharge_per_memory_max_megabytes": 0,
"surcharge_per_vcpu": 0,
"surcharge_min_vcpu": 0
},
"distribution_info": {"image_id": 0,
"password_recovery": "manual",
"remote_access_user": "string",
"features": ["ssh"
]
},
"backup_info": {"type": "daily",
"server_id": 0,
"offsite": true,
"locked": true,
"iso": true,
"backup_disks": [{"id": 0,
"size_gigabytes": 0,
"min_disk_size": 0,
"description": "string"
}
]
}
}
}

Update an Existing Image

Only updating of user created backups is currently supported.

Authorizations:

apiToken

path Parameters

image_id

required

integer <int64>

The ID of the image to update.

Request Body schema: application/json

name	string or null [ 0 .. 250 ] characters Optional: a new display name for this image. Do not provide to leave the display name unchanged, submit an empty string to clear the display name.
locked	boolean or null Optional: you may choose to lock an individual backup in which case we will not update that backup until you unlock it. Do not provide to leave the locked status unchanged.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this image.

name

required

string non-empty

If this is an operating system image, this is the name of the operating system version. If this is a backup image, this is the label of the backup if it exists, otherwise it is the UTC timestamp of the creation of the image.

type

required

string

Enum: "custom" "snapshot" "backup"

Value	Description
custom	An image uploaded by a user.
snapshot	A snapshot. Snapshot creation is not currently supported so only distribution images will have this value.
backup	A backup of a server.

distribution

string or null

If this is an operating system image, this is the name of the distribution. If this is a backup image, this is the name of the distribution the server is using.

full_name

string or null

If this is an operating system image, this is the name and version of the distribution. If this is a backup image, this is the server hostname and label of the backup if it exists, otherwise it is the server hostname and UTC timestamp of the creation of the image.

slug

string or null

If this is an operating system image this is a slug which may be used as an alternative to the ID as a reference.

public

required

boolean

A public image is available to all users. A private image is available only to the account that created the image.

regions

required

Array of strings

The slugs of the regions where the image is available for use.

created_at

string or null <date-time>

If this is a backup image this is the date and time in ISO8601 format when the image was created.

min_disk_size

required

integer <int32>

For a distribution image this is the minimum disk size in GB required to install the operating system. For a backup image this is the minimum total disk size in GB required to restore the backup.

size_gigabytes

required

number <double>

For a distribution image this is the disk size used in GB by the operating system on initial install. For a backup image this is the size of the compressed backup image in GB.

description

string or null

A description that may provide further details or warnings about the image.

status

required

string

Enum: "NEW" "available" "pending" "deleted"

Value	Description
NEW	The image is new.
available	The image is available for use.
pending	The image is pending and is not yet available for use.
deleted	The image has been deleted and is no longer available for use.

error_message

string or null

If the image creation failed this may provide further information.

min_memory_megabytes

integer or null <int32>

This is minimum memory in MB necessary to support this operating system (or the base operating system for a backup image).

object or null

If this is not null the use of this image may incur surcharges above the base cost of the server. All costs are in AU$.

required

object

This object may provide further information about the distribution.

object or null

If this image is a backup, this object will provide further information.

Request samples

Payload
Curl

Content type

application/json

{"name": "string",
"locked": true
}

Response samples

200
400
404

Content type

application/json

{"image": {"id": 0,
"name": "string",
"type": "custom",
"distribution": "string",
"full_name": "string",
"slug": "string",
"public": true,
"regions": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"min_disk_size": 0,
"size_gigabytes": 0,
"description": "string",
"status": "NEW",
"error_message": "string",
"min_memory_megabytes": 0,
"distribution_surcharges": {"surcharge_base_cost": 0,
"surcharge_per_memory_megabyte": 0,
"surcharge_per_memory_max_megabytes": 0,
"surcharge_per_vcpu": 0,
"surcharge_min_vcpu": 0
},
"distribution_info": {"image_id": 0,
"password_recovery": "manual",
"remote_access_user": "string",
"features": ["ssh"
]
},
"backup_info": {"type": "daily",
"server_id": 0,
"offsite": true,
"locked": true,
"iso": true,
"backup_disks": [{"id": 0,
"size_gigabytes": 0,
"min_disk_size": 0,
"description": "string"
}
]
}
}
}

Download an Existing Image

Only user created backup images are currently available for download.

Authorizations:

apiToken

path Parameters

image_id

required

integer <int64>

The ID of the image to download.

Responses

Response Schema: application/json

required

object

id required	integer <int64> The ID of the image this download object refers to.
expiry required	string <date-time> The date and time in ISO8601 format that this download URL will expire.
required	Array of objects (ImageDiskDownload) A list of objects containing the download URLs for each disk in the image.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/images/${image_id}/download"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"link": {"id": 0,
"expiry": "2019-08-24T14:15:22Z",
"disks": [{"id": 0,
"compressed_url": "string",
"raw_url": "string"
}
]
}
}

Keys

Fetch an Existing SSH Key

The key_id may be either the Id or the key fingerprint.

Authorizations:

apiToken

path Parameters

required

integer or string

Example: 5

The ID or fingerprint of the SSH Key to fetch.

Responses

Response Schema: application/json

required

object

id required	integer <int64> The ID of this SSH key.
fingerprint required	string non-empty The fingerprint of this SSH key.
public_key required	string non-empty The public key of this SSH key.
name	string or null The name of this SSH key. This is used only to aid in identification.
default required	boolean If an SSH key is marked as default it will be deployed to all newly created servers that support SSH keys unless expressly overridden in the creation request.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/account/keys/${key_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"ssh_key": {"id": 0,
"fingerprint": "string",
"public_key": "string",
"name": "string",
"default": true
}
}

Update an Existing SSH Key

The key_id may be either the Id or the key fingerprint.

Authorizations:

apiToken

path Parameters

required

integer or string

Example: 5

The ID or fingerprint of the SSH Key to update.

Request Body schema: application/json

name required	string non-empty A name to help you identify the key.
default	boolean or null Do not provide or leave null to leave the default status of the key unchanged. Optional: If true this will be added to all new server installations (if we support SSH Key injection for the server's operating system).

Responses

Response Schema: application/json

required

object

id required	integer <int64> The ID of this SSH key.
fingerprint required	string non-empty The fingerprint of this SSH key.
public_key required	string non-empty The public key of this SSH key.
name	string or null The name of this SSH key. This is used only to aid in identification.
default required	boolean If an SSH key is marked as default it will be deployed to all newly created servers that support SSH keys unless expressly overridden in the creation request.

Request samples

Payload
Curl

Content type

application/json

{"name": "string",
"default": true
}

Response samples

200
400
404

Content type

application/json

{"ssh_key": {"id": 0,
"fingerprint": "string",
"public_key": "string",
"name": "string",
"default": true
}
}

Delete an Existing SSH Key

The key_id may be either the Id or the key fingerprint.

Authorizations:

apiToken

path Parameters

required

integer or string

Example: 5

The ID or fingerprint of the SSH Key to delete.

Responses

Request samples

Curl

curl -X DELETE "https://api.mammoth.com.au/v2/account/keys/${key_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

404

Content type

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}

List All SSH Keys

Authorizations:

apiToken

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (SshKey)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/account/keys?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"ssh_keys": [{"id": 0,
"fingerprint": "string",
"public_key": "string",
"name": "string",
"default": true
}
]
}

Add a New SSH Key

Authorizations:

apiToken

Request Body schema: application/json

public_key required	string non-empty The public key in OpenSSH "authorized_keys" format.
name required	string non-empty A name to help you identify the key.
default	boolean or null Optional: If true this will be added to all new server installations (if we support SSH Key injection for the server's operating system).

Responses

Response Schema: application/json

required

object

id required	integer <int64> The ID of this SSH key.
fingerprint required	string non-empty The fingerprint of this SSH key.
public_key required	string non-empty The public key of this SSH key.
name	string or null The name of this SSH key. This is used only to aid in identification.
default required	boolean If an SSH key is marked as default it will be deployed to all newly created servers that support SSH keys unless expressly overridden in the creation request.

Request samples

Payload
Curl

Content type

application/json

{"public_key": "string",
"name": "string",
"default": true
}

Response samples

200
400

Content type

application/json

{"ssh_key": {"id": 0,
"fingerprint": "string",
"public_key": "string",
"name": "string",
"default": true
}
}

Reverse Names

Fetch all Existing IPv6 Name Server Records

IPv6 addresses within the allocated IPv6 floating range do not have PTR records under our default configuration. You may provide resolution by delegating PTR lookups to your own nameservers. These nameservers - and the floating range itself - are shared by all your servers; PTR lookups for addresses within your routed range will also be delegated.

Authorizations:

apiToken

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
reverse_nameservers required	Array of strings

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/reverse_names/ipv6?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"reverse_nameservers": ["string"
]
}

Create New or Update Existing Global IPv6 Name Server Records

Authorizations:

apiToken

Request Body schema: application/json

reverse_nameservers

required

Array of strings

A list of IPv6 reverse name servers for all IPv6 enabled servers. Any existing reverse name servers that are omitted from the list will be removed.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this action.

status

required

string

Enum: "in-progress" "completed" "errored"

Value	Description
in-progress	This action is currently in progress.
completed	This action has successfully completed.
errored	An error was encountered while processing the action.

type

required

string non-empty

The type of this action.

started_at

required

string <date-time>

The timestamp in ISO8601 format of when processing of this action started.

completed_at

string or null <date-time>

The timestamp in ISO8601 format of when processing of this action completed. If this value is null the action is currently in progress.

resource_type

string or null

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

The resource type (if any) associated with this action.

resource_id

integer or null <int64>

The resource id of the resource (if any) associated with this action.

object or null

The region (if any) of the resource associated with this action.

region_slug

string or null

The region slug (if any) of the resource associated with this action.

required

object

Information about the current progress of the action. Some actions are divided into 'steps' and this may also contain information about the current and completed steps.

result_data

string or null

Returned information from a completed action. For example: a successful completed 'ping' action will have the ping value in ms in this field.

blocking_invoice_id

integer or null <int64>

If this Action is currently blocked by an invoice that requires payment this property will be set.

object or null

If this is not null the action is waiting on a response from the user.

Request samples

Payload
Curl

Content type

application/json

{"reverse_nameservers": ["string"
]
}

Response samples

200
400
404

Content type

application/json

{"action": {"id": 0,
"status": "in-progress",
"type": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"resource_type": "server",
"resource_id": 0,
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"region_slug": "string",
"progress": {"current_step_detail": "string",
"percent_complete": 0,
"current_step": "string",
"completed_steps": ["string"
]
},
"result_data": "string",
"blocking_invoice_id": 0,
"user_interaction_required": {"interaction_type": "continue-after-ping-failure"
}
}
}

Sample Sets

Fetch the Latest Performance and Usage Data Sample Set for a Server

Returns the latest performance and usage sample set.

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The target server id.

query Parameters

data_interval

string

Enum: "five-minute" "half-hour" "four-hour" "day" "week" "month"

Value	Description
five-minute	5 Minutes
half-hour	30 Minutes
four-hour	4 Hours
day	1 Day
week	7 Days
month	1 Month

Responses

Response Schema: application/json

object or null

server_id required	integer <int64> The ID of the server that this sample set refers to.
required	object The period when this sample set was collected.
required	object The average values of the samples collected during this period.
maximum_memory_megabytes required	number <double> The maximum memory used in MB at any point during this collection period.
maximum_storage_gigabytes required	number <double> The maximum storage used in GB at any point during this collection period.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/samplesets/${server_id}/latest?data_interval=${data_interval}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"sample_set": {"server_id": 0,
"period": {"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"data_interval": "five-minute"
},
"average": {"cpu_usage_percent": 0,
"cpu_usage_detailed": [0
],
"memory_usage_bytes": 0,
"network_incoming_kbps": 0,
"network_outgoing_kbps": 0,
"storage_usage_megabytes": 0,
"storage_read_kbps": 0,
"storage_write_kbps": 0,
"storage_read_requests_per_second": 0,
"storage_write_requests_per_second": 0
},
"maximum_memory_megabytes": 0,
"maximum_storage_gigabytes": 0
}
}

Fetch all of the Performance and Usage Data Sample Sets for a Server

Authorizations:

apiToken

path Parameters

server_id

required

integer <int64>

The target server id.

query Parameters

data_interval

string

Enum: "five-minute" "half-hour" "four-hour" "day" "week" "month"

Value	Description
five-minute	5 Minutes
half-hour	30 Minutes
four-hour	4 Hours
day	1 Day
week	7 Days
month	1 Month

start

string <date-time>

The start of the window of samples to retrieve, ISO8601 format (eg 2022-12-30T22:50:00Z). Defaults to 1 week before end for intervals larger than 5 minutes, or 1 day for 5 minute intervals.

end

string <date-time>

The start of the window of samples to retrieve, ISO8601 format (eg 2022-12-30T22:50:00Z). Defaults to 1 week or 1 day after start date depending on the selected data interval (or the current time if start is not provided). Can't be more than 1 year from start.

page

integer <int32> [ 1 .. 2147483647 ]

Default: 1

The selected page. Page numbering starts at 1

per_page

integer <int32> [ 1 .. 200 ]

Default: 20

The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (SampleSet)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/samplesets/${server_id}?data_interval=${data_interval}&start=${start}&end=${end}&page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
400
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"sample_sets": [{"server_id": 0,
"period": {"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"data_interval": "five-minute"
},
"average": {"cpu_usage_percent": 0,
"cpu_usage_detailed": [0
],
"memory_usage_bytes": 0,
"network_incoming_kbps": 0,
"network_outgoing_kbps": 0,
"storage_usage_megabytes": 0,
"storage_read_kbps": 0,
"storage_write_kbps": 0,
"storage_read_requests_per_second": 0,
"storage_write_requests_per_second": 0
},
"maximum_memory_megabytes": 0,
"maximum_storage_gigabytes": 0
}
]
}

Images

List All Images

Authorizations:

apiToken

query Parameters

type	string Enum: "distribution" "backup" Queries for distribution will include images that have pre-installed applications.
private	boolean Provide 'true' to only list private images. 'false' has no effect.
page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Image)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/images?type=${type}&private=${private}&page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
400

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"images": [{"id": 0,
"name": "string",
"type": "custom",
"distribution": "string",
"full_name": "string",
"slug": "string",
"public": true,
"regions": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"min_disk_size": 0,
"size_gigabytes": 0,
"description": "string",
"status": "NEW",
"error_message": "string",
"min_memory_megabytes": 0,
"distribution_surcharges": {"surcharge_base_cost": 0,
"surcharge_per_memory_megabyte": 0,
"surcharge_per_memory_max_megabytes": 0,
"surcharge_per_vcpu": 0,
"surcharge_min_vcpu": 0
},
"distribution_info": {"image_id": 0,
"password_recovery": "manual",
"remote_access_user": "string",
"features": ["ssh"
]
},
"backup_info": {"type": "daily",
"server_id": 0,
"offsite": true,
"locked": true,
"iso": true,
"backup_disks": [{"id": 0,
"size_gigabytes": 0,
"min_disk_size": 0,
"description": "string"
}
]
}
}
]
}

Fetch an Existing Image

Authorizations:

apiToken

path Parameters

required

integer or string

Example: 5

The ID or Slug (if an operating system) of the image to retrieve.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this image.

name

required

string non-empty

If this is an operating system image, this is the name of the operating system version. If this is a backup image, this is the label of the backup if it exists, otherwise it is the UTC timestamp of the creation of the image.

type

required

string

Enum: "custom" "snapshot" "backup"

Value	Description
custom	An image uploaded by a user.
snapshot	A snapshot. Snapshot creation is not currently supported so only distribution images will have this value.
backup	A backup of a server.

distribution

string or null

If this is an operating system image, this is the name of the distribution. If this is a backup image, this is the name of the distribution the server is using.

full_name

string or null

If this is an operating system image, this is the name and version of the distribution. If this is a backup image, this is the server hostname and label of the backup if it exists, otherwise it is the server hostname and UTC timestamp of the creation of the image.

slug

string or null

If this is an operating system image this is a slug which may be used as an alternative to the ID as a reference.

public

required

boolean

A public image is available to all users. A private image is available only to the account that created the image.

regions

required

Array of strings

The slugs of the regions where the image is available for use.

created_at

string or null <date-time>

If this is a backup image this is the date and time in ISO8601 format when the image was created.

min_disk_size

required

integer <int32>

For a distribution image this is the minimum disk size in GB required to install the operating system. For a backup image this is the minimum total disk size in GB required to restore the backup.

size_gigabytes

required

number <double>

For a distribution image this is the disk size used in GB by the operating system on initial install. For a backup image this is the size of the compressed backup image in GB.

description

string or null

A description that may provide further details or warnings about the image.

status

required

string

Enum: "NEW" "available" "pending" "deleted"

Value	Description
NEW	The image is new.
available	The image is available for use.
pending	The image is pending and is not yet available for use.
deleted	The image has been deleted and is no longer available for use.

error_message

string or null

If the image creation failed this may provide further information.

min_memory_megabytes

integer or null <int32>

This is minimum memory in MB necessary to support this operating system (or the base operating system for a backup image).

object or null

If this is not null the use of this image may incur surcharges above the base cost of the server. All costs are in AU$.

required

object

This object may provide further information about the distribution.

object or null

If this image is a backup, this object will provide further information.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/images/${image_id_or_slug}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"image": {"id": 0,
"name": "string",
"type": "custom",
"distribution": "string",
"full_name": "string",
"slug": "string",
"public": true,
"regions": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"min_disk_size": 0,
"size_gigabytes": 0,
"description": "string",
"status": "NEW",
"error_message": "string",
"min_memory_megabytes": 0,
"distribution_surcharges": {"surcharge_base_cost": 0,
"surcharge_per_memory_megabyte": 0,
"surcharge_per_memory_max_megabytes": 0,
"surcharge_per_vcpu": 0,
"surcharge_min_vcpu": 0
},
"distribution_info": {"image_id": 0,
"password_recovery": "manual",
"remote_access_user": "string",
"features": ["ssh"
]
},
"backup_info": {"type": "daily",
"server_id": 0,
"offsite": true,
"locked": true,
"iso": true,
"backup_disks": [{"id": 0,
"size_gigabytes": 0,
"min_disk_size": 0,
"description": "string"
}
]
}
}
}

Update an Existing Image

Only updating of user created backups is currently supported.

Authorizations:

apiToken

path Parameters

image_id

required

integer <int64>

The ID of the image to update.

Request Body schema: application/json

name	string or null [ 0 .. 250 ] characters Optional: a new display name for this image. Do not provide to leave the display name unchanged, submit an empty string to clear the display name.
locked	boolean or null Optional: you may choose to lock an individual backup in which case we will not update that backup until you unlock it. Do not provide to leave the locked status unchanged.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this image.

name

required

string non-empty

If this is an operating system image, this is the name of the operating system version. If this is a backup image, this is the label of the backup if it exists, otherwise it is the UTC timestamp of the creation of the image.

type

required

string

Enum: "custom" "snapshot" "backup"

Value	Description
custom	An image uploaded by a user.
snapshot	A snapshot. Snapshot creation is not currently supported so only distribution images will have this value.
backup	A backup of a server.

distribution

string or null

If this is an operating system image, this is the name of the distribution. If this is a backup image, this is the name of the distribution the server is using.

full_name

string or null

If this is an operating system image, this is the name and version of the distribution. If this is a backup image, this is the server hostname and label of the backup if it exists, otherwise it is the server hostname and UTC timestamp of the creation of the image.

slug

string or null

If this is an operating system image this is a slug which may be used as an alternative to the ID as a reference.

public

required

boolean

A public image is available to all users. A private image is available only to the account that created the image.

regions

required

Array of strings

The slugs of the regions where the image is available for use.

created_at

string or null <date-time>

If this is a backup image this is the date and time in ISO8601 format when the image was created.

min_disk_size

required

integer <int32>

For a distribution image this is the minimum disk size in GB required to install the operating system. For a backup image this is the minimum total disk size in GB required to restore the backup.

size_gigabytes

required

number <double>

For a distribution image this is the disk size used in GB by the operating system on initial install. For a backup image this is the size of the compressed backup image in GB.

description

string or null

A description that may provide further details or warnings about the image.

status

required

string

Enum: "NEW" "available" "pending" "deleted"

Value	Description
NEW	The image is new.
available	The image is available for use.
pending	The image is pending and is not yet available for use.
deleted	The image has been deleted and is no longer available for use.

error_message

string or null

If the image creation failed this may provide further information.

min_memory_megabytes

integer or null <int32>

This is minimum memory in MB necessary to support this operating system (or the base operating system for a backup image).

object or null

If this is not null the use of this image may incur surcharges above the base cost of the server. All costs are in AU$.

required

object

This object may provide further information about the distribution.

object or null

If this image is a backup, this object will provide further information.

Request samples

Payload
Curl

Content type

application/json

{"name": "string",
"locked": true
}

Response samples

200
400
404

Content type

application/json

{"image": {"id": 0,
"name": "string",
"type": "custom",
"distribution": "string",
"full_name": "string",
"slug": "string",
"public": true,
"regions": ["string"
],
"created_at": "2019-08-24T14:15:22Z",
"min_disk_size": 0,
"size_gigabytes": 0,
"description": "string",
"status": "NEW",
"error_message": "string",
"min_memory_megabytes": 0,
"distribution_surcharges": {"surcharge_base_cost": 0,
"surcharge_per_memory_megabyte": 0,
"surcharge_per_memory_max_megabytes": 0,
"surcharge_per_vcpu": 0,
"surcharge_min_vcpu": 0
},
"distribution_info": {"image_id": 0,
"password_recovery": "manual",
"remote_access_user": "string",
"features": ["ssh"
]
},
"backup_info": {"type": "daily",
"server_id": 0,
"offsite": true,
"locked": true,
"iso": true,
"backup_disks": [{"id": 0,
"size_gigabytes": 0,
"min_disk_size": 0,
"description": "string"
}
]
}
}
}

Download an Existing Image

Only user created backup images are currently available for download.

Authorizations:

apiToken

path Parameters

image_id

required

integer <int64>

The ID of the image to download.

Responses

Response Schema: application/json

required

object

id required	integer <int64> The ID of the image this download object refers to.
expiry required	string <date-time> The date and time in ISO8601 format that this download URL will expire.
required	Array of objects (ImageDiskDownload) A list of objects containing the download URLs for each disk in the image.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/images/${image_id}/download"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"link": {"id": 0,
"expiry": "2019-08-24T14:15:22Z",
"disks": [{"id": 0,
"compressed_url": "string",
"raw_url": "string"
}
]
}
}

Regions

List all Regions

Authorizations:

apiToken

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Region)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/regions?page=${page}&per_page=${per_page}"  \

Response samples

200

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"regions": [{"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
}
]
}

Sizes

List All Available Sizes

Authorizations:

apiToken

query Parameters

server_id	integer <int64> If supplied only sizes available for a resize the specified server will be returned. This parameter is only available when authenticated.
	integer or string Example: image=5 If null or not provided regions that support the size are included in the returned objects regardless of operating system. If this is provided it must be the id or slug of an operating system image and will cause only valid regions for the size and operating system to be included in the returned objects.
page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Size)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/sizes?server_id=${server_id}&image=${image}&page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
400

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"sizes": [{"slug": "string",
"description": "string",
"cpu_description": "string",
"storage_description": "string",
"size_type": {"slug": "string",
"name": "string",
"description": "string"
},
"available": true,
"regions": ["string"
],
"regions_out_of_stock": ["string"
],
"price_monthly": 0,
"price_hourly": 0,
"distribution_surcharge_credit_monthly": 0,
"disk": 0,
"memory": 0,
"transfer": 0,
"excess_transfer_cost_per_gigabyte": 0,
"vcpus": 0,
"vcpu_units": "string",
"options": {"disk_min": 0,
"disk_max": 0,
"disk_cost_per_additional_gigabyte": 0,
"restricted_disk_values": [0
],
"memory_max": 0,
"memory_cost_per_additional_megabyte": 0,
"transfer_max": 0,
"transfer_cost_per_additional_gigabyte": 0,
"ipv4_addresses_max": 0,
"ipv4_addresses_cost_per_address": 0,
"discount_for_no_public_ipv4": 0,
"daily_backups": 0,
"weekly_backups": 0,
"monthly_backups": 0,
"backups_cost_per_backup_per_gigabyte": 0,
"offsite_backups_cost_per_gigabyte": 0,
"offsite_backup_frequency_cost": {"daily_per_gigabyte": 0,
"weekly_per_gigabyte": 0,
"monthly_per_gigabyte": 0
}
}
}
]
}

List Payment Frequency Discount Information

Authorizations:

apiToken

Responses

Response Schema: application/json

required

object

required

Array of objects (PaymentFrequencyDiscount)

Array

payment_frequency required	string non-empty The payment_frequency that this discount applies to.
discount_percentage required	number <double> The discount percentage for this payment_frequency. 10 = 10% discount etc.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/sizes/discounts"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"payment_frequency_discounts": {"percentage_discounts_for_each_duration": [{"payment_frequency": "string",
"discount_percentage": 0
}
]
}
}

Service Level Summary Information

Authorizations:

apiToken

Responses

Response Schema: application/json

required

Array of objects (ServiceLevel)

Array

id required	integer <int64> The ID of this Service Level.
name	string or null The name of this Service Level.
summary	string or null A summary of what this Service Level provides. Please see our website for more details, including the monthly cost.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/sizes/service-levels"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"service_levels": [{"id": 0,
"name": "string",
"summary": "string"
}
]
}

Software

Fetch Existing Software

Authorizations:

apiToken

path Parameters

software_id

required

integer <int64>

The ID of the software to fetch.

Responses

Response Schema: application/json

required

object

id required	integer <int64> The ID of this software.
enabled required	boolean Software that is not enabled is not available to be added to servers but may be retained by servers that currently use it.
name required	string non-empty The name of this software.
description required	string non-empty The description of this software.
cost_per_licence_per_month required	number <double> The cost for each licence of this software per month in AU$.
minimum_licence_count required	integer <int32> The minimum licences permitted for this software.
maximum_licence_count required	integer <int32> The maximum licences permitted for this software.
licence_step_count required	integer <int32> Licences must be purchased in multiples of this value.
group	string or null Software in the same group may not be licensed together.
supported_operating_systems required	Array of strings A list of slugs of operating system images that support this software.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/software/${software_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"software": {"id": 0,
"enabled": true,
"name": "string",
"description": "string",
"cost_per_licence_per_month": 0,
"minimum_licence_count": 0,
"maximum_licence_count": 0,
"licence_step_count": 0,
"group": "string",
"supported_operating_systems": ["string"
]
}
}

List All Available Software

Authorizations:

apiToken

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Software)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/software?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"software": [{"id": 0,
"enabled": true,
"name": "string",
"description": "string",
"cost_per_licence_per_month": 0,
"minimum_licence_count": 0,
"maximum_licence_count": 0,
"licence_step_count": 0,
"group": "string",
"supported_operating_systems": ["string"
]
}
]
}

List All Available Software for an Existing Operating System

If any software for the operating system has a non null value for the group property, one (and only one) of the software from each group must be selected. There may be a software in each group with a licence_step_count value of -1 that may be selected to indicate the software from that group is not required.

Authorizations:

apiToken

path Parameters

required

integer or string

Example: 5

The ID or slug of the operating system for which available software should be listed.

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Software)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/software/operating_system/${operating_system_id_or_slug}?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
400
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"software": [{"id": 0,
"enabled": true,
"name": "string",
"description": "string",
"cost_per_licence_per_month": 0,
"minimum_licence_count": 0,
"maximum_licence_count": 0,
"licence_step_count": 0,
"group": "string",
"supported_operating_systems": ["string"
]
}
]
}

Load Balancers

Fetch an Existing Load Balancer

Authorizations:

apiToken

path Parameters

load_balancer_id

required

integer <int64>

The ID of the load balancer to fetch.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of the load balancer.

name

required

string non-empty

The hostname of the load balancer.

ip

required

string non-empty

The IPv4 address of the load balancer.

status

required

string

Enum: "new" "active" "errored"

Value	Description
new	The load balancer is currently being built and is not ready to accept connections.
active	The load balancer is available.
errored	The load balancer is in an errored state.

created_at

required

string <date-time>

The date and time in ISO8601 format of the creation of the load balancer.

required

Array of objects (ForwardingRule)

The rules that control which traffic the load balancer will forward to servers in the pool.

required

object

The rules that determine which servers are considered 'healthy' and in the server pool for the load balancer.

object or null

The region the load balancer is located in. If this value is null the load balancer is an 'AnyCast' load balancer.

server_ids

required

Array of integers <int64> [ items <int64 > ]

The server IDs of the servers that are currently in the load balancer pool (regardless of their current 'health').

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/load_balancers/${load_balancer_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"load_balancer": {"id": 0,
"name": "string",
"ip": "string",
"status": "new",
"created_at": "2019-08-24T14:15:22Z",
"forwarding_rules": [{"entry_protocol": "http"
}
],
"health_check": {"protocol": "http",
"path": "string"
},
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"server_ids": [0
]
}
}

Update an Existing Load Balancer

Any existing settings or servers that are not included will revert to default values.

Authorizations:

apiToken

path Parameters

load_balancer_id

required

integer <int64>

The ID of the load balancer to update.

Request Body schema: application/json

name required	string non-empty The hostname of the load balancer.
	Array of objects or null (ForwardingRule) The rules that control which traffic the load balancer will forward to servers in the pool. Leave null to accept a default "HTTP" only forwarding rule.
	object or null The rules that determine which servers are considered 'healthy' and in the server pool for the load balancer. Leave this null to accept appropriate defaults based on the forwarding_rules.
server_ids	Array of integers or null <int64> A list of server IDs to assign to this load balancer.

Responses

Response Schema: application/json

required	object
	object or null

Request samples

Payload
Curl

Content type

application/json

{"name": "string",
"forwarding_rules": [{"entry_protocol": "http"
}
],
"health_check": {"protocol": "http",
"path": "string"
},
"server_ids": [0
]
}

Response samples

200
400
404

Content type

application/json

{"load_balancer": {"id": 0,
"name": "string",
"ip": "string",
"status": "new",
"created_at": "2019-08-24T14:15:22Z",
"forwarding_rules": [{"entry_protocol": "http"
}
],
"health_check": {"protocol": "http",
"path": "string"
},
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"server_ids": [0
]
},
"links": {"actions": [{"id": 0,
"rel": "string",
"href": "string"
}
]
}
}

Cancel an Existing Load Balancer

Authorizations:

apiToken

path Parameters

load_balancer_id

required

integer <int64>

The ID of the load balancer to cancel.

Responses

Request samples

Curl

curl -X DELETE "https://api.mammoth.com.au/v2/load_balancers/${load_balancer_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

404

Content type

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}

List all Load Balancers

Authorizations:

apiToken

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (LoadBalancer)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/load_balancers?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"load_balancers": [{"id": 0,
"name": "string",
"ip": "string",
"status": "new",
"created_at": "2019-08-24T14:15:22Z",
"forwarding_rules": [{"entry_protocol": "http"
}
],
"health_check": {"protocol": "http",
"path": "string"
},
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"server_ids": [0
]
}
]
}

Create a New Load Balancer

Authorizations:

apiToken

Request Body schema: application/json

name required	string non-empty The hostname of the load balancer.
	Array of objects or null (ForwardingRule) The rules that control which traffic the load balancer will forward to servers in the pool. Leave null to accept a default "HTTP" only forwarding rule.
	object or null The rules that determine which servers are considered 'healthy' and in the server pool for the load balancer. Leave this null to accept appropriate defaults based on the forwarding_rules.
server_ids	Array of integers or null <int64> A list of server IDs to assign to this load balancer.
region	string or null Leave null to create an anycast load balancer.

Responses

Response Schema: application/json

required	object
required	object

Request samples

Payload
Curl

Content type

application/json

{"name": "string",
"forwarding_rules": [{"entry_protocol": "http"
}
],
"health_check": {"protocol": "http",
"path": "string"
},
"server_ids": [0
],
"region": "string"
}

Response samples

200
400
422

Content type

application/json

{"load_balancer": {"id": 0,
"name": "string",
"ip": "string",
"status": "new",
"created_at": "2019-08-24T14:15:22Z",
"forwarding_rules": [{"entry_protocol": "http"
}
],
"health_check": {"protocol": "http",
"path": "string"
},
"region": {"slug": "string",
"name": "string",
"sizes": ["string"
],
"available": true,
"features": ["string"
],
"name_servers": ["string"
]
},
"server_ids": [0
]
},
"links": {"actions": [{"id": 0,
"rel": "string",
"href": "string"
}
]
}
}

Fetch Load Balancer Availability and Pricing

Authorizations:

apiToken

Responses

Response Schema: application/json

required

Array of objects (LoadBalancerAvailabilityOption)

Array

regions	Array of strings or null The slugs of regions where this load balancer option is available. If this is an Anycast load balancer option this will be null.
anycast required	boolean If true this is an Anycast load balancer option.
price_monthly required	number <double> Monthly Price in AU$.
price_hourly required	number <double> Hourly price in AU$.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/load_balancers/availability"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"load_balancer_availability_options": [{"regions": ["string"
],
"anycast": true,
"price_monthly": 0,
"price_hourly": 0
}
]
}

Add Servers to an Existing Load Balancer

Authorizations:

apiToken

path Parameters

load_balancer_id

required

integer <int64>

The ID of the load balancer to which servers should be added.

Request Body schema: application/json

server_ids

required

Array of integers <int64> [ items <int64 > ]

A list of server IDs.

Responses

Request samples

Payload
Curl

Content type

application/json

{"server_ids": [0
]
}

Response samples

400
404
422

Content type

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"errors": {"property1": ["string"
],
"property2": ["string"
]
},
"property1": null,
"property2": null
}

Remove Servers from an Existing Load Balancer

Authorizations:

apiToken

path Parameters

load_balancer_id

required

integer <int64>

The ID of the load balancer for which servers should be removed.

Request Body schema: application/json

server_ids

required

Array of integers <int64> [ items <int64 > ]

A list of server IDs.

Responses

Request samples

Payload
Curl

Content type

application/json

{"server_ids": [0
]
}

Response samples

400
404
422

Content type

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"errors": {"property1": ["string"
],
"property2": ["string"
]
},
"property1": null,
"property2": null
}

Add Forwarding Rules to an Existing Load Balancer

Authorizations:

apiToken

path Parameters

load_balancer_id

required

integer <int64>

The ID of the load balancer to which forwarding rules should be added.

Request Body schema: application/json

required

Array of objects (ForwardingRule)

The rules that control which traffic the load balancer will forward to servers in the pool.

Array

entry_protocol

required

string

Enum: "http" "https"

The protocol that traffic must match for this load balancer to forward traffic according to this rule.

Responses

Request samples

Payload
Curl

Content type

application/json

{"forwarding_rules": [{"entry_protocol": "http"
}
]
}

Response samples

400
404

Content type

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"errors": {"property1": ["string"
],
"property2": ["string"
]
},
"property1": null,
"property2": null
}

Remove Forwarding Rules from an Existing Load Balancer

Authorizations:

apiToken

path Parameters

load_balancer_id

required

integer <int64>

The ID of the load balancer for which forwarding rules should be removed.

Request Body schema: application/json

required

Array of objects (ForwardingRule)

The rules that control which traffic the load balancer will forward to servers in the pool.

Array

entry_protocol

required

string

Enum: "http" "https"

The protocol that traffic must match for this load balancer to forward traffic according to this rule.

Responses

Request samples

Payload
Curl

Content type

application/json

{"forwarding_rules": [{"entry_protocol": "http"
}
]
}

Response samples

400
404

Content type

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"errors": {"property1": ["string"
],
"property2": ["string"
]
},
"property1": null,
"property2": null
}

Virtual Private Cloud

Fetch an Existing VPC

Authorizations:

apiToken

path Parameters

vpc_id

required

integer <int64>

The target vpc id.

Responses

Response Schema: application/json

required

object

id required	integer <int64> The ID of this VPC.
name required	string non-empty The name of this VPC.
ip_range required	string non-empty The IPv4 range for this VPC in CIDR format.
required	Array of objects (RouteEntry) The route entries that control how network traffic is directed through the VPC environment.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/vpcs/${vpc_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"vpc": {"id": 0,
"name": "string",
"ip_range": "string",
"route_entries": [{"router": "string",
"destination": "string",
"description": "string"
}
]
}
}

Update an Existing VPC

Anything not included in this will be removed, especially route entries.

Authorizations:

apiToken

path Parameters

vpc_id

required

integer <int64>

The target vpc id.

Request Body schema: application/json

name required	string [ 0 .. 250 ] characters A name to help identify this VPC.
	Array of objects or null (RouteEntryRequest) The route entries that control how network traffic is directed through the VPC environment.

Responses

Response Schema: application/json

required

object

id required	integer <int64> The ID of this VPC.
name required	string non-empty The name of this VPC.
ip_range required	string non-empty The IPv4 range for this VPC in CIDR format.
required	Array of objects (RouteEntry) The route entries that control how network traffic is directed through the VPC environment.

Request samples

Payload
Curl

Content type

application/json

{"name": "string",
"route_entries": [{"router": "string",
"destination": "string",
"description": "string"
}
]
}

Response samples

200
400
404

Content type

application/json

{"vpc": {"id": 0,
"name": "string",
"ip_range": "string",
"route_entries": [{"router": "string",
"destination": "string",
"description": "string"
}
]
}
}

Update an Existing VPC

Anything not included in this will be un-altered.

Authorizations:

apiToken

path Parameters

vpc_id

required

integer <int64>

The target vpc id.

Request Body schema: application/json

name	string or null [ 1 .. 250 ] characters A name to help identify this VPC. Submit null to leave unaltered.
	Array of objects or null (RouteEntryRequest) Submit null to leave unaltered, submit an empty list to clear all route entries. It is not possible to PATCH individual route entries, to alter a route entry submit the entire list of route entries you wish to save.

Responses

Response Schema: application/json

required

object

id required	integer <int64> The ID of this VPC.
name required	string non-empty The name of this VPC.
ip_range required	string non-empty The IPv4 range for this VPC in CIDR format.
required	Array of objects (RouteEntry) The route entries that control how network traffic is directed through the VPC environment.

Request samples

Payload
Curl

Content type

application/json

{"name": "string",
"route_entries": [{"router": "string",
"destination": "string",
"description": "string"
}
]
}

Response samples

200
400
404

Content type

application/json

{"vpc": {"id": 0,
"name": "string",
"ip_range": "string",
"route_entries": [{"router": "string",
"destination": "string",
"description": "string"
}
]
}
}

Delete an Existing VPC

Authorizations:

apiToken

path Parameters

vpc_id

required

integer <int64>

The target vpc id.

Responses

Request samples

Curl

curl -X DELETE "https://api.mammoth.com.au/v2/vpcs/${vpc_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

403
404

Content type

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}

List All Existing VPCs

Authorizations:

apiToken

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Vpc)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/vpcs?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"vpcs": [{"id": 0,
"name": "string",
"ip_range": "string",
"route_entries": [{"router": "string",
"destination": "string",
"description": "string"
}
]
}
]
}

Create a New VPC

Authorizations:

apiToken

Request Body schema: application/json

name required	string [ 0 .. 250 ] characters A name to help identify this VPC.
	Array of objects or null (RouteEntryRequest) The route entries that control how network traffic is directed through the VPC environment.
ip_range	string or null A private address range that you select during creation, such as the default value of 10.240.0.0/16. Because the virtual network is dedicated to your use, you may use whatever IP address range you like.

Responses

Response Schema: application/json

required

object

id required	integer <int64> The ID of this VPC.
name required	string non-empty The name of this VPC.
ip_range required	string non-empty The IPv4 range for this VPC in CIDR format.
required	Array of objects (RouteEntry) The route entries that control how network traffic is directed through the VPC environment.

Request samples

Payload
Curl

Content type

application/json

{"name": "string",
"route_entries": [{"router": "string",
"destination": "string",
"description": "string"
}
],
"ip_range": "string"
}

Response samples

200
400

Content type

application/json

{"vpc": {"id": 0,
"name": "string",
"ip_range": "string",
"route_entries": [{"router": "string",
"destination": "string",
"description": "string"
}
]
}
}

List All Members of an Existing VPC

Only resource type 'server' is currently supported.

Authorizations:

apiToken

path Parameters

vpc_id

required

integer <int64>

The target vpc id.

query Parameters

resource_type

string

Enum: "server" "load-balancer" "ssh-key" "vpc" "image" "registered-domain-name"

Value	Description
server	Server
load-balancer	Load Balancer
ssh-key	SSH Key
vpc	Virtual Private Network
image	Backup or Operating System Image
registered-domain-name	Registered Domain Name

page

integer <int32> [ 1 .. 2147483647 ]

Default: 1

The selected page. Page numbering starts at 1

per_page

integer <int32> [ 1 .. 200 ]

Default: 20

The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (VpcMember)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/vpcs/${vpc_id}/members?resource_type=${resource_type}&page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"members": [{"name": "string",
"resource_type": "server",
"resource_id": "string",
"created_at": "2019-08-24T14:15:22Z"
}
]
}

Nameserver Notes

Any domain records that are created or managed here will only have an effect if the nameservers for the domain are set to our local nameservers.

Manage DNS

List All Public Nameservers

Authorizations:

apiToken

Responses

Response Schema: application/json

local_nameservers

required

Array of strings

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/domains/nameservers"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200

Content type

application/json

{"local_nameservers": ["string"
]
}

Refresh Cached Nameserver Domain Records

The nameservers for domains are cached. If you have recently altered the nameservers for a managed domain you may need to refresh the cached domain records.

Authorizations:

apiToken

Responses

Request samples

Curl

curl -X POST "https://api.mammoth.com.au/v2/domains/refresh_nameserver_cache"  \
-H "Authorization: Bearer ${APITOKEN}"  \
-H "Content-Type: application/json" -d "${PAYLOAD}"

List All Domains

Authorizations:

apiToken

query Parameters

page	integer <int32> [ 1 .. 2147483647 ] Default: 1 The selected page. Page numbering starts at 1
per_page	integer <int32> [ 1 .. 200 ] Default: 20 The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (Domain)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/domains?page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
400
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"domains": [{"name": "string",
"current_nameservers": ["string"
],
"ttl": 0,
"zone_file": "string"
}
]
}

Create a New Domain

Authorizations:

apiToken

Request Body schema: application/json

name required	string non-empty The domain name to add to the DNS management system.
ip_address	string or null An optional IPv4 address that will be used to create an A record for the root domain.

Responses

Response Schema: application/json

required

object

name required	string non-empty The name of the domain.
current_nameservers required	Array of strings The current authoritative name servers for this domain.
ttl	integer or null <int32> The time to live for records in this domain in seconds. If the DNS records for this domain are not managed locally this will be what the TTL would be if the authority was delegated to us.
zone_file required	string non-empty The zone file for the selected domain. If the DNS records for this domain are not managed locally this is what the zone file would be if the authority was delegated to us.

Request samples

Payload
Curl

Content type

application/json

{"name": "string",
"ip_address": "string"
}

Response samples

200
400

Content type

application/json

{"domain": {"name": "string",
"current_nameservers": ["string"
],
"ttl": 0,
"zone_file": "string"
}
}

Fetch an Existing Domain

Authorizations:

apiToken

path Parameters

domain_name

required

string

The name of the domain to fetch.

Responses

Response Schema: application/json

required

object

name required	string non-empty The name of the domain.
current_nameservers required	Array of strings The current authoritative name servers for this domain.
ttl	integer or null <int32> The time to live for records in this domain in seconds. If the DNS records for this domain are not managed locally this will be what the TTL would be if the authority was delegated to us.
zone_file required	string non-empty The zone file for the selected domain. If the DNS records for this domain are not managed locally this is what the zone file would be if the authority was delegated to us.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/domains/${domain_name}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"domain": {"name": "string",
"current_nameservers": ["string"
],
"ttl": 0,
"zone_file": "string"
}
}

Delete an Existing Domain

Authorizations:

apiToken

path Parameters

domain_name

required

string

The name of the domain to delete.

Responses

Request samples

Curl

curl -X DELETE "https://api.mammoth.com.au/v2/domains/${domain_name}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

404

Content type

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}

List All Domain Records for a Domain

Authorizations:

apiToken

path Parameters

domain_name

required

string

The domain name for which records should be listed.

query Parameters

type

string

Enum: "A" "AAAA" "CAA" "CNAME" "MX" "NS" "SOA" "SRV" "TXT"

Value	Description
A	Map an IPv4 address to a hostname.
AAAA	Map an IPv6 address to a hostname.
CAA	Restrict which certificate authorities are permitted to issue certificates for a domain.
CNAME	Define an alias for your canonical hostname.
MX	Define the mail exchanges that handle mail for the domain.
NS	Define the nameservers that manage the domain.
SOA	The Start of Authority record for the zone.
SRV	Specify a server by hostname and port to handle a service or services.
TXT	Define a string of text that is associated with a hostname.

name

string

Only return records for this subdomain name.

page

integer <int32> [ 1 .. 2147483647 ]

Default: 1

The selected page. Page numbering starts at 1

per_page

integer <int32> [ 1 .. 200 ]

Default: 20

The number of results to show per page.

Responses

Response Schema: application/json

required	object Contains metadata about the response, currently this includes the total number of items.
	object or null
required	Array of objects (DomainRecord)

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/domains/${domain_name}/records?type=${type}&name=${name}&page=${page}&per_page=${per_page}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"meta": {"total": 0
},
"links": {"pages": {"last": "string",
"next": "string",
"prev": "string",
"first": "string"
}
},
"domain_records": [{"id": 0,
"type": "A",
"name": "string",
"data": "string",
"priority": 0,
"port": 0,
"ttl": 0,
"weight": 0,
"flags": 0,
"tag": "string"
}
]
}

Create a New Domain Record

Authorizations:

apiToken

path Parameters

domain_name

required

string

The domain name for which the record should be created.

Request Body schema: application/json

type	string or null Enum: "A" "AAAA" "CAA" "CNAME" "MX" "NS" "SOA" "SRV" "TXT" The type of the DNS record.
name	string or null The subdomain for this record. Use @ for records on the domain itself, and * to create a wildcard record.
data	string or null A general data field that has different functions depending on the record type.
priority	integer or null <int32> [ 0 .. 65535 ] A priority value that is only relevant for SRV and MX records.
port	integer or null <int32> [ 0 .. 65535 ] A port value that is only relevant for SRV records.
ttl	integer or null <int32> This value is the time to live for the record, in seconds.
weight	integer or null <int32> [ 0 .. 65535 ] The weight value that is only relevant for SRV records.
flags	integer or null <int32> [ 0 .. 255 ] An unsigned integer between 0-255 that is only relevant for CAA records.
tag	string or null [ 1 .. 15 ] characters [a-z0-9]+ A parameter tag that is only relevant for CAA records.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this domain record.

type

required

string

Enum: "A" "AAAA" "CAA" "CNAME" "MX" "NS" "SOA" "SRV" "TXT"

A general data field that has different functions depending on the record type.

Value	Description
A	Map an IPv4 address to a hostname.
AAAA	Map an IPv6 address to a hostname.
CAA	Restrict which certificate authorities are permitted to issue certificates for a domain.
CNAME	Define an alias for your canonical hostname.
MX	Define the mail exchanges that handle mail for the domain.
NS	Define the nameservers that manage the domain.
SOA	The Start of Authority record for the zone.
SRV	Specify a server by hostname and port to handle a service or services.
TXT	Define a string of text that is associated with a hostname.

name

required

string non-empty

The subdomain, alias, or service defined by the record.

data

string or null

Variable data depending on record type.

priority

integer or null <int32>

A priority value that is only relevant for SRV and MX records.

port

integer or null <int32>

A port value that is only relevant for SRV records.

ttl

required

integer <int32>

This value is the time to live for the record in seconds.

weight

integer or null <int32>

The weight value that is only relevant for SRV records.

flags

integer or null <int32>

An unsigned integer between 0-255 that is only relevant for CAA records.

tag

string or null

A parameter tag that is only relevant for CAA records.

Request samples

Payload
Curl

Content type

application/json

{"type": "A",
"name": "string",
"data": "string",
"priority": 65535,
"port": 65535,
"ttl": 0,
"weight": 65535,
"flags": 255,
"tag": "string"
}

Response samples

200
400
404

Content type

application/json

{"domain_record": {"id": 0,
"type": "A",
"name": "string",
"data": "string",
"priority": 0,
"port": 0,
"ttl": 0,
"weight": 0,
"flags": 0,
"tag": "string"
}
}

Fetch an Existing Domain Record

Authorizations:

apiToken

path Parameters

domain_name required	string The domain name for which the record should be fetched.
record_id required	integer <int64> The ID of the record to fetch.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this domain record.

type

required

string

Enum: "A" "AAAA" "CAA" "CNAME" "MX" "NS" "SOA" "SRV" "TXT"

A general data field that has different functions depending on the record type.

Value	Description
A	Map an IPv4 address to a hostname.
AAAA	Map an IPv6 address to a hostname.
CAA	Restrict which certificate authorities are permitted to issue certificates for a domain.
CNAME	Define an alias for your canonical hostname.
MX	Define the mail exchanges that handle mail for the domain.
NS	Define the nameservers that manage the domain.
SOA	The Start of Authority record for the zone.
SRV	Specify a server by hostname and port to handle a service or services.
TXT	Define a string of text that is associated with a hostname.

name

required

string non-empty

The subdomain, alias, or service defined by the record.

data

string or null

Variable data depending on record type.

priority

integer or null <int32>

A priority value that is only relevant for SRV and MX records.

port

integer or null <int32>

A port value that is only relevant for SRV records.

ttl

required

integer <int32>

This value is the time to live for the record in seconds.

weight

integer or null <int32>

The weight value that is only relevant for SRV records.

flags

integer or null <int32>

An unsigned integer between 0-255 that is only relevant for CAA records.

tag

string or null

A parameter tag that is only relevant for CAA records.

Request samples

Curl

curl -X GET "https://api.mammoth.com.au/v2/domains/${domain_name}/records/${record_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

200
404

Content type

application/json

{"domain_record": {"id": 0,
"type": "A",
"name": "string",
"data": "string",
"priority": 0,
"port": 0,
"ttl": 0,
"weight": 0,
"flags": 0,
"tag": "string"
}
}

Update an Existing Domain Record

Authorizations:

apiToken

path Parameters

domain_name required	string The domain name for which the record should be updated.
record_id required	integer <int64> The ID of the record to update.

Request Body schema: application/json

type	string or null Enum: "A" "AAAA" "CAA" "CNAME" "MX" "NS" "SOA" "SRV" "TXT" The type of the DNS record.
name	string or null The subdomain for this record. Use @ for records on the domain itself, and * to create a wildcard record.
data	string or null A general data field that has different functions depending on the record type.
priority	integer or null <int32> [ 0 .. 65535 ] A priority value that is only relevant for SRV and MX records.
port	integer or null <int32> [ 0 .. 65535 ] A port value that is only relevant for SRV records.
ttl	integer or null <int32> This value is the time to live for the record, in seconds.
weight	integer or null <int32> [ 0 .. 65535 ] The weight value that is only relevant for SRV records.
flags	integer or null <int32> [ 0 .. 255 ] An unsigned integer between 0-255 that is only relevant for CAA records.
tag	string or null [ 1 .. 15 ] characters [a-z0-9]+ A parameter tag that is only relevant for CAA records.

Responses

Response Schema: application/json

required

object

id

required

integer <int64>

The ID of this domain record.

type

required

string

Enum: "A" "AAAA" "CAA" "CNAME" "MX" "NS" "SOA" "SRV" "TXT"

A general data field that has different functions depending on the record type.

Value	Description
A	Map an IPv4 address to a hostname.
AAAA	Map an IPv6 address to a hostname.
CAA	Restrict which certificate authorities are permitted to issue certificates for a domain.
CNAME	Define an alias for your canonical hostname.
MX	Define the mail exchanges that handle mail for the domain.
NS	Define the nameservers that manage the domain.
SOA	The Start of Authority record for the zone.
SRV	Specify a server by hostname and port to handle a service or services.
TXT	Define a string of text that is associated with a hostname.

name

required

string non-empty

The subdomain, alias, or service defined by the record.

data

string or null

Variable data depending on record type.

priority

integer or null <int32>

A priority value that is only relevant for SRV and MX records.

port

integer or null <int32>

A port value that is only relevant for SRV records.

ttl

required

integer <int32>

This value is the time to live for the record in seconds.

weight

integer or null <int32>

The weight value that is only relevant for SRV records.

flags

integer or null <int32>

An unsigned integer between 0-255 that is only relevant for CAA records.

tag

string or null

A parameter tag that is only relevant for CAA records.

Request samples

Payload
Curl

Content type

application/json

{"type": "A",
"name": "string",
"data": "string",
"priority": 65535,
"port": 65535,
"ttl": 0,
"weight": 65535,
"flags": 255,
"tag": "string"
}

Response samples

200
400
404

Content type

application/json

{"domain_record": {"id": 0,
"type": "A",
"name": "string",
"data": "string",
"priority": 0,
"port": 0,
"ttl": 0,
"weight": 0,
"flags": 0,
"tag": "string"
}
}

Delete an Existing Domain Record

Authorizations:

apiToken

path Parameters

domain_name required	string The domain name for which the record should be deleted.
record_id required	integer <int64> The ID of the record to delete.

Responses

Request samples

Curl

curl -X DELETE "https://api.mammoth.com.au/v2/domains/${domain_name}/records/${record_id}"  \
-H "Authorization: Bearer ${APITOKEN}"

Response samples

404

Content type

application/json

{"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}