# Getting started with FlexMetal

Please get in touch with the i3D.net sales team to start using FlexMetal or learn more about the product's current state and roadmap.

## Prerequisites

To create a new FlexMetal server, you will need to follow four prerequisite steps:

1. An **API Token**
2. Geographical **Location**
3. Instance Type
4. Operating System

***

## Using the FlexMetal Terraform provider

FlexMetal can be used through our API, or through our Terraform provider. Refer to the [i3D.net Terraform Documentation](https://registry.terraform.io/providers/i3dnet/i3dnet/latest/docs) for more information.

Similar to the API endpoint, you'll need an API token for using the Terraform provider. The procedure is documented in [API v3 Authentication](/game-hosting/overview/apiv3-authentication.md)

{% hint style="info" %}
Add IP whitelisting for security (whitelist the IP addresses that will access the API)
{% endhint %}

***

## Using FlexMetal API

{% hint style="info" %}
Note : API URL prefix is `https://api.i3d.net`
{% endhint %}

### 1. API Token

* Generate an API token, the procedure is documented in [API v3 Authentication](/game-hosting/overview/apiv3-authentication.md)
  1. Add IP whitelisting for security (whitelist the IP addresses that will access the API)
* Include your API key in every request using this **HTTP header**:<br>

  | HTTP Header Name | HTTP Header Value |
  | ---------------- | ----------------- |
  | PRIVATE-TOKEN    | YOUR\_API\_KEY    |
* Throughout these documentation pages, we will refer to API endpoints like for instance:

  `GET /v3/flexMetal/location`

  \
  This is not a complete endpoint. You must prefix this with the API URI and API version tag:

  `https://api.i3d.net/v3/`

  \
  That results in the complete URL:

  `GET https://api.i3d.net/v3/flexMetal/location`

<pre data-title="Example HTTP request:"><code>GET /v3/flexMetal/location
<strong>Host: api.i3d.net
</strong>PRIVATE-TOKEN: abc123xyz789
</code></pre>

### 2. Location

Locations are named for the i3D.net Datacenter where FlexMetal instances are available. Below is a small extract of available locations:

<table><thead><tr><th width="170.93359375">Region</th><th width="237.66796875">Country / State</th><th>Location Name</th></tr></thead><tbody><tr><td>Europe</td><td>Netherlands</td><td><code>EU: Rotterdam</code></td></tr><tr><td>Europe</td><td>France</td><td><code>EU: Montreuil 1</code></td></tr><tr><td>USA</td><td>Virginia</td><td><code>US: Ashburn - VA</code></td></tr><tr><td>USA</td><td>Texas</td><td><code>US: Dallas - TX</code></td></tr><tr><td>USA</td><td>California</td><td><code>US: Los Angeles - CA</code></td></tr><tr><td>Asia</td><td>Japan</td><td><code>JP: Tokyo</code></td></tr><tr><td>Asia</td><td>Hong Kong</td><td><code>HK: Hong Kong</code></td></tr><tr><td>Latam</td><td>Brazil</td><td><code>BR: Sao Paulo</code></td></tr><tr><td>Middle East</td><td>United Arab Emirates</td><td><code>AE: Dubai</code></td></tr></tbody></table>

The full list of worldwide locations can be found using the location endpoint:\
[`GET /v3/flexMetal/location/`](https://docs.i3d.net/api/api_general#get-v3-flexmetal-location)

### 3. Instance Type

The instance type specifies the hardware configuration of a bare metal server. Below is a list of available instance types:

<table data-full-width="true"><thead><tr><th width="143.859375">Instance</th><th width="110.9453125">CPU Model</th><th width="118.08984375">Generation</th><th>CPU Specifications</th><th width="85.2578125">RAM</th><th width="103.80078125">Storage</th><th width="87.4375">Uplinks</th></tr></thead><tbody><tr><td><code>bm7.std.8</code></td><td>Intel Xeon E-2278G</td><td>Coffee Lake (14nm)</td><td>8 Cores / 16 Threads @ 3.40 GHz</td><td>32 GB DDR4</td><td>1x 960 GB SSD</td><td>2x1G</td></tr><tr><td><code>bm7.hmm.8</code></td><td>Intel Xeon E-2278G</td><td>Coffee Lake (14nm)</td><td>8 Cores / 16 Threads @ 3.40 GHz</td><td>64 GB DDR4</td><td>1x 960 GB SSD</td><td>2x1G</td></tr><tr><td><code>bm8.std.32</code></td><td>AMD EPYC 7502P</td><td>Rome Zen3 (7nm)</td><td>32 Cores / 64 Threads @ 2.50 GHz</td><td>128 GB DDR4</td><td>2x 960 GB SSD</td><td>2x25G</td></tr><tr><td><code>bm9.hmm.32</code></td><td>AMD EPYC 9354P</td><td>Genoa Zen4 (5nm)</td><td>32 Cores / 64 Threads @ 3.25 GHz</td><td>256 GB DDR5</td><td>1x 1.92 TB NVME</td><td>2x25G</td></tr><tr><td><code>bm9.std.32</code></td><td>AMD EPYC 9354P</td><td>Genoa Zen4 (5nm)</td><td>32 Cores / 64 Threads @ 3.25 GHz</td><td>128 GB DDR5</td><td>1x 1.92 TB NVME</td><td>2x25G</td></tr><tr><td><code>bm9.hmm.12</code></td><td>AMD EPYC 4464P</td><td>Raphael Zen4 (5nm)</td><td>12 Cores / 24 Threads @ 3.7 GHz</td><td>128 GB RAM</td><td>1x 1.92 TB NVME</td><td>2x25G</td></tr></tbody></table>

{% hint style="info" %}
Instance Type availability can differ per location. Not all Instance Types are available in all locations.

\
Obtain a list of available Instance Types per location and their availability using the /plans API endpoint:\
[`GET /v3/flexMetal/plans`](https://customer.i3d.net/apidoc-v3/all#/FlexMetalServer/getFlexMetalPlans)
{% endhint %}

### 4. Operating System

FlexMetal supports many Operating Systems. Below is a small extract of available OS's:

| OS                        | slug              |
| ------------------------- | ----------------- |
| Ubuntu 22.04 LTS          | `ubuntu-2204-lts` |
| Ubuntu 24.04 LTS          | `ubuntu-2404-lts` |
| Talos Omni 1.8.0 - 1.11.0 | `talos-omni-1110` |
| Debian 12 - 13            | `debian-13`       |

The full list of supported OS's can be found using the API endpoint: [`GET /v3/operatingsystem`](https://docs.i3d.net/api/api_general#get-v3-operatingsystem).

Talos has frequent updates. You can check which is the latest supported version using the endpoint above.

## Creating a Server (POST)

[`POST /v3/flexMetal/servers`](https://docs.i3d.net/api/api_general#post-v3-flexmetal-servers)

This endpoint allows you to create a new bare-metal server by specifying key details such as the server (host) name, location, instance type, operating system, and additional configurations like SSH keys, post-installation scripts, tags, and contract ID with overflow settings.

### Server request body properties

<table data-full-width="true"><thead><tr><th width="192.47265625">Property</th><th width="103.765625">Value type</th><th width="98.2734375">Required</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>name</code></td><td>string</td><td>Required</td><td>Human-readable (host) name for the server instance</td><td><code>server1.example.com</code></td></tr><tr><td><code>location</code></td><td>string</td><td>Required</td><td>The data center or region where the server will be deployed</td><td><code>EU: Rotterdam</code></td></tr><tr><td><code>instanceType</code></td><td>string</td><td>Required</td><td>The type of instance to be provisioned (defines hardware resources)</td><td><code>bm7.std.8</code></td></tr><tr><td><code>os</code></td><td>object</td><td>Required</td><td>Specifies the operating system and optional kernel parameters</td><td>See table below.</td></tr><tr><td><code>sshKey</code></td><td>array</td><td>Required</td><td>List of public SSH keys, can also be sshkey UUIDs</td><td><code>"ssh-rsa AAAAB3NzaC1yc..."</code></td></tr><tr><td><code>postInstallScript</code></td><td>string</td><td>Optional</td><td>A script that runs automatically after the server is installed. <strong>Not applied for <code>custom-ipxe</code> installs</strong> (e.g. Flatcar) — use <code>userData</code> instead.</td><td><code>"#!/bin/bash echo Hello"</code></td></tr><tr><td><code>userData</code></td><td>object</td><td>Optional</td><td>Arbitrary data made available to the server via the <a href="/pages/hD6pHNFEUANWS7kUGdau#userdata">Metadata API userdata endpoint</a>. Typically used with <code>custom-ipxe</code> installs to supply ignition configs or post-boot scripts.</td><td>See <a href="/pages/hD6pHNFEUANWS7kUGdau#userdata">Metadata API — Userdata</a></td></tr><tr><td><code>tags</code></td><td>array</td><td>Optional</td><td>List of Tags.<br><br>Each tag must be in the format <code>[A-Za-z0-9_:-]{1,64}</code></td><td><code>["my-tag1", "set:value"]</code></td></tr><tr><td><code>contractId</code></td><td>string</td><td>Optional</td><td>A contractId in format <code>^[A-Z0-9_\-.]{0,240}$</code></td><td><code>CTR-1</code></td></tr><tr><td><code>overflow</code></td><td>bool</td><td>Optional</td><td>Parameter that indicates if on-demand pool should be used</td><td><code>false</code></td></tr></tbody></table>

### OS Parameter

The `os` parameter allows you to define the operating system for the server, an optional partitioning scheme and optional kernel parameters.

<table data-full-width="true"><thead><tr><th width="171.28515625">Field</th><th width="108.87109375">Type</th><th>Description</th><th>Example Value</th></tr></thead><tbody><tr><td><code>slug</code></td><td>string</td><td>The slug identifying the operating system to install (e.g., Linux distro)</td><td><code>ubuntu-2404-lts</code></td></tr><tr><td><code>kernelParams</code></td><td>array</td><td>(Optional) A list of kernel parameters to customize the OS installation, currently only used for Talos installations</td><td>See <a href="/pages/fohQXEv1nFOEaKlq8W9k">OS Customization</a></td></tr><tr><td><code>partitions</code></td><td>array</td><td>(Optional) A list of custom disk partitions</td><td>See <a href="/pages/fohQXEv1nFOEaKlq8W9k">OS Customization</a></td></tr></tbody></table>

### SSH Keys

The `sshKey` parameter allows you to provide your public keys for your root logins.

{% hint style="warning" %}
Talos does not have a shell and as such does not require an SSH key. Windows OS does not support SSH keys. You will need to know your root password. The root password is accessible [here](https://www.i3d.net/docs/api/v3/all#/FlexMetalServer/getFlexMetalServerRootPasswords). Note that we support Windows 2022. **You must fetch the root password within the first 24 hours after installation.**
{% endhint %}

You can provide actual public keys, or you can give the `uuid` of already stored SSH keys. The latter can be managed via the SSH CRUD endpoints:

* Creating a SSH Key : [`POST /v3/sshKey`](https://customer.i3d.net/apidoc-v3/all#/SSHKey/createSshKey)
* Listing SSH Keys : [`GET /v3/sshKey`](https://customer.i3d.net/apidoc-v3/all#/SSHKey/getSshKeys)
* Deleting SSH Keys : [`DELETE /v3/sshKey`](https://customer.i3d.net/apidoc-v3/all#/SSHKey/deleteSshKey)

### Contract Id and Overflow

The `contractId` parameter allows you to specify the contract under which the server should be billed. If you want the server to be charged against a specific contract and use your **Committed Quota (Guaranteed Resources)**, provide the appropriate contract ID here. The contract ID must match the format: `^[A-Z0-9_\-.]{0,240}$`.

The `overflow` parameter determines whether the server should be created from the **On-Demand** pool when your Committed Quota for the specified contract ID is exhausted. If set to true, the server will be provisioned from the On-Demand pool.\
Please note that resource availability in the on-demand pool is not guaranteed and is allocated on a first-come, first-served basis. Default value is `false`.

### Example request

[`POST /v3/flexMetal/servers`](https://docs.i3d.net/api/api_general#post-v3-flexmetal-servers)

Request Body

```json
{
  "name": "MyFlexServer",
  "location": "EU: Rotterdam",
  "instanceType": "bm7.std.8",
  "os": {
    "slug": "ubuntu-2404-lts"
  },
  "sshKey": [
    "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBIWrzxdeW3hhkejzSfFBFzPzcEBJBGtggOUJpLBCakbqmV/NztCaUoh631Xnk46MFn2snF89tSZZzlp9ySpqW7c= ecdsa-key-example"
  ],
  "postInstallScript": "#!/bin/bash\necho \"Hello flex world\" > /tmp/test.txt",
  "tags": [
    "My-tag1",
    "env:dev"
  ],
  "contractId": "CTR-1",
  "overflow": true
}
```

### Response

If the request is successful, you will receive a response containing the details of the new server.

The Server UUID will be provided and can be used for getting server-specific details and releasing the server.

The server IP address(es) will also be populated once the provisioning process has configured the server's networking data.

Example Response:

```json
[
    {
        "uuid": "019257a3-dxxxx-xxxx-xxxx-84c78b711f6e",
        "name": "MyFlexServer",
        "status": "created",
        "statusMessage": "OK",
        "location": {
            "id": 18,
            "name": "EU: Rotterdam"
        },
        "instanceType": {
            "id": 129,
            "name": "bm7.std.8"
        },
        "os": {
            "slug": "ubuntu-2404-lts"
        },
        "ipAddresses": [
            {
                "ipAddress": "x.x.x.x"
            }
        ],
        "tags": [
            "My-tag1",
            "env:dev"
        ],
        "createdAt": 1728047209,
        "deliveredAt": null,
        "releasedAt": null,
        "contractId": "CTR-1"
    }
]
```

### Server Statuses

You can track the progress of server delivery via the `status` field which can have the following values:

* created
* delivered
* failed
* released

There are three end states for all servers:

<table data-full-width="true"><thead><tr><th width="128.9765625">End state</th><th>Meaning</th></tr></thead><tbody><tr><td>created</td><td>Upon a successful API server request, a server entity is created and the provisioning process will commence.</td></tr><tr><td>delivered</td><td>When the server status reaches <code>delivered</code>, it will be available for usage. You can then login with your SSH key, or root password on Windows.</td></tr><tr><td>failed</td><td>If a problem arises during server provisioning, the status will be set to <code>failed</code> and the specific problem will be described in the <code>statusMessage</code> field of the response.</td></tr><tr><td>released</td><td>Upon releasing a server, its status will be set to <code>released</code>, indicating that you can no longer use it. The data on the server will then be securely erased.</td></tr></tbody></table>

{% hint style="warning" %}

* Billing will start at the `deliveredAt` date and will end when the server is released with the date shown as `releasedAt`.
* Billed hours will be rounded up to the full hour used.
  {% endhint %}

### Contract ID

If a contractId was provided in the request and is also present in the response body, it means the server was allocated from the **Committed Quota** pool.\
If the contractId is not present in the response body, the server was allocated from the **On-Demand** pool.

## List FlexMetal servers (GET)

This endpoint retrieves information about all servers currently provisioned in your FlexMetal account.

The FlexMetal API allows users to retrieve detailed information about all existing servers or specific servers in the FlexMetal environment. This guide provides documentation for the following endpoints:

* [`GET /v3/flexMetal/servers`](https://docs.i3d.net/api/api_general#get-v3-flexmetal-servers): Retrieve a list of all servers.
* [`GET /v3/flexMetal/servers/{uuid}`](https://docs.i3d.net/api/api_general#get-v3-flexmetal-servers-uuid): Retrieve detailed information about a specific server by its unique identifier.

Server can be filtered by statuses by using, for example :\
`/v3/flexMetal/servers?status=delivered`

### Filtering on Tags

Tags can be used to filter results for example:\
`/v3/flexMetal/servers?tag=My-tag1`

You can provide more than one tag to filter on, for example:\
`/v3/flexMetal/servers?tag=My-tag1&tag=env:dev`

Only servers with all the provided tags will be returned when searching by multiple tags.

### Pagination

The server's entries returned by the API can be paginated using HTTP Header key `RANGED-DATA` and the value `start=xx,results=yy`

Where `xx` is starting index number beginning at `0` and `yy` is the number of entries to return, with a maximum to `50`

<pre data-title="Example HTTP request:"><code>GET /v3/flexMetal/servers?status=delivered
<strong>Host: api.i3d.net
</strong>PRIVATE-TOKEN: abc123xyz789
RANGED-DATA: start=15,results=30
</code></pre>

The default pagination returns a maximum of 15 server entries.

{% hint style="warning" %}
Servers that are in a `failed` or `released` state will only be visible in your GET responses for 24 hours.
{% endhint %}

## Releasing FlexMetal servers (DELETE)

{% hint style="danger" %}
This operation cannot be undone, so back up any necessary data before deleting the server.
{% endhint %}

[`DELETE /v3/flexMetal/servers/{uuid}`](https://docs.i3d.net/api/api_general#delete-v3-flexmetal-servers-uuid)

This endpoint releases or deletes a FlexMetal server from your infrastructure. Once a server is released, it is no longer available, and all resources such as storage, network configurations, and data are removed.

## FlexMetal server commands: power\_on, power\_off, and reboot

With FlexMetal, you can utilize the following commands for your servers:

* "power\_on"
* "power\_off"
* "reboot"

### Example request

`POST /v3/flexMetal/server/{uuid}`

Request Body

```json
{
  "command": "reboot",
}
```

{% hint style="warning" %}
Commands are executed immediately. Verify execution by checking if the server is rebooting or if the power status is on or off.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.i3d.net/compute/flexmetal/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.