OpenMetal
API docs by Redocly

OpenMetal API (1.0.0)

Download OpenAPI specification:Download

Authentication

Most API endpoints are secured using Bearer Token Authentication. To access the API, you need to include a valid token in the Authorization header of your requests.

Example:

Authorization: Bearer <your-token>

Generating Tokens

There are two methods to obtain Bearer tokens for API authentication:

1. API Keys

API Keys are long-term tokens that provide persistent access to the API.

  • Generation: API Keys can be generated via OpenMetal Central
    • Navigate to Organization Dashboard → Organization Tools → API Keys
    • Create a new API key and securely store the generated token
  • Usage: Use the API key directly as a Bearer token in the Authorization header

2. OAuth 2.0 Clients

OAuth Applications provide short-lived tokens using client credentials.

  • Generation: OAuth Apps can be created via OpenMetal Central
    • Navigate to Organization Dashboard → Organization Tools → API Keys
    • Create a new OAuth Client
    • You will receive a client_id and client_secret
  • Token Exchange: Use your OAuth credentials to obtain a Bearer token via the /v1/oauth2/token endpoint (see below)

Security Notes

  • Keep all tokens and credentials secure and never share them publicly
  • API Keys should be rotated periodically
  • OAuth tokens have limited lifespans and should be refreshed as needed
  • Unauthorized requests will result in a 401 Unauthorized response

If you have trouble authenticating or accessing the API, please contact support@openmetal.io for assistance.

OAuth 2.0

Operations for OAuth 2.0 client credential flow and token management.

Get Token

Exchange OAuth Application client credentials for a short-lived Bearer token.

This endpoint uses Basic Authentication with your OAuth App credentials:

  • Username: client_id
  • Password: client_secret

The Authorization header should contain the Base64-encoded credentials in the format:

Authorization: Basic <Base64(client_id:client_secret)>

Example cURL request:

curl --location 'https://api.central.openmetal.io/v1/oauth2/token?grant_type=client_credentials' \
  --header 'Authorization: Basic <Base64-encoded-credentials>'
Authorizations:
basicAuth
query Parameters
grant_type
required
string
Value: "client_credentials"
Example: grant_type=client_credentials

The OAuth grant type. Currently only "client_credentials" is supported.

Responses

Response samples

Content type
application/json
{}

Clouds

Operations for managing a collection of servers. Private clouds or a group of baremetal nodes will be owned by a cloud resource.

Get a list of clouds

Retrieve a list of of your clouds.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a cloud by ID

Retrieve details of a specific cloud by their ID.

Authorizations:
bearerAuth
path Parameters
cloudId
required
string

The ID of the cloud to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "0Absd1",
  • "label": "My first cloud",
  • "description": "This cloud is for testing purposes.",
  • "created_at": "2021-01-01T00:00:00Z",
  • "fields": {
    }
}

Delete a cloud

Delete a cloud resource and reclaim all associated infrastructure.

Important: The cloud will be immediately deactivated upon successful deletion. However, there is a 3-day delay before servers are fully decommissioned and wiped. Clouds will enter a "pending-delete" state during this period.

Authorizations:
bearerAuth
path Parameters
cloudId
required
string
Example: 0Absd1

The ID of the cloud to delete.

Responses

Get cloud stats

Get detailed stats for a specific cloud including node hardware information, power states, VLAN configuration, and service assignments.

Authorizations:
bearerAuth
path Parameters
cloudId
required
string

The ID of the cloud to retrieve.

Responses

Response samples

Content type
application/json
{
  • "name": "US East - Production Cloud",
  • "description": "A Pre-prepared cloud generated automatically",
  • "label": "deploy-v2,pcc,pcc-3.0.7",
  • "cloud_uuid": "00000000-0000-0000-0000-000000000001",
  • "cloud_state": "RUNNING",
  • "cloud_hostname": "198.51.100.10",
  • "cloud_hosts": [
    ],
  • "external_vip_address": "198.51.100.10",
  • "internal_vip_address": "192.168.3.254",
  • "maintenance": false,
  • "creation_date": "2025-01-15T10:45:24.510406",
  • "pending_number": 0,
  • "pending_tasks": [
    ],
  • "pending_date": null,
  • "prevent_delete": false,
  • "nodes": [
    ],
  • "vlans": [
    ],
  • "keys": [
    ]
}

Assign a VLAN to a cloud

Assign an existing VLAN resource to a private cloud.

