Instance Metadata Service

The instance metadata service is a link-local HTTP API available from within any running Latitude.sh bare metal server. It allows your server to query its own metadata — hostname, IP addresses, network configuration, storage layout, tags, and more — without needing external API credentials.

The instance metadata service is not part of the main Latitude.sh REST API. It uses its own token-based authentication and is only accessible from within a bare metal server. Your regular API keys will not work with this service.

The metadata service is not yet available in the SAO and SAN3 regions. Support for these regions will be added in a future update.

Base URL

All requests use the following base URL:

http://169.254.169.254/metadata/v1

This is a link-local address that is only reachable from within the server itself. It is not accessible from the public internet.

Authentication

The metadata service uses token-based authentication (IMDSv2-style). Before making any metadata requests, you must obtain a session token.

Requesting a token

Make a PUT request to the token endpoint with a TTL (time-to-live) header specifying how long the token should be valid, in seconds. Response body: The session token is returned as plain text in the response body.

Header	Description
`X-Metadata-Token`	The session token to use in subsequent requests.

TOKEN=$(curl -s -X PUT "http://169.254.169.254/metadata/v1/api/token" \
  -H "X-Metadata-Token-TTL-Seconds: 3600")

Use the returned token in the X-Metadata-Token header for all subsequent metadata requests.

Retrieving metadata (full JSON)

To retrieve all metadata as a single JSON object, send a GET request to /metadata/v1/metadata.json:

curl -s "http://169.254.169.254/metadata/v1/metadata.json" \
  -H "X-Metadata-Token: $TOKEN" | jq

Example response:

{
  "instance_id": "sv_abc123def456",
  "hostname": "my-server",
  "local_ipv4": "10.0.0.5",
  "public_ipv4": "203.0.113.10",
  "public_ipv6": "2001:db8::1",
  "region": "SAO",
  "plan": "c3.medium.x86",
  "operating_system": "ubuntu_24_04_x64_lts",
  "userdata": "#cloud-config\npackages:\n  - nginx",
  "tags": [
    { "key": "env", "value": "production" },
    { "key": "team", "value": "infra" }
  ],
  "network": {
    "interfaces": [
      {
        "name": "eth0",
        "mac": "aa:bb:cc:dd:ee:f0",
        "addresses": [
          {
            "address": "203.0.113.10",
            "prefix": 30,
            "family": "IPv4",
            "type": "public"
          },
          {
            "address": "2001:db8::1",
            "prefix": 127,
            "family": "IPv6",
            "type": "public"
          }
        ]
      },
      {
        "name": "eth1",
        "mac": "aa:bb:cc:dd:ee:f1",
        "addresses": [
          {
            "address": "10.0.0.5",
            "prefix": 24,
            "family": "IPv4",
            "type": "private"
          }
        ]
      }
    ],
    "dns": {
      "nameservers": ["8.8.8.8", "8.8.4.4"]
    }
  },
  "storage": {
    "disks": [
      {
        "name": "sda",
        "size_gb": 480,
        "type": "SSD",
        "model": "INTEL SSDSC2KB48"
      },
      {
        "name": "sdb",
        "size_gb": 480,
        "type": "SSD",
        "model": "INTEL SSDSC2KB48"
      }
    ]
  },
  "ssh_keys": [
    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@example.com"
  ],
  "vendor": {
    "latitude": {
      "project_id": "prj_abc123",
      "team_id": "team_xyz789"
    }
  }
}

Retrieving metadata (path-based)

You can query individual metadata fields by appending the field path to the base URL. Each path returns a plain-text value or a JSON fragment.

Available paths

Path	Description
`/metadata/v1/instance_id`	Unique server identifier
`/metadata/v1/hostname`	Server hostname
`/metadata/v1/local_ipv4`	Private IPv4 address
`/metadata/v1/public_ipv4`	Public IPv4 address
`/metadata/v1/public_ipv6`	Public IPv6 address
`/metadata/v1/region`	Region code (e.g., `SAO`, `DAL`)
`/metadata/v1/plan`	Server plan slug
`/metadata/v1/operating_system`	Operating system slug
`/metadata/v1/userdata`	User data script content
`/metadata/v1/tags`	Tags array (JSON)
`/metadata/v1/network`	Full network configuration (JSON)
`/metadata/v1/storage`	Storage/disk information (JSON)
`/metadata/v1/ssh_keys`	SSH public keys (JSON array)
`/metadata/v1/vendor`	Vendor-specific metadata (JSON)

Examples

Get the server hostname:

curl -s "http://169.254.169.254/metadata/v1/hostname" \
  -H "X-Metadata-Token: $TOKEN"

my-server

Get the public IPv4 address:

curl -s "http://169.254.169.254/metadata/v1/public_ipv4" \
  -H "X-Metadata-Token: $TOKEN"

203.0.113.10

Get the network configuration:

curl -s "http://169.254.169.254/metadata/v1/network" \
  -H "X-Metadata-Token: $TOKEN" | jq

Response schema

Top-level fields

Field	Type	Description
`instance_id`	string	Unique identifier for the server
`hostname`	string	Server hostname
`local_ipv4`	string	Private IPv4 address
`public_ipv4`	string	Public IPv4 address
`public_ipv6`	string	Public IPv6 address
`region`	string	Region code where the server is deployed
`plan`	string	Server plan slug (e.g., `c3.medium.x86`)
`operating_system`	string	OS slug (e.g., `ubuntu_24_04_x64_lts`)
`userdata`	string	User data script content, if set during deployment
`tags`	array	Array of tag objects with `key` and `value` strings
`network`	object	Network configuration (see below)
`storage`	object	Storage/disk information (see below)
`ssh_keys`	array	Array of SSH public key strings
`vendor`	object	Vendor-specific metadata (see below)

`network` object

The network object contains the server’s network interfaces and DNS configuration. network.interfaces[]

Field	Type	Description
`name`	string	Interface name (e.g., `eth0`)
`mac`	string	MAC address
`addresses`	array	Array of address objects

network.interfaces[].addresses[]

Field	Type	Description
`address`	string	IP address
`prefix`	integer	CIDR prefix length
`family`	string	`IPv4` or `IPv6`
`type`	string	`public` or `private`

network.dns

Field	Type	Description
`nameservers`	array	Array of DNS nameserver IP addresses

`storage` object

storage.disks[]

Field	Type	Description
`name`	string	Device name (e.g., `sda`)
`size_gb`	integer	Disk size in gigabytes
`type`	string	Disk type (e.g., `SSD`, `NVMe`, `HDD`)
`model`	string	Disk model identifier

`vendor` object

vendor.latitude

Field	Type	Description
`project_id`	string	ID of the project this server belongs to
`team_id`	string	ID of the team that owns the server

You can use the metadata service together with user data to automatically configure your servers at boot — for example, setting up network interfaces or registering the server in a service discovery system.

Introduction

Endpoints

Base URL

Authentication

Requesting a token

Retrieving metadata (full JSON)

Retrieving metadata (path-based)

Available paths

Examples

Response schema

Top-level fields

`network` object

`storage` object

`vendor` object

​Base URL

​Authentication

​Requesting a token

​Retrieving metadata (full JSON)

​Retrieving metadata (path-based)

​Available paths

​Examples

​Response schema

​Top-level fields

​network object

​storage object

​vendor object

Base URL

Authentication

Requesting a token

Retrieving metadata (full JSON)

Retrieving metadata (path-based)

Available paths

Examples

Response schema

Top-level fields

`network` object

`storage` object

`vendor` object