Metadata API Service Available to All Vultr Cloud Servers

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",
    "instance-v2-id": "36e9cf60-5d93-4e31-8ebf-613b3d2874fb",
    "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",
        "network-v2-id": "742a1cc0-92da-4620-b875-2c8d5e040cba"
    }],
    "public-keys": ["ssh-rsa dGhpcyBpcyBhIHNhbXBsZSBzc2gga2V5IHRoaXMgaXMgYSBzYW1wbGUgc3NoIGtleSB0aGlzIGlzIGEgc2FtcGxlIHNzaCBrZXk= root@example1\nssh-rsa dGhpcyBpcyBhIHNhbXBsZSBzc2gga2V5IHRoaXMgaXMgYSBzYW1wbGUgc3NoIGtleSB0aGlzIGlzIGEgc2FtcGxlIHNzaCBrZXk= root@example2"],
    "region": {
        "regioncode": "EWR",
        "countrycode": "US"
    },
	"nvidia-driver": 470.82
}

Index

/v1/

Retrieve the metadata index.

Request Type: GET

Example Request:

curl http://169.254.169.254/v1/

Example Response:

hostname
instanceid
instance-v2-id
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

Instance V2 ID

/v1/instance-v2-id

Retrieve the v2 instance id of the calling VM.

Request Type: GET

Example Request:

curl http://169.254.169.254/v1/instance-v2-id

Example Response:

36e9cf60-5d93-4e31-8ebf-613b3d2874fb

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

NVidia Driver Version

/v1/nvidia-driver

Retrieve the NVidia Driver version running on the host.

Request Type: GET

Example Request:

curl http://169.254.169.254/v1/nvidia-driver

Example Response:

470.82

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:

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:

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:

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:

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

Network V2 ID

/v1/interfaces/0/network-v2-id

For private networks, retrieve the network's v2 ID of the specified network interface.

Request Type: GET

Example Request:

curl http://169.254.169.254/v1/interfaces/0/network-v2-id

Example Response:

742a1cc0-92da-4620-b875-2c8d5e040cba

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:

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:

Region

Index

/v1/region/

Retrieve the region index.

Request Type: GET

Example Request:

curl http://169.254.169.254/v1/region/

Example Response:

regioncode
countrycode

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

Country Code

/v1/region/countrycode

Retrieve the country code of the calling VM.

Request Type: GET

Example Request:

curl http://169.254.169.254/v1/region/countrycode

Example Response:

US