Requirements:

  • Both the cloud and VLAN must be in the same datacenter location
  • Both resources must be owned by the same organization
  • The cloud provisioning status must be "complete"
  • Clouds can have a maximum of 10 assigned VLANs
Authorizations:
bearerAuth
path Parameters
cloudId
required
string
Example: 0Absd1

The ID of the cloud to assign the VLAN to.

vlanId
required
string
Example: vl4nXy2Z9a

The ID of the VLAN resource to assign.

Responses

Response samples

Content type
application/json
{
  • "id": "vl4nXy2Z9a",
  • "type": "vlans",
  • "label": "production-vlan",
  • "description": "VLAN for production workloads",
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00",
  • "is_active": true,
  • "created_by": "o6aQxVGezj",
  • "fields": {
    }
}

Unassign a VLAN from a cloud

Unassign a VLAN resource from a private cloud.

This removes the association between the VLAN and the cloud but does not delete the VLAN resource itself.

Important: You cannot remove all VLAN assignments. A VLAN needs to have at least one cloud assignment.

Authorizations:
bearerAuth
path Parameters
cloudId
required
string
Example: 0Absd1

The ID of the cloud to unassign the VLAN from.

vlanId
required
string
Example: vl4nXy2Z9a

The ID of the VLAN resource to unassign.

Responses

Remove hardware node

Remove a hardware node from a cloud. The node is detached from the cloud and its inventory is cleaned up asynchronously.

Authorization

Requires the manage capability on the cloud resource. This limits access to users with the owner role on the cloud (resource owner, organization admin, or support agent).

Authorizations:
bearerAuth
path Parameters
cloudId
required
string
Example: 0Absd1

The Central resource ID of the cloud (hash ID format).

nodeUuid
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The UUID of the node to remove. This can be found in the nodes[].uuid field of the GET /v1/clouds/{cloudId}/stats response.

Responses

Response samples

Content type
application/json
{
  • "name": "US East - Production Cloud",
  • "description": "A Pre-prepared cloud generated automatically",
  • "label": "deploy-v2,pcc,pcc-3.0.7",
  • "cloud_uuid": "00000000-0000-0000-0000-000000000001",
  • "cloud_state": "RUNNING",
  • "cloud_hostname": "198.51.100.10",
  • "cloud_hosts": [
    ],
  • "external_vip_address": "198.51.100.10",
  • "internal_vip_address": "192.168.3.254",
  • "maintenance": false,
  • "creation_date": "2025-01-15T10:45:24.510406",
  • "pending_number": 0,
  • "pending_tasks": [
    ],
  • "pending_date": null,
  • "prevent_delete": false,
  • "nodes": [
    ],
  • "vlans": [
    ],
  • "keys": [
    ]
}

Configurations

Operations for managing custom deployment configurations.

A configuration is a reusable template that defines what operating system image and/or cloud-init user data should be applied to bare metal hardware during provisioning. Instead of specifying an OS image directly in each order, you can create a configuration once and reference it by ID when placing bare metal orders via the deployment_configuration field in order modifications.

Deployment Modes

Configurations currently support disk deployment mode:

Mode Required Fields Description
Disk image_source Traditional whole-disk image written directly to disk

Disk mode requires image_os_hash_algo and image_os_hash_value for image integrity verification. Valid hash algorithms are md5, sha256, and sha512.

Cloud-init user data (cloud_init.data) can be combined with disk deployment.

List configurations

Retrieve a list of all custom deployment configurations for your organization.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a configuration

Create a new custom deployment configuration with an OS image and/or cloud-init user data.

Deployment Mode

Set image_source in the fields object to a whole-disk image URL for disk deployment.

Validation Requirements

  • image_os_hash_algo and image_os_hash_value are required when image_source is set
  • image_os_hash_algo must be one of: md5, sha256, sha512
Authorizations:
bearerAuth
Request Body schema: application/json
required
label
required
string

A user-friendly name for the configuration.

description
string

A description of the configuration (optional).

object

Configuration fields containing deployment image and/or cloud-init settings. Disk deployments (image_source) require image_os_hash_algo and image_os_hash_value.

Responses

Request samples

Content type
application/json
Example

Deploy a whole-disk OS image directly to the node's disk. This is the most common deployment mode.

{}

Response samples

Content type
application/json
{
  • "id": "0a7Y8ABym5",
  • "label": "Ubuntu 22.04 Disk Deploy",
  • "description": "Standard whole-disk image deployment",
  • "fields": {},
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00"
}

