Vultr

Metadata API

Metadata API

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