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
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")
X-Metadata-Token header for all subsequent metadata requests.
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
{
"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"
}
}
}
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"
curl -s "http://169.254.169.254/metadata/v1/public_ipv4" \
-H "X-Metadata-Token: $TOKEN"
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. 
