Maxihost Developer Hub

Welcome to Maxihost's Developer Hub. Here you'll find comprehensive guides and documentation to help you start working with Maxihost as quickly as possible, as well as support if yo u get stuck. Let's jump right in!

Guides
 

Welcome to our API documentation! You can view code examples in the area to the right.

For more information about Maxihost products, you can visit our product documentation.

Suggest Edits

API Summary

 

JSON is returned in all responses.

The API also uses common approaches for the following:

Function
Description

Data

API data is JSON encoded with UTF-8. API JSON is either a single object or a list of objects.

Authorization

Access control using API Access Tokens.

Errors

4xx and 5xx responses returning JSON with error codes

HTTP

Methods are used in accordance with HTTP (GET POST and DELETE are the primary methods used) and resources are identified using URIs. All API requests are sent over HTTPS.

Suggest Edits

Access Tokens

 

You'll need an Access Token if you want to use the API to access your own Maxihost data – for example, if you use the API with your own scripts to get data from your Maxihost account.

Setting up Access Tokens

Access Tokens should never be shared outside of your company

Access Tokens allow access to your private customer data in Maxihost. They should not be shared outside of your company. We cannot stress enough how important it is for you not to share your Token with anyone.

Creating your Access Token is simple and you can get a Token instantly.

To create your Access Token, go to the API page on the dashboard by clicking here or by clicking on API on the main menu.

Using your Access Token

Once you have created your Access Token you will see it in the same section of your Dashboard. You can edit or delete the token from here.

You can copy your token and use it in much the same way as you would use an API Key. The specifics will depend on how you are integrating with Maxihost.

To use your Access Token simply provide it as part of the authorization header when you make a request. Access Tokens use the bearer authorization header when you make a request. This just means you need to specify the bearer type in the header.

For more info on the bearer token framework please see the official spec.

$ curl \
-s https://api.maxihost.com/users/494817923 \
-H "Authorization: Bearer <access_token>" \
-H 'Accept:application/json'
 
Suggest Edits

Create Device

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.maxihost.com/devices
curl --request POST \
  --url https://api.maxihost.com/devices
var request = require("request");

var options = { method: 'POST', url: 'https://api.maxihost.com/devices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/devices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.maxihost.com/devices");

xhr.send(data);
import requests

url = "https://api.maxihost.com/devices"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "created_at": 1537286770,
  "order_id": 1338,
  "order_status": 49,
  "client_id": 33,
  "company": "Acme Co.",
  "summary": {
    "total": 600,
    "total_setup": 0,
    "prorated_total": 600
  },
  "info": [
    {
      "hostname": "hostname",
      "plan_id": "45",
      "quantity": 1,
      "period": 1,
      "service_description": "Servidor Outlet",
      "cost": 600,
      "total_setup": 0,
      "prorated_total": 600
    }
  ]
}
{
  "status": false,
  "error_messages": [
    "Plan is out of stock"
  ]
}

Body Params

facility
string
required

The datacenter name. Currently, only 'mh1' is available

plan
string
required

Plan's slug. You get this from the /plans endpoint.

hostname
string
required

Device hostname. Only alphanumberic, dashes and dots are allowed.

operating_system
string
required

Operating System to deploy. You get this from the /plans/operating-system endpoint.

billing_cycle
string
required

Periodicity the server should be charged. Currently, only 'monthly' is allowed.

backorder
boolean

Create device even if out of stock. Optional. Default: false

ssh_keys
array of strings

A list of SSH Key fingerprints or IDs for deployment. Optional

Response

Device created

idinteger
descriptionstring
typestring
type_idinteger
labelstring
service_idinteger
power_statusinteger
specsobject
specs.cpustring
specs.diskstring
specs.ramstring
locationobject
location.facility_namestring
location.facility_codestring
location.facility_countrystring
location.row_namestring
location.rack_namestring
location.rack_positionstring
ipsarray

Device create failure

statusboolean
error_messagesarray

This creates a new device in the selected facility. All of the attributes must be set, with exception of backorder, to successfully create a server.

By default, the request will fail if there are no available servers matching your criteria unless you set the backorder parameter to true. In that case, the device will be added to a backorder queue where it'll be provisioned as soon as we have a server that matches your requirements. The team is also notified when a device enters the backorder queue so it can prioritize restocking of that server.

Suggest Edits

List Devices

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/devices
curl --request GET \
  --url https://api.maxihost.com/devices
var request = require("request");