Get a configuration by ID

Retrieve details of a specific deployment configuration by its ID.

Authorizations:
bearerAuth
path Parameters
configurationId
required
string
Example: 0a7Y8ABym5

The ID of the deployment configuration to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "0a7Y8ABym5",
  • "label": "Ubuntu 22.04 Disk Deploy",
  • "description": "Standard whole-disk image deployment",
  • "fields": {},
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00"
}

Update a configuration

Update an existing deployment configuration. The configuration ID must be included in the request body.

Only include the fields you want to change — the server merges incoming fields with existing fields before re-validating. This means you can update a single field (e.g., change image_source) without resending the entire configuration.

Authorizations:
bearerAuth
path Parameters
configurationId
required
string
Example: 0a7Y8ABym5

The ID of the deployment configuration to update.

Request Body schema: application/json
required
id
required
string

The ID of the deployment configuration to update. Must match the path parameter.

label
string

A user-friendly name for the configuration.

description
string

A description of the configuration.

object

Configuration fields to update. Only include fields you want to change. The server merges these with existing fields before validating.

Responses

Request samples

Content type
application/json
Example

Change the disk image URL on an existing disk deployment configuration. Hash fields and other settings are preserved.

{}

Response samples

Content type
application/json
{
  • "id": "0a7Y8ABym5",
  • "label": "Ubuntu 22.04 Disk Deploy",
  • "description": "Standard whole-disk image deployment",
  • "fields": {},
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00"
}

Delete a configuration

Delete a deployment configuration.

Authorizations:
bearerAuth
path Parameters
configurationId
required
string
Example: 0a7Y8ABym5

The ID of the deployment configuration to delete.

Responses

Deployment

Operations for deployment and provisioning related resources such as node images.

Get operating system images for a pod location

Retrieve a list of available operating system images for node deployment at a specific pod location. This endpoint does not require authentication.

path Parameters
pod_location
required
string (PodLocations)
Enum: "pod_1" "pod_2" "pod_3" "pod_5"
Example: pod_1

The unique datacenter identifier (e.g., "pod_1", "pod_2", etc.). Available locations can be retrieved from the inventory locations endpoint.

Responses

Response samples

Content type
application/json
{}

Inventory

Operations for retrieving inventory information such as available locations and availability.

Get available locations

Retrieve a list of available datacenter locations and their details.

Responses

Response samples

Content type
application/json
{
  • "locations": {
    }
}

Get inventory availability for a specific pod location

Retrieve current inventory availability information for a specific datacenter location. This endpoint shows available hardware SKUs and their counts.

path Parameters
pod_location
required
string
Example: pod_1

The unique datacenter identifier (e.g., "pod_1", "pod_2", etc.). Available locations can be retrieved from the inventory locations endpoint.

Responses

Response samples

Content type
application/json
{
  • "medium_v4": {
    },
  • "large_v4": {
    },
  • "timestamp": "2025-08-29T13:05:27+00:00",
  • "pod_location": "pod_1"
}

Get product catalog

Retrieve a catalog of available OpenMetal cloud products including hardware configurations and addon services.

This is a public endpoint that provides the complete product catalog, including:

  • Hardware products grouped by type (Small, Medium, Large, etc.)
  • Addon services categorized by functionality (memory, storage, ip_block, other)
  • Pricing information for all products and addons
  • Hardware specifications and capabilities

Note: This endpoint is publicly accessible and does not require authentication.

query Parameters
location
string (PodLocations)
Enum: "pod_1" "pod_2" "pod_3" "pod_5"
Example: location=pod_1

Datacenter location identifier to get location-specific pricing. Available locations can be retrieved from the inventory locations endpoint.

Responses

Response samples

Content type
application/json
{
  • "hardware": {
    },
  • "addons": {
    }
}

IP Blocks

Operations for managing IP Address Block (Prefix) resources for private clouds.

Get a list of IP Address Blocks

Retrieve a list of all IP Address Block (prefix) resources that have been created by you or organizations that you are a member of.

IP Address Blocks are network prefixes (CIDR blocks) used for IP address allocation in private clouds.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new IP Address Block

Create a new IP Address Block (network prefix) resource in a specified datacenter location.

IP Address Blocks can be created with a specific CIDR or by specifying a prefix length to automatically allocate from available address space.

