> ## 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](/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](/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>