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:

{
  "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:

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:

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:

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

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