Important: An IP Address Block must be assigned to a VLAN for use. Create the appropriate internal or routed VLAN to assign this IP Address Block to. IP Blocks can be assigned to a VLAN during IP Block creation (via central_vlan_id) or after creation in a separate request.

Authorizations:
bearerAuth
Request Body schema: application/json
required
label
required
string

A user-friendly name for the IP Address Block.

description
string

A description of the IP Address Block (optional).

required
object

Responses

Request samples

Content type
application/json
Example

Create a private IP Address Block with a specific CIDR block.

{
  • "label": "Private IP Address Block",
  • "description": "IP Block Description",
  • "fields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "pf3xY7z2W9",
  • "type": "prefixes",
  • "label": "production-ips",
  • "description": "IP range for production servers",
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00",
  • "is_active": true,
  • "created_by": "o6aQxVGezj",
  • "fields": {
    }
}

Get an IP Address Block by ID

Retrieve details of a specific IP Address Block resource by its ID.

Authorizations:
bearerAuth
path Parameters
prefixId
required
string
Example: pf3xY7z2W9

The ID of the IP Address Block resource to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "pf3xY7z2W9",
  • "type": "prefixes",
  • "label": "production-ips",
  • "description": "IP range for production servers",
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00",
  • "is_active": true,
  • "created_by": "o6aQxVGezj",
  • "fields": {
    }
}

Update an IP Address Block

Update an existing IP Address Block resource.

Authorizations:
bearerAuth
path Parameters
prefixId
required
string
Example: pf3xY7z2W9

The ID of the IP Address Block resource to update.

Request Body schema: application/json
required
label
string

A user-friendly name for the IP Address Block.

description
string

A description of the IP Address Block.

Responses

Request samples

Content type
application/json
{
  • "label": "production-ips",
  • "description": "IP range for production servers"
}

Response samples

Content type
application/json
{
  • "id": "pf3xY7z2W9",
  • "type": "prefixes",
  • "label": "production-ips",
  • "description": "IP range for production servers",
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00",
  • "is_active": true,
  • "created_by": "o6aQxVGezj",
  • "fields": {
    }
}

Get prefix with IP addresses

Retrieve a prefix by its resource ID, including all child IP addresses.

This endpoint returns the full prefix details from the network infrastructure, including:

  • Prefix metadata (CIDR, type, usage, status)
  • All IP addresses within the prefix (ip_addrs array)
  • Child prefixes if any exist (children array)
Authorizations:
bearerAuth
path Parameters
prefixId
required
string
Example: pr3fixAbc123

The resource ID of the prefix to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": 456,
  • "cidr": "192.168.1.0/24",
  • "description": "Production network",
  • "prefix_type": "routed",
  • "usage": "custom",
  • "status": "ACTIVE",
  • "managed_addressing": "off",
  • "vlan_id": 123,
  • "parent_id": 100,
  • "children": [
    ],
  • "ip_addrs": [
    ]
}

Create an IP address within a prefix

Create an IP address within a specified prefix resource.

If no specific IP address is provided in the request body, an available IP will be automatically assigned from the prefix.

Authorizations:
bearerAuth
path Parameters
prefixId
required
string
Example: pr3fixAbc123

The resource ID of the prefix to create the IP address in.

Request Body schema: application/json
required
ip
string

The specific IP address to create. If omitted, an available IP will be automatically assigned.

label
string

A label for the IP address.

assigned_host
string

The hostname or identifier of the host this IP is assigned to.

Responses

Request samples

Content type
application/json
{
  • "ip": "192.168.1.10",
  • "label": "web-server-01",
  • "assigned_host": "webserver.example.com"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "ip": "192.168.1.10",
  • "label": "web-server-01",
  • "assigned_host": "webserver.example.com"
}

Update an IP address

Update an existing IP address within a prefix.

To unassign an IP address from a host, pass an empty string ("") as the assigned_host value. A host's main IP cannot be reassigned or unassigned.

Authorizations:
bearerAuth
path Parameters
prefixId
required
string
Example: pr3fixAbc123

The resource ID of the prefix containing the IP address.

ipId
required
integer
Example: 12345

The numeric ID of the IP address to update.

Request Body schema: application/json
required
label
string

A label for the IP address.

assigned_host
string

The hostname or identifier of the host this IP is assigned to. Pass empty string to unassign.

Responses

Request samples

Content type
application/json
{
  • "label": "web-server-01-updated",
  • "assigned_host": "webserver-new.example.com"
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "ip": "192.168.1.10",
  • "label": "web-server-01",
  • "assigned_host": "webserver.example.com"
}