var options = { method: 'GET', url: 'https://api.maxihost.com/devices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/devices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/devices");

xhr.send(data);
import requests

url = "https://api.maxihost.com/devices"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "devices": [
    {
      "id": 6098,
      "description": "1F1D5M1",
      "type": "Bare Metal",
      "type_id": 1,
      "label": "BRC1234KD0",
      "service_id": 0,
      "power_status": 1,
      "specs": {
        "cpu": "Dual Intel Xeon Silver 4116",
        "disk": "2 x 1000GB NVMe",
        "ram": "256GB"
      },
      "location": {
        "facility_name": "Maxihost SP1",
        "facility_code": "MH1",
        "row_name": "C",
        "rack_name": "01",
        "rack_position": "33"
      },
      "ips": [
        {
          "id": 6098,
          "ip_address": "1.1.1.1",
          "ip_description": "Public IPv4",
          "device_id": 613,
          "device_description": "BRC55378N7",
          "device_label": "BRC55378N7",
          "service_id": 0,
          "created_at": 1526918369,
          "updated_at": 1537818767
        }
      ]
    }
  ],
  "links": {
    "first": "https://api.maxihost.com/devices?limit=1&page=1",
    "last": "https://api.maxihost.com/devices?limit=1&page=10",
    "next": "https://api.maxihost.com/devices?limit=1&page=3",
    "prev": "https://api.maxihost.com/devices?limit=1&page=1",
    "self": "https://api.maxihost.com/devices?limit=1&page=2"
  },
  "meta": {
    "pages": {
      "count": 1,
      "total": 10
    }
  }
}

Query Params

page
string

The page number.

limit
string

The page size.

Response

Devices found

devicesarray
linksobject
links.firststring
links.laststring
links.nextstring
links.prevstring
links.selfstring
metaobject
meta.pagesobject
meta.pages.totalinteger
meta.pages.countinteger
Suggest Edits

Show Device

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/devices/id
curl --request GET \
  --url https://api.maxihost.com/devices/id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.maxihost.com/devices/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/devices/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/devices/id");

xhr.send(data);
import requests

url = "https://api.maxihost.com/devices/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": 613,
  "description": "2PY11Y1",
  "type": "Bare Metal",
  "type_id": 1,
  "label": "2PY11Y1",
  "service_id": 0,
  "power_status": 1,
  "specs": {
    "cpu": "Intel Xeon E3-1240v2",
    "disk": "500GB SATA",
    "ram": "32GB"
  },
  "location": {
    "facility_name": "Maxihost SP1",
    "facility_code": "MH1",
    "facility_country": "BR",
    "row_name": "C",
    "rack_name": "05",
    "rack_position": "33"
  },
  "ips": [
    {
      "id": 5260,
      "ip_address": "177.54.158.95",
      "ip_description": "Public IPv4",
      "device_id": 613,
      "device_description": "BRC55378N7",
      "device_label": "BRC55378N7",
      "service_id": 0,
      "created_at": 1526928304,
      "updated_at": 1537818788
    }
  ]
}
{
  "status": false,
  "code": "DEVICE_NOT_FOUND",
  "error_messages": {
    "base": [
      "Device not found."
    ]
  }
}
{
  "status": false,
  "code": "DEVICE_NOT_FOUND",
  "error_messages": {
    "base": [
      "request failed: Device not found"
    ]
  }
}

Path Params

id
string
required

Response

Device found

devicesarray

Device not found

statusboolean
codestring
error_messagesobject
error_messages.basearray

Device not found

statusboolean
codestring
error_messagesobject
error_messages.basearray
Suggest Edits

Show Device Bandwidth

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/devices/device_id/bandwidth
curl --request GET \
  --url https://api.maxihost.com/devices/device_id/bandwidth
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.maxihost.com/devices/device_id/bandwidth' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/devices/device_id/bandwidth")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/devices/device_id/bandwidth");

xhr.send(data);
import requests

url = "https://api.maxihost.com/devices/device_id/bandwidth"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "data": {
    "bandwidth": "\\x00\\xFF\\x88\\xFF\\x00\\xFF"
  }
}
{
  "code": "NOT_FOUND",
  "error_messages": {
    "base": [
      "Invalid device specified"
    ]
  },
  "status": false
}

Path Params

device_id
string
required

Query Params

period
string

Period to fetch the bandwidth graph. Available: custom, week,month,yesterday,current,previous

start_time
string

Only used if period is custom. Timestamp of initial graph date.

end_time
string

Only used if period is custom. Timestamp of end graph date.

Response

Custom device bandwidth graph

bandwidthstring

Device not found

statusboolean
codestring
error_messagesobject
error_messages.basearray
Suggest Edits

List Device IPs

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/devices/device_id/ips
curl --request GET \
  --url https://api.maxihost.com/devices/device_id/ips
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.maxihost.com/devices/device_id/ips' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/devices/device_id/ips")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/devices/device_id/ips");

