> For the complete documentation index, see [llms.txt](https://docs.i3d.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.i3d.net/compute/flexmetal/metadata-api.md).

# Metadata API

You can fetch server configurations and settings via the Metadata API.

The Metadata API can be queried from your FlexMetal server, to fetch information about that server. It provides network configuration data, SSH keys, tag, the location of the server and many other details related to your server. This can be used in combination with Cloud Init or Ignition to auto-configure a server during first boot, or to have applications fetch information about the server they run on.

The Metadata API does not require any authentication. You can simply query it from your server and you will get a JSON response.

## Querying the Metadata API

To query the Metadata API you can make the following request from your server:

`GET https://metadata.i3d.net/v1/metadata`

This will respond with a JSON object such as:

```json
{
  "hostname": "server.example.org",
  "instance_type": {
    "name": "bm7.std.8",
    "cpu": {
        "name": "Intel(R) Xeon(R) E-2278G CPU @ 3.40GHz",
        "base_clock": 3400,
        "cpu_count": 1,
        "cpu_cores": 8
    },
    "memory": {
        "type": "ddr4",
        "size": 32
    },
    "network_interfaces": [
      {
          "type": "1 Gbps",
          "count": 2
      }
    ],
    "disks": [
      {
        "type": "ssd",
        "size": 480
      }
    ]
  },
  "location": {
    "dc_code": "nlrtm1",
    "name": "EU: Rotterdam"
  },
  "network_interfaces": [
    {
      "is_bond": true,
      "mac_address": "10:98:36:A0:83:DD",
      "name": "bond0",
      "networks": [
        {
          "ip": "5.200.22.205",
          "netmask": "255.255.255.192",
          "prefix": "26",
          "gateway": "5.200.22.193",
          "vlan_id": 2602
        },
        {
          "ip": "2a00:1630:2602:6::",
          "prefix": "48",
          "gateway": "2a00:1630:2602::1",
          "vlan_id": 2602
        }
      ],
      "child_interfaces": [
        {
          "mac_address": "10:98:36:A0:83:DD",
          "name": "eno0"
        },
        {
          "mac_address": "10:98:36:A0:83:DE",
          "name": "eno1"
        }
      ]
    }
  ],
  "operating_system": {
    "slug": "ubuntu-2404-lts",
    "name": "Ubuntu",
    "version": "24.04"
  },
  "server_id": "019bff06-a8ac-72e6-a0cb-82ac3f2dd000",
  "ssh_keys": [
    "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBHo8IaPkQ6UnDZvi4F4RBSouRa6Gtysdg2EF+SIXheVF2SGBQ2uH7RfDjXRfvq4VpHJrKYs4kWfNoHQg8ZG6PH4="
  ],
  "tags": [
    "a-tag"
  ]
}
```

## Userdata

When creating a server, you can specify arbitrary data in the request body, called "userdata", which you can later retrieve using the Metadata API. Some examples: an installation shell script, a JSON containing configuration properties or a custom binary file.

To be able to fetch user data from your server, specify it in the request property `userData.data` when requesting to create a server. For example, setting userdata to a custom script:

```http
POST https://api.i3d.net/v3/flexMetal/servers
Content-Type: application/json

{
  ...
  "userData": {
    "data": "#!/bin/bash\necho \"my custom script\""
  }
  ...
}
```

Then later on, you can retrieve it from the server using the metadata API, like so:

```shell
curl -X GET https://metadata.i3d.net/v1/userdata
```

The response will be whatever you configured in the `userData.data` property when creating a server via the create-server request. If you wish to set userdata to be a binary file, because JSON does not work with binary data, you can base64-encode it and indicate it in the request. Example: setting a zip file (binary) as userdata:

```http
POST https://api.i3d.net/v3/flexMetal/servers
Content-Type: application/json

{
  ...
  "userData": {
    "data": "UEsDBAoAAAAAAM1tf1xyjbEOEQAAABEAAAAIABwAZmlsZS50eHRVVAkAAxK0y2kUtMtpdXgLAAEE+AEAAAQUAAAAY29udGVudHMgb2YgZmlsZQpQSwECHgMKAAAAAADNbX9cco2xDhEAAAARAAAACAAYAAAAAAABAAAApIEAAAAAZmlsZS50eHRVVAUAAxK0y2l1eAsAAQT4AQAABBQAAABQSwUGAAAAAAEAAQBOAAAAUwAAAAAA",
    "isBase64": true
  }
  ...
}
```

{% hint style="info" %}
`isBase64` applies to the **request only**. It tells us how to decode your payload on the way in, because JSON cannot carry binary data. The Metadata API always serves the original, decoded content — you never need to base64-decode the `/v1/userdata` response yourself.
{% endhint %}

See [Post-install scripts](/compute/flexmetal/post-install-scripts.md#combining-the-two) for reading userdata from a script that runs on first boot, on both Linux and Windows.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.i3d.net/compute/flexmetal/metadata-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.