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-omc.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": {
    }
}

Get hardware information

Get hardware information for a specific cloud. This includes current power state of all nodes.

Authorizations:
bearerAuth
path Parameters
cloudId
required
string

The ID of the cloud to retrieve.

Responses

Response samples

Content type
application/json
{
  • "cloud_state": "RUNNING",
  • "cloud_uuid": "0000000-0000-00-00000",
  • "nodes": [
    ]
}

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

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

Orders

Operations for managing orders.

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

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

Create a new order

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

Authorizations:
bearerAuth
path Parameters
accountId
required
string
Example: mWLBVbB7Eq

The ID of the organization account to create the order for.

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