xhr.send(data);
import requests

url = "https://api.maxihost.com/devices/device_id/ips"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "ips": [
    {
      "id": 6098,
      "ip_address": "10.54.158.95",
      "ip_description": "Private IPMI",
      "device_id": 613,
      "device_description": "BRC55378N7",
      "device_label": "BRC55378N7",
      "service_id": 0,
      "created_at": 1526918369,
      "updated_at": 1537818767
    },
    {
      "id": 6102,
      "ip_address": "177.54.158.95",
      "ip_description": "Public IPv4",
      "device_id": 613,
      "device_description": "BRC55378N7",
      "device_label": "BRC55378N7",
      "service_id": 0,
      "created_at": 1526928304,
      "updated_at": 1537818788
    }
  ],
  "links": {
    "self": "https://api.maxihost.com/devices/613/ips?limit=2&page=1",
    "next": "https://api.maxihost.com/devices/613/ips?limit=2&page=2",
    "last": "https://api.maxihost.com/devices/613/ips?limit=2&page=5"
  },
  "meta": {
    "pages": {
      "count": 2,
      "total": 5
    }
  }
}

Path Params

device_id
string
required

Query Params

page
string

The page number.

limit
string

The page size.

Response

Device found

ipsarray
linksobject
links.firststring
links.laststring
links.nextstring
links.prevstring
links.selfstring
metaobject
meta.pagesobject
meta.pages.totalinteger
meta.pages.countinteger
 
Suggest Edits

Create SSH Key

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.maxihost.com/account/keys
curl --request POST \
  --url https://api.maxihost.com/account/keys
var request = require("request");

var options = { method: 'POST', url: 'https://api.maxihost.com/account/keys' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/account/keys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.maxihost.com/account/keys");

xhr.send(data);
import requests

url = "https://api.maxihost.com/account/keys"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": 3,
  "fingerprint": "f7:4a:b7:63:b3:4d:d5:0d:50:d8:79:53:68:87:d3:c7",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCgJe9hY84cYnqxBZvkNve65CPOw6l0hrV6+CmAoURHlpUYCtD4HvR67428v9iCS4kyqftJlk9f+AyG0OKexDHSHp4GiHEjEwMXqQugfbEWf0whxwCdUDd96lf1JUB0giV2+viTxhSJ0hMWX19hQs15zkSc8jZ6sV+Rs9X5awOvPs2U98eq29wlIahW6iM7dlW/UH2pbGryLOu+ESY4hrCFiPwWS1RrP+BDwipYAC1dFKG8N5b7yqQoN8OvfuvHlIGNZAkWPw5lRxUR5+YN1XSMezbcDU/Fq0vIAxxEv2RVfCrzV4FO36mC71vl+vh1jh9J8Fo4jZPf6EGM9qB1dU3d",
  "name": "My SSH key 3"
}
{
  "status": false,
  "error_messages": {
    "base": [
      "public_key Invalid SSH Public Key"
    ]
  }
}

Body Params

name
string
required

A name to identify the key.

public_key
string
required

The base64 encoded sequence of the public key to be added.

Response

SSH Key created

idinteger
fingerprintstring
public_keystring
namestring

Invalid SSH Public Key

statusboolean
codestring
error_messagesobject
error_messages.basearray
Suggest Edits

List SSH Keys

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/account/keys
curl --request GET \
  --url https://api.maxihost.com/account/keys
var request = require("request");

var options = { method: 'GET', url: 'https://api.maxihost.com/account/keys' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/account/keys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/account/keys");

xhr.send(data);
import requests

url = "https://api.maxihost.com/account/keys"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "ssh_keys": [
    {
      "id": 1,
      "fingerprint": "00:6a:e2:6a:c5:ab:c4:9c:bc:f6:63:4e:04:ea:fc:8f",
      "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDoKPBoeHGlAbAvD8AuLVoHZiyo+WbzsOmM/aFI28a7zPmBzIsuoWCd9tYGZk3IjzruqYBCfsEWHF6LcBOTAahRWwPb2PF2lcoYLN+3M69OmcIWdUpinHdqDoT8ot27JJdVGdqG80FAcr6lJRifTm4JtHDdVzM0UGWlzNmMXensajSyE4V/Eh5QIRlW6l809w25WJwtDrY7pT+9ItXB9gZAsxR4o36FDLIQVZrKPRtRFmxtiAOIQBWGza4i+UqIW7ljoYMkfDEq0jTBhmJxN7cuZ9riHZtvPibLR8QViYVkTLMsrth78SNePeNkPnWW3Yl+0KSQD1M2wtCnvWJ7+6TH",
      "name": "My SSH key 1"
    }
  ],
  "links": {
    "self": "https://api.maxihost.com/account/keys?limit=1&page=1"
  },
  "meta": {
    "pages": {
      "total": 1,
      "count": 1
    }
  }
}

