> ## Documentation Index
> Fetch the complete documentation index at: https://www.latitude.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Instance Metadata Service

> Complete reference for the instance metadata service available from within Latitude.sh bare metal servers

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.

<Warning>
  The instance metadata service is **not** part of the main [Latitude.sh REST API](/docs/api-reference/summary). 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.
</Warning>

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

## 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. |

```bash theme={null}
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`:

```bash theme={null}
curl -s "http://169.254.169.254/metadata/v1/metadata.json" \
  -H "X-Metadata-Token: $TOKEN" | jq
```

**Example response:**

```json theme={null}
{
  "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:

```bash theme={null}
curl -s "http://169.254.169.254/metadata/v1/hostname" \
  -H "X-Metadata-Token: $TOKEN"
```

```
my-server
```

Get the public IPv4 address:

```bash theme={null}
curl -s "http://169.254.169.254/metadata/v1/public_ipv4" \
  -H "X-Metadata-Token: $TOKEN"
```

```
203.0.113.10
```

Get the network configuration:

```bash theme={null}
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 |

<Tip>
  You can use the metadata service together with [user data](/docs/servers/user-data) to automatically configure your servers at boot — for example, setting up network interfaces or registering the server in a service discovery system.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.