Delete an IP address

Delete an IP address.

Authorizations:
bearerAuth
path Parameters
prefixId
required
string
Example: pr3fixAbc123

The resource ID of the prefix containing the IP address.

ipId
required
integer
Example: 12345

The numeric ID of the IP address to delete.

Responses

Delete IP Address Block (prefix)

Permanently delete a IP Address Block (prefix)

Validation Requirements

⚠️ A IP Address Block (prefix) cannot be deleted if:

  • Non-user-created resource: Only user-created IP Address Blocks (prefixes) (created_from = "user") can be deleted by regular users. Internal resources created by OpenMetal require support agent access.
  • Assigned to VLAN: IP Block (Prefix) must be unassigned from all VLANs first using the unassign endpoint.
  • IP addresses in use: No IP addresses from this IP Block (prefix) can be assigned to nodes.
  1. Check for active IP assignments: Query GET /v1/deployment/network/prefix/{prefixId} to verify no IPs from this prefix are assigned to nodes
  2. Unassign from VLAN (if applicable): Use DELETE /v1/vlans/{vlan_id}/prefixes/{prefix_id} if prefix is currently assigned to a VLAN
  3. Delete prefix: Execute DELETE request once all dependencies are cleared
Authorizations:
bearerAuth
path Parameters
prefix_id
required
string
Example: AbC123XyZ

The Central resource ID of the prefix (hash ID format)

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Assign Prefix to VLAN

Associate an existing prefix with a VLAN, enabling routing through the VLAN.

Validation Rules

  • Ownership mismatch: Resources must have the same owner
  • Location mismatch: Resources must be in the same pod_location
  • Existing VLAN assignment: IP Block (prefix) cannot already be assigned to another VLAN
Authorizations:
bearerAuth
path Parameters
vlan_id
required
string
Example: XyZ789AbC

The Central resource ID of the VLAN

prefix_id
required
string
Example: AbC123XyZ

The Central resource ID of the prefix

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Unassign Prefix from VLAN

Remove the association between a prefix and a VLAN without deleting either resource.

Validation Requirements

⚠️ Unassignment restrictions:

  • Non-user-created VLAN: Only user-created VLANs (created_from = "user") can be modified by regular users. System generated VLANs require support agent access.

Important Notes

  • The IP Block (prefix) remains active and can be reassigned to another VLAN
  • The VLAN remains active and can have other IP Blocks (prefixes) assigned
  • No billing changes occur
  • Only user-created VLANs can be modified by regular users
Authorizations:
bearerAuth
path Parameters
vlan_id
required
string
Example: XyZ789AbC

The Central resource ID of the VLAN

prefix_id
required
string
Example: AbC123XyZ

The Central resource ID of the prefix

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Nodes

Operations for managing and interacting with individual nodes that are assigned to a cloud, including IPMI console access and power management.

Change the power state of the node.

Change power state. Options are "power on", "power off", or "rebooting".

Authorizations:
bearerAuth
path Parameters
cloudId
required
string

The ID of the cloud that owns the node.

nodeUuid
required
string

The UUID of the node to change the power state. This UUID can be found in the cloud hardware information.

Request Body schema: application/json
required
power_state
string

The new power state of the node. Options are "power on", "power off", or "rebooting".

Responses

Request samples

Content type
application/json
{
  • "power_state": "power on"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "power_state": "power on",
  • "node_uuid": "0000000-0000-00-00000"
}

Generate IPMI Session via HTML5

Generates an IPMI (Intelligent Platform Management Interface) console session and retrieves a URL for accessing the HTML5-based web console for remote management of a node. This provides browser-based KVM access for server remote management without requiring Java or additional software installation.

Recommended Method: The HTML5 console is the recommended method for accessing IPMI as it works directly in modern web browsers.

For help using the web console, see Accessing IPMI on Central Dashboard.

Authorizations:
bearerAuth
path Parameters
cloudId
required
string
Example: 0Absd1

The ID of the cloud that owns the node.

inventoryUuid
required
string <uuid>
Example: 0000000-0000-00-00000

UUID v4 string identifying the inventory item (node). This can be found in the cloud hardware information.

Responses

Response samples

Content type
application/json
{
  • "url": "https://<Node UUID>.ipmi.pod-4.flexmetal.net:<PORT>/redfish/<SESSION-ID>.IKVM"
}

Generate IPMI Session via JNLP