Query Params

page
string

The page number.

limit
string

The page size.

Response

List SSH Keys

ssh_keysarray
linksobject
links.firststring
links.laststring
links.nextstring
links.prevstring
links.selfstring
metaobject
meta.pagesobject
meta.pages.totalinteger
meta.pages.countinteger
Suggest Edits

Show SSH Key

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/account/keys/id
curl --request GET \
  --url https://api.maxihost.com/account/keys/id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.maxihost.com/account/keys/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/account/keys/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/account/keys/id");

xhr.send(data);
import requests

url = "https://api.maxihost.com/account/keys/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": 1,
  "fingerprint": "00:6a:e2:6a:c5:ab:c4:9c:bc:f6:63:4e:04:ea:fc:8f",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDoKPBoeHGlAbAvD8AuLVoHZiyo+WbzsOmM/aFI28a7zPmBzIsuoWCd9tYGZk3IjzruqYBCfsEWHF6LcBOTAahRWwPb2PF2lcoYLN+3M69OmcIWdUpinHdqDoT8ot27JJdVGdqG80FAcr6lJRifTm4JtHDdVzM0UGWlzNmMXensajSyE4V/Eh5QIRlW6l809w25WJwtDrY7pT+9ItXB9gZAsxR4o36FDLIQVZrKPRtRFmxtiAOIQBWGza4i+UqIW7ljoYMkfDEq0jTBhmJxN7cuZ9riHZtvPibLR8QViYVkTLMsrth78SNePeNkPnWW3Yl+0KSQD1M2wtCnvWJ7+6TH",
  "name": "My SSH key 1"
}
{
  "status": false,
  "code": "SSH_KEY_NOT_FOUND",
  "error_messages": {
    "base": [
      "The provided id or fingerprint were not found."
    ]
  }
}

Path Params

id
string
required

SSH Key ID or fingerprint

Response

SSH Key

idinteger
fingerprintstring
public_keystring
namestring

Invalid id or fingerprint

statusboolean
codestring
error_messagesobject
error_messages.idarray
Suggest Edits

Update SSH Key

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.maxihost.com/account/keys/id
curl --request PUT \
  --url https://api.maxihost.com/account/keys/id
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.maxihost.com/account/keys/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/account/keys/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.maxihost.com/account/keys/id");

xhr.send(data);
import requests

url = "https://api.maxihost.com/account/keys/id"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": 1,
  "fingerprint": "00:6a:e2:6a:c5:ab:c4:9c:bc:f6:63:4e:04:ea:fc:8f",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDoKPBoeHGlAbAvD8AuLVoHZiyo+WbzsOmM/aFI28a7zPmBzIsuoWCd9tYGZk3IjzruqYBCfsEWHF6LcBOTAahRWwPb2PF2lcoYLN+3M69OmcIWdUpinHdqDoT8ot27JJdVGdqG80FAcr6lJRifTm4JtHDdVzM0UGWlzNmMXensajSyE4V/Eh5QIRlW6l809w25WJwtDrY7pT+9ItXB9gZAsxR4o36FDLIQVZrKPRtRFmxtiAOIQBWGza4i+UqIW7ljoYMkfDEq0jTBhmJxN7cuZ9riHZtvPibLR8QViYVkTLMsrth78SNePeNkPnWW3Yl+0KSQD1M2wtCnvWJ7+6TH",
  "name": "New SSH Key"
}
{
  "status": false,
  "code": "SSH_KEY_NOT_FOUND",
  "error_messages": {
    "base": [
      "The provided id or fingerprint were not found."
    ]
  }
}
{
  "status": false,
  "code": "UNPROCESSABLE_ENTITY",
  "error_messages": {
    "base": [
      "Name can't be blank"
    ]
  }
}

Path Params

id
string
required

SSH Key ID or fingerprint

Body Params

name
string

Response

SSH Key updated

idinteger
fingerprintstring
public_keystring
namestring

Invalid id or fingerprint

statusboolean
codestring
error_messagesobject
error_messages.idarray

Invalid name

statusboolean
error_messagesobject
error_messages.namearray
Suggest Edits

Remove SSH Key

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.maxihost.com/account/keys/id
curl --request DELETE \
  --url https://api.maxihost.com/account/keys/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.maxihost.com/account/keys/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/account/keys/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.maxihost.com/account/keys/id");

xhr.send(data);
import requests

