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