Generates an IPMI (Intelligent Platform Management Interface) console session and downloads a Java Network Launch Protocol (JNLP) file for launching a Java-based KVM console to access a node's remote management interface.

Prerequisites:

  • Java Runtime Environment (JRE) must be installed on the client machine
  • Download available from www.java.com/en/download

Usage: Once downloaded, the JNLP file can be launched with Java Web Start to open the KVM console.

For additional assistance, visit the IPMI KVM documentation.

Authorizations:
bearerAuth
path Parameters
cloudId
required
string
Example: 0Absd1

The ID of the cloud that owns the node.

inventoryUuid
required
string <uuid>
Example: 0000000-0000-00-00000

UUID v4 string identifying the inventory item (node). This can be found in the cloud hardware information.

Responses

Orders

Operations for managing orders.

Creating a New Server Order

Follow this workflow to create and track a new server order:

  1. Check Inventory Availability - Use the GET /v2/inventory/{pod_location}/availability endpoint to verify that your desired hardware SKU is available in the target datacenter location.

  2. Create the Order - Submit a POST /v1/orders request with your desired configuration (hardware SKU, location, type, and quantity).

  3. Monitor Order Status - Use GET /v1/orders/{orderId} to retrieve the order and check the clouds_deployed field. Each item in the clouds_deployed array contains:

    • id - The cloud resource identifier
    • provisioning_status - Current provisioning state with progression: pending → in_progress → awaiting_setup → complete
    • If errors occur during provisioning, the cloud may enter a manual_setup state requiring support intervention

  4. Query Cloud Details - Once you have the cloud ID from clouds_deployed[].id, use the GET /v1/clouds/{cloudId} endpoint to retrieve detailed information about the provisioned cloud, including its provision_status and other configuration details.

Get a list of orders

Retrieve a list of all orders that have been created by you or organizations that you are a member of.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new order

Create a new order for baremetal servers or private cloud products running OpenStack.

Deploying a New Cloud

By default, when no cloud_id is specified on an order item, a new cloud will be deployed with the ordered hardware.

Adding Nodes to an Existing Cloud

To add hardware nodes to an existing cloud, include the cloud_id field in the item configuration. The new node will be provisioned and added to the specified cloud's infrastructure, with billing attached to the existing cloud.

  • The cloud_id must reference a cloud owned by your organization
  • The location must match the cloud's datacenter location
  • The type must match the cloud's type (baremetal or pcc)
  • The cloud must be fully provisioned (provision_status: "complete") before nodes can be added
Authorizations:
bearerAuth
Request Body schema: application/json
required
label
required
string

A user-friendly name for the order.

description
string

A brief description of the order (optional).

required
object (OrderFields)

The product selections and configuration options for an order.

Responses

Request samples

Content type
application/json
Example

A baremetal order with Operating System specified.

{
  • "label": "Baremetal Medium V4 with Ubuntu 22.04 LTS",
  • "description": "Baremetal Medium V4 cluster in Ashburn, VA with 1 node to run production workloads.",
  • "fields": {
    }
}

Response samples

Content type
application/json
{
  • "label": "Test PCC Order v2 with pending tasks check",
  • "description": "Baremetal Medium V4 cluster in Ashburn, VA with 1 node to run production workloads.",
  • "fields": {
    },
  • "id": "PGZYNxBpg3",
  • "type": "orders",
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00",
  • "is_active": true,
  • "created_by": "o6aQxVGezj",
  • "access": {
    }
}

Get an order by ID

Retrieve a specific order by its ID to view details and check the status of the order.

Authorizations:
bearerAuth
path Parameters
orderId
required
string

The ID of the order to retrieve.

Responses

Response samples

Content type
application/json
{
  • "label": "Test PCC Order v2 with pending tasks check",
  • "description": "Baremetal Medium V4 cluster in Ashburn, VA with 1 node to run production workloads.",
  • "fields": {
    },
  • "id": "PGZYNxBpg3",
  • "type": "orders",
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00",
  • "is_active": true,
  • "created_by": "o6aQxVGezj",
  • "access": {
    }
}

SSH Keys

Operations for managing SSH public keys.

SSH public keys can be stored and managed for use during bare metal provisioning. Keys are validated on create/update and a SHA256 fingerprint is automatically computed from the key data.

Supported key types: ssh-rsa, ssh-dss, ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, sk-ssh-ed25519@openssh.com, sk-ecdsa-sha2-nistp256@openssh.com