url = "https://api.maxihost.com/account/keys/id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{}
{
  "status": false,
  "code": "SSH_KEY_NOT_FOUND",
  "error_messages": {
    "base": [
      "The provided id or fingerprint were not found."
    ]
  }
}

Path Params

id
string
required

SSH Key ID or fingerprint

Response

SSH Key destroyed

SSH Key not found

statusboolean
codestring
error_messagesobject
error_messages.basearray
Suggest Edits

List Available Servers

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/plans
curl --request GET \
  --url https://api.maxihost.com/plans
var request = require("request");

var options = { method: 'GET', url: 'https://api.maxihost.com/plans' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/plans")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/plans");

xhr.send(data);
import requests

url = "https://api.maxihost.com/plans"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "servers": [
    {
      "id": 1,
      "slug": "spot_1",
      "name": "Spot",
      "line": "baremetal",
      "deploy_type": "automated",
      "specs": {
        "cpus": {
          "count": 2,
          "type": "Xeon Silver 4116",
          "cores": "24",
          "clock": "2.10"
        },
        "memory": {
          "total": "256GB"
        },
        "drives": [
          {
            "count": 2,
            "size": "500GB",
            "type": "SSD,"
          },
          {
            "count": 1,
            "size": "1TB",
            "type": "NVMe"
          }
        ]
      },
      "location": {
        "id": 3,
        "name": "Maxihost SP1",
        "code": "MH1",
        "city": "Sao Paulo",
        "country": "Brazil"
      },
      "pricing": {
        "brl_month": 600,
        "usd_month": 199
      },
      "in_stock": true
    }
  ],
  "links": {
    "self": "https://api.maxihost.com/plans?limit=1&page=1"
  },
  "meta": {
    "pages": {
      "count": 1,
      "total": 1
    }
  }
}

Query Params

page
string

The page number.

limit
string

The page size.

Response

Available Plans

serversarray
linksobject
links.firststring
links.laststring
links.nextstring
links.prevstring
links.selfstring
metaobject
meta.pagesobject
meta.pages.totalinteger
meta.pages.countinteger
Suggest Edits

List Available Bare Metal Addons

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/plans/addons
curl --request GET \
  --url https://api.maxihost.com/plans/addons
var request = require("request");

var options = { method: 'GET', url: 'https://api.maxihost.com/plans/addons' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/plans/addons")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/plans/addons");

xhr.send(data);
import requests

url = "https://api.maxihost.com/plans/addons"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "additional_bandwidth": [
    {
      "id": 219,
      "name": "10 TB / 1 Gbps",
      "slug": "10_tb_1gbps",
      "description": "",
      "pricing": {
        "brl_month": 0,
        "usd_month": 0
      }
    }
  ],
  "additional_ip": [
    {
      "id": 262,
      "name": "Additional IP",
      "slug": "additional_ip",
      "description": "",
      "pricing": {
        "brl_month": 20,
        "usd_month": 6
      }
    }
  ],
  "ddos_protection": [
    {
      "id": 254,
      "name": "Standard (Up to 10 Gbps and 8Mpps)",
      "slug": "standard_(upto10gbpsand8mpps)",
      "description": "",
      "pricing": {
        "brl_month": 500,
        "usd_month": 169
      }
    }
  ],
  "hardware_firewall": [
    {
      "id": 271,
      "name": "Standard",
      "slug": "standard",
      "description": "",
      "pricing": {
        "brl_month": 99,
        "usd_month": 29
      }
    }
  ],
  "links": {
    "last": "https://api.maxihost.com/plans/addons?limit=1&page=7",
    "next": "https://api.maxihost.com/plans/addons?limit=1&page=2",
    "self": "https://api.maxihost.com/plans/addons?limit=1&page=1"
  },
  "meta": {
    "pages": {
      "count": 4,
      "total": 7
    }
  }
}

Query Params

page
string

The page number.

limit
string

The page size.

Response

Success

additional_bandwidtharray
additional_iparray
hardware_firewallarray
ddos_protectionarray
linksobject
links.firststring
links.laststring
links.nextstring
links.prevstring
links.selfstring
metaobject
meta.pagesobject
meta.pages.totalinteger
meta.pages.countinteger
Suggest Edits

List Operating Systems

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/plans/operating-systems
curl --request GET \
  --url https://api.maxihost.com/plans/operating-systems
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.maxihost.com/plans/operating-systems' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/plans/operating-systems")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/plans/operating-systems");

xhr.send(data);
import requests

