Skip to content

Getting started using API

Warning

FlexMetal is under active development and still in closed Alpha state.

Please get in touch with the i3D.net sales team to learn more about the product state and roadmap or if you wish to be part of the closed Alpha program for FlexMetal.

What is FlexMetal

FlexMetal makes it easy to set up and manage high-performance bare metal servers dedicated hardware that combines the power of physical servers with the flexibility of cloud services. With FlexMetal, you can choose between hourly or monthly billing options, allowing you to optimize costs based on your usage.

Two Ways to Order Compute Resources:

FlexMetal offers two primary ways to allocate compute resources, ensuring you have the flexibility and control you need:

On-Demand:

  • How it works: You can quickly request additional compute resources as needed. However, On-Demand resources are not guaranteed and are available on a first-come, first-served basis.
  • Best for: Handling occasional or unpredictable spikes in resource needs.

Committed Pool (Guaranteed Resources):

  • How it works: For consistent and predictable workloads, you can create a committed pool of resources. This ensures that the baseline capacity you require is always available. Any additional needs beyond this pool can still be met with On-Demand resources, but these will not be guaranteed.
  • Best for: Ensuring predictable access to a fixed set of resources while retaining the flexibility to scale up with On-Demand when necessary.

How FlexMetal Balances Resource Allocation:

When you request server capacity, FlexMetal will prioritize fulfilling the request from your committed pool of guaranteed resources. If all committed capacity is in use, FlexMetal will automatically begin provisioning additional resources from the On-Demand pool.

This dynamic allocation ensures that you always have the necessary resources, while allowing you to scale up flexibly when required to handle unexpected demand

Note : Please get in touch with the i3D.net sales team to set up a committed pool tied to a commercial agreement.

Prerequisites

In order to create a new FlexMetal server you will need to have 4 pre-requisite steps :

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

Note : API URL prefix is https://api.i3d.net

1. API Token

The procedure is documented in API v3 Authentication

Create an API Key and please remember to add IP whitelisting to access the API.

API Key is to be used in HTTP Header as Key = PRIVATE-TOKEN and Value = your_api_key

2. Location

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

Region Location Name
Europe EU: Rotterdam
Europe EU: Montreuil 1
USA US: Ashburn - VA
USA US: Dallas - TX
USA US: Los Angeles - CA
Asia JP: Tokyo
Asia HK: Hong Kong
Latam BR: Sao Paulo
Middle East AE: Dubai

The full list of worldwide locations can be found using the location endpoint : GET /v3/flexMetal/location/

3. Instance Type

The Instance Type defines the hardware configuration of the bare metal server. Here is an extract of available instance types:

Instance CPU Model Generation CPU Specifications RAM Storage Uplinks
bm7.std.8 Intel Xeon E-2278G Coffee Lake (14nm) 8 Cores / 16 Threads @ 3.40 GHz 32 GB DDR4 1x 960 GB SSD 2x1G
bm8.std.32 AMD EPYC 7502P Rome Zen3 (7nm) 32 Cores / 64 Threads @ 2.50 GHz 128 GB DDR4 2x 960 GB SSD 2x25G
bm9.hmm.32 AMD EPYC 9354P Genoa Zen4 (5nm) 32 Cores / 64 Threads @ 3.25 GHz 256 GB DDR5 1x 1.92 TB NVME 2x25G

The full list of Instance Types can be found on the Catalog page.

Note

4. Operating System

Many Operating Systems are supported by FlexMetal. 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.4 talos-omni-184
Debian 12 debian-12

The full list of supported OS's can be found using the API endpoint : GET /v3/operatingsystem.

Creating a Server (POST)

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 and post-installation scripts.

Server request body properties

Property Value type Required Description Example Value
name string Required Human-readable (host) name for the server instance server1.example.com
location string Required The data center or region where the server will be deployed EU: Rotterdam
instanceType string Required The type of instance to be provisioned (defines hardware resources) bm7.std.8
os object Required Specifies the operating system and optional kernel parameters See table below.
sshKey array Required List of public SSH keys, can also be sshkey UUIDs "ssh-rsa AAAAB3NzaC1yc..."
postInstallScript string Optional A script that runs automatically after the server is installed "#!/bin/bash echo Hello"
tags array Optional List of Tags. Each tag must be in the format [A-Za-z0-9_:-]{1,64} ["my-tag1", "set:value"]
Table 1: FlexMetal Server Request element structure

OS Parameter

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

Field Type Description Example Value
slug string The slug identifying the operating system to install (e.g., Linux distro) ubuntu-2404-lts
kernelParams array (Optional) A list of kernel parameters to customize the OS installation, currently only used for Talos installations See OS Customization
partitions array (Optional) A list of custom disk partitions See OS Customization

SSH Keys

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

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

Example request

POST /v3/flexMetal/servers

Request Body 

{
  "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"
  ]
}

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.

Server IP address will also be populated once provisioning process has been finished.

Example Response: 

[
    {
        "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
    }
]

Server Statuses

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

  • created
  • discovering
  • discovered
  • allocating
  • allocated
  • configuring_network
  • network_configured
  • provisioning
  • provisioned
  • delivered
  • failed
  • releasing
  • released

There are 3 end states for all servers:

End state Meaning
delivered After creating a server, the requested OS will be installed. When the server status reaches delivered, it will be available for usage. You can then login with the root user and your SSH key.
failed If a problem arises during the server creation, the status will be set to failed and the specific problem will be described in the statusMessage field of the response.
released After deleting a server, its status will be set to released, indicating that you can no longer use it. The data on the server will then be securely erased.

Note

  • Billing will start at the deliveredAt date and will end when server is released with date shown as releasedAt.
  • Billed hours will be rounded up to the full hour used.

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:

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

When searching by multiple tags, only servers with all the provided tags will be returned.

Pagination

The servers 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

Default pagination is returning maximum 15 servers entries

Note

Servers that are failed or released will be visible in your GET responses for 24 hours.

Releasing FlexMetal servers (DELETE)

Danger

This operation cannot be undone, so ensure that you have backed up any necessary data before deleting the server.

DELETE /v3/flexMetal/servers/{uuid}

This endpoint is used to release or delete 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.