List public keys

Retrieve a list of all active SSH public keys the authenticated user has access to (owned, shared via team, or organization).

Returns an empty array [] when the user has no public keys.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a public key

Create a new SSH public key resource.

The key is validated on creation and a SHA256 fingerprint is automatically computed from the key data. The fingerprint cannot be set directly.

Supported key types: ssh-rsa, ssh-dss, ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, sk-ssh-ed25519@openssh.com, sk-ecdsa-sha2-nistp256@openssh.com

Authorizations:
bearerAuth
Request Body schema: application/json
required
label
required
string

Display name for the key.

description
string

Optional description.

required
object

Responses

Request samples

Content type
application/json
Example

Create a public key with an ED25519 SSH key.

{
  • "label": "My SSH Key",
  • "description": "Work laptop key",
  • "fields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "OvZyEGQwWj",
  • "type": "public-keys",
  • "label": "My SSH Key",
  • "description": "Work laptop key",
  • "fields": {
    },
  • "created_at": "2026-03-02T20:57:40+00:00",
  • "updated_at": "2026-03-02T20:57:40+00:00",
  • "created_by": "nDG3DAKMOr",
  • "created_by_name": ""
}

Get a public key

Retrieve details of a specific SSH public key by its ID.

Authorizations:
bearerAuth
path Parameters
publicKeyId
required
string
Example: OvZyEGQwWj

The hashed resource ID of the public key.

Responses

Response samples

Content type
application/json
{
  • "id": "OvZyEGQwWj",
  • "type": "public-keys",
  • "label": "My SSH Key",
  • "description": "Work laptop key",
  • "fields": {
    },
  • "created_at": "2026-03-02T20:57:40+00:00",
  • "updated_at": "2026-03-02T20:57:40+00:00",
  • "created_by": "nDG3DAKMOr",
  • "created_by_name": "",
  • "access": {
    }
}

Update a public key

Update an existing SSH public key. All fields are optional — only provided fields are changed.

When key_data is updated, the fingerprint is automatically recomputed. The fingerprint field cannot be set directly.

Authorizations:
bearerAuth
path Parameters
publicKeyId
required
string
Example: OvZyEGQwWj

The hashed resource ID of the public key to update.

Request Body schema: application/json
required
label
string

Updated display name for the key.

description
string

Updated description.

object

Responses

Request samples

Content type
application/json
Example

Update just the display name of the key.

{
  • "label": "My Updated SSH Key"
}

Response samples

Content type
application/json
{
  • "id": "OvZyEGQwWj",
  • "type": "public-keys",
  • "label": "My SSH Key",
  • "description": "Work laptop key",
  • "fields": {
    },
  • "created_at": "2026-03-02T20:57:40+00:00",
  • "updated_at": "2026-03-02T20:57:40+00:00",
  • "created_by": "nDG3DAKMOr",
  • "created_by_name": "",
  • "access": {
    }
}

Delete a public key

Delete an SSH public key. This performs a soft delete (sets is_active to false).

Authorizations:
bearerAuth
path Parameters
publicKeyId
required
string
Example: OvZyEGQwWj

The hashed resource ID of the public key to delete.

Responses

VLANs

Operations for managing Virtual LAN (VLAN) resources for private clouds.

Get a list of VLANs

Retrieve a list of all VLAN resources that have been created by you or organizations that you are a member of.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new VLAN

Create a new VLAN resource in a specified datacenter location.

VLANs can optionally be assigned to a cloud and/or have an IP Address Block assigned during creation.

Authorizations:
bearerAuth
Request Body schema: application/json
required
label
required
string

A user-friendly name for the VLAN.

description
string

A description of the VLAN (optional).

required
object

Responses

Request samples

Content type
application/json
Example

Create a VLAN in a specific location without cloud assignment.

{
  • "label": "my-custom-vlan",
  • "description": "Custom VLAN for development environment",
  • "fields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "vl4nXy2Z9a",
  • "type": "vlans",
  • "label": "production-vlan",
  • "description": "VLAN for production workloads",
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00",
  • "is_active": true,
  • "created_by": "o6aQxVGezj",
  • "fields": {
    }
}

Get a VLAN by ID

Retrieve details of a specific VLAN resource by its ID.

Authorizations:
bearerAuth
path Parameters
vlanId
required
string
Example: vl4nXy2Z9a