url = "https://api.maxihost.com/plans/operating-systems"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "operating-systems": [
    {
      "id": 32,
      "slug": "centos_6_x",
      "operating_system": "Linux",
      "distro": "CentOS",
      "name": "CentOS (6.x)",
      "version": "6.x",
      "pricing": {
        "brl_month": 0,
        "usd_month": 0
      }
    },
    {
      "id": 266,
      "slug": "windows_server_2016_r2__datacenter",
      "operating_system": "Windows",
      "distro": "Windows",
      "name": "Windows Server (2016 R2 - Datacenter)",
      "version": "2016 R2 - Datacenter",
      "pricing": {
        "brl_month": 50,
        "usd_month": 19
      }
    }
  ],
  "links": {
    "last": "https://api.maxihost.com/devices/operating-systems?limit=10&page=2",
    "next": "https://api.maxihost.com/devices/operating-systems?limit=10&page=2",
    "self": "https://api.maxihost.com/devices/operating-systems?limit=10&page=1"
  },
  "meta": {
    "pages": {
      "count": 2,
      "total": 2
    }
  }
}

Query Params

page
string

The page number.

limit
string

The page size.

Response

Operating Systems found

operating-systemsarray
linksobject
links.firststring
links.laststring
links.nextstring
links.prevstring
links.selfstring
metaobject
meta.pagesobject
meta.pages.totalinteger
meta.pages.countinteger
 
Suggest Edits

List Data Centers

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/regions
curl --request GET \
  --url https://api.maxihost.com/regions
var request = require("request");

var options = { method: 'GET', url: 'https://api.maxihost.com/regions' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/regions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/regions");

xhr.send(data);
import requests

url = "https://api.maxihost.com/regions"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "regions": [
    {
      "slug": "MH1",
      "name": "Maxihost SP1",
      "location": {
        "city": "Sao Paulo",
        "country": "BR"
      },
      "available": 1,
      "features": [
        "bare_metal",
        "firewall",
        "backup"
      ]
    }
  ],
  "links": {
    "self": "https://api.maxihost.com/regions?limit=1&page=1"
  },
  "meta": {
    "pages": {
      "count": 1,
      "total": 1
    }
  }
}

Query Params

page
string

The page number.

limit
string

The page size.

Response

Available Regions

regionsarray
linksobject
links.firststring
links.laststring
links.nextstring
links.prevstring
links.selfstring
metaobject
meta.pagesobject
meta.pages.totalinteger
meta.pages.countinteger
Suggest Edits

List Users

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/users
curl --request GET \
  --url https://api.maxihost.com/users
var request = require("request");

var options = { method: 'GET', url: 'https://api.maxihost.com/users' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/users");

xhr.send(data);
import requests

url = "https://api.maxihost.com/users"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "users": [
    {
      "id": 237,
      "status": 1,
      "description": "Primary Contact",
      "email": "me@maxi.host",
      "phone": "1-877-729-0562",
      "name": "MaxiHost LTDA"
    }
  ],
  "links": {
    "first": "https://api.maxihost.com/users?limit=1&page=1",
    "last": "https://api.maxihost.com/users?limit=1&page=19",
    "next": "https://api.maxihost.com/users?limit=1&page=4",
    "prev": "https://api.maxihost.com/users?limit=1&page=2",
    "self": "https://api.maxihost.com/users?limit=1&page=3"
  },
  "meta": {
    "pages": {
      "count": 1,
      "total": 19
    }
  }
}

Query Params

status
integer

An integer value to show user current status

page
string

The page number.

limit
string

The page size.

Response

Users found

usersarray
linksobject
links.firststring
links.laststring
links.nextstring
links.prevstring
links.selfstring
metaobject
meta.pagesobject
meta.pages.totalinteger
meta.pages.countinteger
Suggest Edits

Show User

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.maxihost.com/users/id
curl --request GET \
  --url https://api.maxihost.com/users/id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.maxihost.com/users/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/users/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.maxihost.com/users/id");

xhr.send(data);
import requests

url = "https://api.maxihost.com/users/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": 237,
  "status": 1,
  "description": "Primary Contact",
  "email": "me@maxi.host",
  "phone": "1-877-729-0562",
  "name": "MaxiHost LTDA"
}
{
  "status": false,
  "code": "USER_NOT_FOUND",
  "error_messages": {
    "base": [
      "User not found."
    ]
  }
}

Path Params

id
string
required

Response

User found

idinteger
statusinteger
descriptionstring
emailstring
phonestring
namestring

User not found

statusboolean
codestring
error_messagesobject
error_messages.basearray
Suggest Edits

Update User

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.maxihost.com/users/id
curl --request PUT \
  --url https://api.maxihost.com/users/id
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.maxihost.com/users/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.maxihost.com/users/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.maxihost.com/users/id");

