Overview
The Vultr Metadata API is a service available to all Vultr cloud servers and allows any instance to query information about itself. With additional scripting, this service enables developers to create self-configuring instances. The API functions described in this document will only return information about the calling instance.
- API Endpoint: http://169.254.169.254/v1/
HTTP Response Code | Description |
---|---|
200 | Function successfully executed. |
404 | Invalid location. Check the URL that you are using. |
405 | Invalid HTTP method. Check that the method (POST|GET) matches what the documentation indicates. |
500 | Internal server error. Try again at a later time. |
503 | Service is currently unavailable. Try your request again later. |
Using the API
- Function calls are performed over standard HTTP with no authentication.
- There are two types of endpoints: indexes and values. Indexes end with a "/" and return a listing of values for the given path. Values print the value for the given path in plain text.
- Each endpoint in this document includes a cURL example. If cURL is installed on your virtual machine, you can use the example to test an endpoint.
Metadata
Index (JSON)
/v1.json
Retrieve the entire metadata tree as a JSON document.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1.json
Example Response:
{
"bgp": {
"ipv4": {
"my-address": "192.0.2.2",
"my-asn": "64496",
"peer-address": "169.254.169.254",
"peer-asn": "64515"
},
"ipv6": {
"my-address": "2001:0db8:7400:7ccf:5428:d5ff:fe28:1910",
"my-asn": "64496",
"peer-address": "2001:19f0:ffff::1",
"peer-asn": "64515"
}
},
"hostname": "vultr-guest",
"instanceid": "a747bfz6385e",
"interfaces": [{
"ipv4": {
"additional": [{
"address": "192.0.2.3",
"netmask": "255.255.255.0"
}],
"address": "192.0.2.2",
"gateway": "192.0.2.1",
"netmask": "255.255.255.0"
},
"ipv6": {
"additional": [{
"network": "2001:0db8:0:2::",
"prefix": "64"
}],
"address": "2001:0db8:0:1:5428:d5ff:fe28:1910",
"network": "2001:0db8:0:1::",
"prefix": "64"
},
"mac": "00:00:00:00:00:00",
"network-type": "public"
},
{
"ipv4": {
"additional": [],
"address": "10.99.0.10",
"gateway": "",
"netmask": "255.255.0.0"
},
"ipv6": {
"additional": [],
"network": "",
"prefix": ""
},
"mac": "00:00:00:00:00:01",
"network-type": "private",
"networkid": "net59a077ae437d8"
}],
"public-keys": "ssh-rsa dGhpcyBpcyBhIHNhbXBsZSBzc2gga2V5IHRoaXMgaXMgYSBzYW1wbGUgc3NoIGtleSB0aGlzIGlzIGEgc2FtcGxlIHNzaCBrZXk= root@example1\nssh-rsa dGhpcyBpcyBhIHNhbXBsZSBzc2gga2V5IHRoaXMgaXMgYSBzYW1wbGUgc3NoIGtleSB0aGlzIGlzIGEgc2FtcGxlIHNzaCBrZXk= root@example2",
"region": {
"regioncode": "EWR"
}
}
Index
/v1/
Retrieve the metadata index.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/
Example Response:
hostname
instanceid
public-keys
Hostname
/v1/hostname
Retrieve the default hostname of the calling VM.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/hostname
Example Response:
vultr-guest
Instance ID
/v1/instanceid
Retrieve the instance ID of the calling VM. This was formerly known as "SUBID".
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/instanceid
Example Response:
a747bfz6385e
Public Keys
/v1/public-keys
Retrieve the default public SSH keys installed on the calling VM.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/public-keys
Example Response:
ssh-rsa dGhpcyBpcyBhIHNhbXBsZSBzc2gga2V5IHRoaXMgaXMgYSBzYW1wbGUgc3NoIGtleSB0aGlzIGlzIGEgc2FtcGxlIHNzaCBrZXk= root@example1
ssh-rsa dGhpcyBpcyBhIHNhbXBsZSBzc2gga2V5IHRoaXMgaXMgYSBzYW1wbGUgc3NoIGtleSB0aGlzIGlzIGEgc2FtcGxlIHNzaCBrZXk= root@example2
BGP
Index
/v1/bgp/
Retrieve the BGP index.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/bgp/
Example Response:
ipv4/
ipv6/
IPv4 Index
/v1/bgp/ipv4/
Retrieve the BGP IPv4 index.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/bgp/ipv4/
Example Response:
peer-address
peer-asn
my-address
my-asn
Peer Address
/v1/bgp/ipv4/peer-address
Retrieve the BGP IPv4 address of the peer (Vultr).
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/bgp/ipv4/peer-address
Example Response:
169.254.169.254
Peer ASN
/v1/bgp/ipv4/peer-asn
Retrieve the BGP ASN of the peer (Vultr).
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/bgp/ipv4/peer-asn
Example Response:
64515
My Address
/v1/bgp/ipv4/my-address
Retrieve the BGP IPv4 address of the calling VM.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/bgp/ipv4/my-address
Example Response:
192.0.2.2
My ASN
/v1/bgp/ipv4/my-asn
Retrieve the BGP ASN of the calling VM.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/bgp/ipv4/my-asn
Example Response:
64496
IPv6 Index
/v1/bgp/ipv6/
Retrieve the BGP IPv6 index.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/bgp/ipv6/
Example Response:
peer-address
peer-asn
my-address
my-asn
Peer Address
/v1/bgp/ipv6/peer-address
Retrieve the BGP IPv6 address of the peer (Vultr).
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/bgp/ipv6/peer-address
Example Response:
2001:19f0:ffff::1
Peer ASN
/v1/bgp/ipv6/peer-asn
Retrieve the BGP ASN of the peer (Vultr).
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/bgp/ipv6/peer-asn
Example Response:
64515
My Address
/v1/bgp/ipv6/my-address
Retrieve the BGP IPv6 address of the calling VM.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/bgp/ipv6/my-address
Example Response:
2001:0db8:7400:7ccf:5428:d5ff:fe28:1910
My ASN
/v1/bgp/ipv6/my-asn
Retrieve the BGP ASN of the calling VM.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/bgp/ipv6/my-asn
Example Response:
64496
Network Interfaces
Index
/v1/interfaces/
Retrieve the interface index.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/
Example Response:
0/
1/
Interface Index
/v1/interfaces/0/
Retrieve the index of the specified network interface. The first interface is labeled with "0", counting onward for subsequent interfaces.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/
Example Response:
network-type
mac
ipv4/
ipv6/
Network Type
/v1/interfaces/0/network-type
Retrieve the network type of the specified interface. The value can be one of: "public", "private".
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/network-type
Example Response:
public
MAC
/v1/interfaces/0/mac
Retrieve the mac address of the specified network interface.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/mac
Example Response:
00:00:00:00:00:00
NETWORKID
/v1/interfaces/0/networkid
For private networks, retrieve the NETWORKID of the specified network interface.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/networkid
Example Response:
net59a077ae437d8
Primary IPv4 Index
/v1/interfaces/0/ipv4/
Retrieve the IPv4 index of the specified network interface.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv4/
Example Response:
address
gateway
netmask
additional/
IPv4 Address
/v1/interfaces/0/ipv4/address
Retrieve the IPv4 address of the specified network interface.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv4/address
Example Response:
192.0.2.2
IPv4 Gateway
/v1/interfaces/0/ipv4/gateway
Retrieve the IPv4 gateway of the specified network interface.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv4/gateway
Example Response:
192.0.2.1
IPv4 Netmask
/v1/interfaces/0/ipv4/netmask
Retrieve the IPv4 netmask of the specified network interface.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv4/netmask
Example Response:
255.255.255.0
Additional IPv4 List Index
/v1/interfaces/0/ipv4/additional/
Retrieve a list of additional IPv4 addresses available to the specified network interface. The first address is labeled with "0", counting onward for subsequent addresses.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv4/additional/
Example Response:
0/
Additional IPv4 Index
/v1/interfaces/0/ipv4/additional/0/
Retrieve the index of the specified IPv4 address for a given network interface. This index does not include the main IPv4 address.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv4/additional/0/
Example Response:
address
netmask
IPv4 Address
/v1/interfaces/0/ipv4/additional/0/address
Retrieve the address of an additional IPv4.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv4/additional/0/address
Example Response:
192.0.2.3
IPv4 Netmask
/v1/interfaces/0/ipv4/additional/0/netmask
Retrieve the netmask of an additional IPv4.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv4/additional/0/netmask
Example Response:
255.255.255.0
Primary IPv6 Index
/v1/interfaces/0/ipv6/
Retrieve the IPv6 index of the specified network interface.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv6/
Example Response:
network
prefix
additional/
IPv6 Address
/v1/interfaces/0/ipv6/address
Retrieve the default IPv6 address of the specified network interface. You can use any address within the block, this address is only a suggestion.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv6/address
Example Response:
2001:0db8:0:1:5428:d5ff:fe28:1910
IPv6 Network
/v1/interfaces/0/ipv6/network
Retrieve the IPv6 network of the specified network interface.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv6/network
Example Response:
2001:0db8:0:1::
IPv6 Prefix
/v1/interfaces/0/ipv6/prefix
Retrieve the IPv6 prefix of the specified network interface.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv6/prefix
Example Response:
64
Additional IPv6 List Index
/v1/interfaces/0/ipv6/additional/
Retrieve a list of additional IPv6 networks available to the specified network interface. The first network is labeled with "0", counting onward for subsequent networks.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv6/additional/
Example Response:
0/
Additional IPv6 Index
/v1/interfaces/0/ipv6/additional/0/
Retrieve the index of the specified IPv6 network for a given network interface. This index does not include the main IPv6 network.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv6/additional/0/
Example Response:
network
prefix
IPv6 Network
/v1/interfaces/0/ipv6/additional/0/network
Retrieve the network of an additional IPv6.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv6/additional/0/network
Example Response:
2001:0db8:0:2::
IPv6 Prefix
/v1/interfaces/0/ipv6/additional/0/prefix
Retrieve the prefix of an additional IPv6.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/interfaces/0/ipv6/additional/0/prefix
Example Response:
64
Region
Index
/v1/region/
Retrieve the region index.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/region/
Example Response:
regioncode
Region Code
/v1/region/regioncode
Retrieve the region code of the calling VM.
Request Type: | GET |
Example Request:
curl http://169.254.169.254/v1/region/regioncode
Example Response:
EWR