The ID of the VLAN resource to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "vl4nXy2Z9a",
  • "type": "vlans",
  • "label": "production-vlan",
  • "description": "VLAN for production workloads",
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00",
  • "is_active": true,
  • "created_by": "o6aQxVGezj",
  • "fields": {
    }
}

Update a VLAN

Update an existing VLAN resource.

Note: Only user-created VLANs can be modified. System-reserved VLANs (control, compute, storage, tunnel, octavia, inventory, provider) cannot be altered.

Authorizations:
bearerAuth
path Parameters
vlanId
required
string
Example: vl4nXy2Z9a

The ID of the VLAN resource to update.

Request Body schema: application/json
required
label
string

A user-friendly name for the VLAN.

description
string

A description of the VLAN.

Responses

Request samples

Content type
application/json
{
  • "label": "production-vlan",
  • "description": "VLAN for production workloads"
}

Response samples

Content type
application/json
{
  • "id": "vl4nXy2Z9a",
  • "type": "vlans",
  • "label": "production-vlan",
  • "description": "VLAN for production workloads",
  • "created_at": "2025-08-27T20:05:56+00:00",
  • "updated_at": "2025-08-27T20:05:56+00:00",
  • "is_active": true,
  • "created_by": "o6aQxVGezj",
  • "fields": {
    }
}

Assign an IP Address Block to a VLAN

Assign an existing IP Address Block (prefix) resource to a VLAN.

Requirements:

  • Both resources must be in the same datacenter location
  • Both resources must be owned by the same organization
  • The IP Address Block must not already be assigned to another VLAN
Authorizations:
bearerAuth
path Parameters
vlanId
required
string
Example: vl4nXy2Z9a

The UUID of the VLAN resource.

prefixId
required
string
Example: pf3xY7z2W9

The ID of the IP Address Block (prefix) resource to assign.

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Delete VLAN

Permanently delete a VLAN.

Validation Requirements

⚠️ A VLAN cannot be deleted if:

  • Non-user-created resource: Only user-created VLANs (created_from = "user") can be deleted by regular users. Internal resources created by OpenMetal require support agent access.
  • In Use by Cloud or Node: VLAN is assigned to a cloud or node resource
  • Child IP Blocks: This VLAN has one or more IP Blocks assigned to it

Reserved VLANs (Cannot be Deleted)

The following system VLANs cannot be deleted:

  • control - Control plane networking
  • compute - Compute node networking
  • storage - Storage networking
  • tunnel - Tunnel networking
  • octavia - Load balancer networking
  • inventory - Inventory management
  • provider - Provider networking
  1. Review resource relationships: Query GET /v1/vlans/{vlan_id} to see all associated child IP Blocks(prefixes) or parent cloud resource assignments
  2. Check parent cloud assignments: Verify VLAN has no parent cloud resource assignments
  3. Check child IP Blocks: Verify VLAN has no child IP Blocks assigned to it
  4. Delete VLAN: Execute DELETE request
Authorizations:
bearerAuth
path Parameters
vlan_id
required
string
Example: XyZ789AbC

The Central resource ID of the VLAN (hash ID format)

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Assign Prefix to VLAN

Associate an existing prefix with a VLAN, enabling routing through the VLAN.

Validation Rules

  • Ownership mismatch: Resources must have the same owner
  • Location mismatch: Resources must be in the same pod_location
  • Existing VLAN assignment: IP Block (prefix) cannot already be assigned to another VLAN
Authorizations:
bearerAuth
path Parameters
vlan_id
required
string
Example: XyZ789AbC

The Central resource ID of the VLAN

prefix_id
required
string
Example: AbC123XyZ

The Central resource ID of the prefix

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}

Unassign Prefix from VLAN

Remove the association between a prefix and a VLAN without deleting either resource.

Validation Requirements

⚠️ Unassignment restrictions:

  • Non-user-created VLAN: Only user-created VLANs (created_from = "user") can be modified by regular users. System generated VLANs require support agent access.

Important Notes

  • The IP Block (prefix) remains active and can be reassigned to another VLAN
  • The VLAN remains active and can have other IP Blocks (prefixes) assigned
  • No billing changes occur
  • Only user-created VLANs can be modified by regular users
Authorizations:
bearerAuth
path Parameters
vlan_id
required
string
Example: XyZ789AbC

The Central resource ID of the VLAN

prefix_id
required
string
Example: AbC123XyZ

The Central resource ID of the prefix

Responses

Response samples

Content type
application/json
{
  • "status": "success"
}