xhr.send(data);
import requests

url = "https://api.maxihost.com/users/id"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "status": false,
  "code": "USER_UPDATE_FAILURE",
  "error_messages": {
    "base": [
      "Sorry, user with property xunda@maxi.host already exists."
    ]
  }
}

Path Params

id
string
required

Body Params

email
string

The user's email address

name
string

The user's name

status
integer

The user's account status. 0 deactivates the account while 1 activates it

phone
string

The user's phone number

Response

User updated

Unprocessable

statusboolean
codestring
error_messagesobject
error_messages.basearray
Suggest Edits

Error Objects

 

The API will return an Error List for a failed request, which will contain one or more Error objects.

Error List Attributes

Each error has the following attributes

Field
Description

status

The status is false

code

General context about the error. See Error Codes.

error_messages

An array of one or more error objects.

Error Object Attributes

Each Error Object has the following attributes

Field
Description

base

Human readable description of the error

Error List Object

{
  "status": "error.list",
  "errors": [
    {
      "code": "not_found",
      "message": "No such user_id[494817923]",
      "field": "user_id"
    },
    {
      "code": "not_found",
      "message": "No such email[john@doe.acme]",
      "field": "email"
    }
  ]
}
Suggest Edits

Error Codes

 

The API may send the following error codes. Other codes may be added in the future.

Field
Description

CLIENT_ERROR

Generic server error

TIMEOUT

Timeout error

UNAUTHORIZED_REQUEST

The request was not authorized. Check your token.

FORBIDDEN_REQUEST

The request was forbidden. Check your token.

INVALID_CREDENTIALS

The credentials are invalid. Check your data.

UNPROCESSABLE_ENTITY

Cannot process the request. Check your data.

INVALID_TOKEN

The token is invalid. Request a new token.

REVOKED_TOKEN

The token is revoked. Request a new token.

MISSING_TOKEN

The token is missing. Check your token.

EXPIRED_TOKEN

The token is expired. Request a new token.

ACCOUNT_LOGIN_FAILURE

Failure to log in. Check your credentials.

MALFORMED_PAYLOAD

Your payload is wrong. Check your data.

PRIMARY_USER_EDIT

Cannot update the primary user. Select another user to update.

<ITEM>_NOT_FOUND

<ITEM> not found. Check your data.

UPDATE_CONTACT

Failure updating a contact. Check your data.

NOT_FOUND

Generic error when the subject is not found

INVALID_UPDATE

Failure updating the subject. Check your data.

<ITEM>_LIST_FAILURE

Failure listing available <ITEM>. Try again later.

<ITEM>_UPDATE_FAILURE

Failure updating <ITEM>. Try again later.

<ITEM>_CREATE_FAILURE

Failure creating <ITEM>. Try again later.

Suggest Edits

HTTP Responses

 

The API returns HTTP responses on each request to indicate the success or otherwise of API requests. The codes listed below are often used, and the API may use others. Note that 4xx and 5xx responses may be returned for any request and clients should cater for them.

Response Code
Description

200

Ok -- The request was successful.

201

Created -- The request was successful.

400

Bad Request -- General client error, possibly malformed data.

401

Unauthorized -- The API Key was not authorised (or no API Key was found).

403

Forbidden -- The request is not allowed.

404

Not Found -- The resource was not found.

422

Unprocessable Entity -- The data was well-formed but invalid.

429

Too Many Requests -- The client has reached or exceeded a rate limit, or the server is overloaded.

500

Server errors - something went wrong with Maxihost's servers.

This response is most likely a momentary operational error (e.g. temporary unavailability), and, as a result, requests should be retried once.

Suggest Edits

Object Model

 

Commond Fields

API objects have a type field indicating their object type. Each object in the API may be given an identifier, indicated via its id field, and will typically be addressable via a URI. Many objects will also have a created field indicating the object's creation date as a UTC Unix timestamp.

Dates and Timestamps

All temporal fields in the API are encoded as Unix timestamps and are by definition always treated as UTC. The most common time fields in the API are created and updated.

Paramater
Description

created_at

The time the object was created. In most, but not all cases, this is the time the object was created according to the API server.

updated_at

The time the object was last updated according to the API server.

Optional Fields

Unpopulated optional data is returned as follows

  • Number, String, and Boolean types may be returned as having null values.
  • Arrays and Objects may be returned as empty ([] {})

In general clients should be able to handle null and empty fields.

Metadata and Custom Attributes

Some object types, such as Devices, have a metadata field that allows clients to set custom-defined data about an object.

 

Data is encoded as defined by JSON in RFC4627. The default encoding for APIs is UTF-8. Certain characters, such as Emoji may be handled as surrogate unicode pairs (see section '2.5. Strings' of RFC4627).

Some query parameters may need to be url encoded when sending - for example, the email parameter value used to query users should be encoded.

HTML Encoding

It should be noted that the following identifiers are encoded to protect from potential cross-site scripting attacks: 'name', 'user_id', 'company_id' and 'email'. As a result you may see these identifiers in their encoded format when you retrieve them via the API.
Note that the characters we encode are double quote, single quote, ampersand, less than and greater than symbols i.e " ' & < >

Let's say you have a company name like "BL&T's". 
Then when you retrieve it from the API it will look like this:
"BL&amp;T&#39;s"
Suggest Edits

Identifiers and URLs

 

All objects in the API have an id field indicating their logical identifier. Some objects may optionally also have a self field that indicates a URL or canonical address for the object.

Parameter
Description

id

A string that identifies the object within the API. The id field will not be larger than 128 characters (in SQL it corresponds to a varchar(128)).

self

A URL that addresses the object within the API. The self field will not be larger than 255 characters (in SQL it corresponds to a varchar(255)).

These fields must always be treated as opaque strings - no guarantees are made about the internal structure of the id or self fields for an object.

The id field is always defined by the API server and is guaranteed to be unique relative to the type field - this means no two user objects will have the same id field, but a user and a company may have the same value for their id fields.

Suggest Edits

Pagination

 

List resources in the API are paginated by default to allow clients to traverse data over multiple requests. In most cases we're geared towards a default pagination limit of 10 resources per page which can be overridden via ?limit=<number>&page=<page number> query parameters.

The Maxihost API provides a Link header according to RFC5988 that can be used to retrieve the next page.

Here's an example response header from requesting the third page of servers:
Link: <https://api.maxihost.com/devices?page=3>; rel="next"

If the Link header is blank, that's the last page. The Maxihost API also provides the following pagination totals

Header
Description

X-Total-Count

Total number of resources you're fetching

X-Total-Pages

The total number of pages

The API also provides links and meta/pages nodes that provide additional pagination data. Here's an example from requesting ?page=2 of devices

"links": {
        "first": "https://api.maxihost.com/devices?limit=2&page=1",
        "last": "https://api.maxihost.com/devices?limit=2&page=10",
        "next": "https://api.maxihost.com/devices?limit=2&page=3",
        "prev": "https://api.maxihost.com/devices?limit=2&page=1",
        "self": "https://api.maxihost.com/devices?limit=2&page=2"
    },
    "meta": {
        "pages": {
            "count": 2,
            "total": 10
        }
    }
name
description

first

The first page. Included when the current page is greater than 1

last

The last page

next

The next page. Included when there's a next page

prev

The previous page. Included when there's a previous page

self

The current page

meta/pages/count

The total number of resources

meta/pages/total

The total number of pages

Suggest Edits

Use of HTTP

 

Request methods are used in accordance with HTTP

  • GET is used to access resources and perform queries. The API does not allow modifications (creates, updates, deletes) to occur via GET.
  • POST is used to create or update resources. The preferred model for creation is to post JSON to a 'collections' resource - for example the collections resource for users is https://api.maxihost.com/users. PATCH is not currently used by the API.
  • DELETE is used to delete resources.

Responses use standard HTTP codes. Where there are client or server errors, a list of of one or more errors in JSON format is returned in the body - see "Errors" for more details.

The API may send cache directives where suitable, notably the ETag, Last-Modified and If-Modified-Since headers.

The Accept header must be used by a client used to indicate a preferred response for GET/HEAD requests. Requests without an Accept header of application/json may be rejected with a client error of 404 or 406. The Content-Type header should be used by clients to indicate the submitted format for POST/PUT requests.

Suggest Edits

Compatibility

 

JSON objects in the API follow a must ignore processing model, where clients are expected to ignore data fields they don't understand.

For example if the client saw the JSON as shown in the example on the right ('Unknown Field')
and did not understand the such_key field, it must pretend the field wasn't there and will process the object as if it looked liked the object shown in 'Must Ignore'.

When fetching content, fields that are optional for API objects are indicated in the documentation - clients must not assume they will always be present. When submitting content, fields that are required to be sent by client are also indicated in the documentation - if these are not sent the API may reject the request.

In general the API may reject JSON where data is not valid or incomplete with a 422 Unprocessable Entity response and an error message explaining the issue.

Unknown Field

{
  "type": "user",
  "user_id" : "456456",
  "email" : "j@example.org",
  "such_key": "so_value"
}

Must Ignore Interpretation

{
  "type": "user",
  "user_id" : "456456",
  "email" : "j@example.org"
}