Brokkr API Documentation

Overview

This document provides details of the REST API for Hydra Host's Brokkr product. It outlines key functions that allow users to interact programmatically with the Brokkr system, including authenticating, viewing available and provisioned hosts, provisioning new hosts, deleting provisioned hosts, and handling SSH keys.

Postman Collection

The easiest way to try out the Brokkr API yourself is with the Postman collection. Take a look at the collection environment variables to set your session token.

Brokkr Postman Collection (Beta)

Authentication

All routes in the Brokkr API require a session token. This token can be passed to authenticated routes through the x-session-token header. All requests can be directed to https://thor.prod.hydra.host/api.

POST /login

Authenticates a user through email and password, returning a session token.

• Request

{
  "email": "first.last@hydrahost.com",
  "password": "Sup3rS3cur3Passw0rd!"
}

• Response (200)

{
  "sessionToken": "ory_st_GWogqWZ3SQtkA2XLsT1jQg7OW8hxcXb9"
}

• Response (401)

{
    "message": "Invalid authentication credentials."
}

Deployments

Manages a users provisioned machines, called deployments.

GET /deployments

Retrieves all of the users current deployments.

• Response (200)

{
	"deployments": [
		{
      "id": 814,
      "certname": "bbd20e59-bbd0-401b-a573-05f3dabfc9eb.dev.hydra.host",
      "mac": "52:54:00:00:00:a6",
      "operatingsystem_name": "Ubuntu 20.04",
      "global_status": 0,
      "global_status_label": "OK",
      "location_name": "phoenix",
      "created_at": "2023-07-26T16:25:49.677Z",
      "displayName": "Server A"
		}
	]
}

GET /deployments/{deploymentId}

Retrieves an individual deployment with more details.

• Response (200)

{
  "id": 814,
  "certname": "bbd20e59-bbd0-401b-a573-05f3dabfc9eb.dev.hydra.host",
  "domain_name": "dev.hydra.host",
  "ip6": "2606:a5c0:0:40:5054:ff:fe00:a6",
  "mac": "52:54:00:00:00:a6",
  "architecture_name": "x86_64",
  "operatingsystem_name": "Ubuntu 20.04",
  "pxe_loader": null,
  "location_name": "phoenix",
  "organization_name": "Hydra Host",
  "owner_name": "Thomas Juranek",
  "created_at": "2023-07-26T16:25:49.677Z"
}

• Response (401)

{
    "message": "Authenticated user is not authorized to view request resource."
}

DELETE /deployments/{deploymentId}

Deletes an individual deployment.

• Response (200)

{
    "id": 814
}

• Response (401)

{
    "message": "Authenticated user is not authorized to delete requested resource."
}

Inventory

Retrieves information about available inventory and allows provisioning of items.

GET /inventory

Retrieves all available inventory items.

• Response (200)

{
	"inventory": [
		{
			"ip": "10.15.0.110",
      "mac": "52:54:00:00:00:a5",
      "last_report": "2023-07-28T03:23:14.066Z",
      "subnet_id": 3,
      "subnet_name": "management-network (10.15.0.0/24)",
      "hardware_model_name": "Standard PC (Q35 + ICH9, 2009)",
      "memory": 1973,
      "disk_count": 2,
      "disks_size": 51201,
      "cpus": 2,
      "organization_id": 3,
      "organization_name": "Hydra Host",
      "location_id": 4,
      "location_name": "phoenix",
      "name": "h-5254000000a5",
      "id": 809
		}
	]
}

GET /inventory/{itemId}

Retrieves a single inventory item with more details.

• Response (200)

{
  "ip": "10.15.0.110",
  "mac": "52:54:00:00:00:a5",
  "last_report": "2023-07-28T03:23:14.066Z",
  "subnet_id": 3,
  "subnet_name": "management-network (10.15.0.0/24)",
  "hardware_model_name": "Standard PC (Q35 + ICH9, 2009)",
  "memory": 1973,
  "disk_count": 2,
  "disks_size": 51201,
  "cpus": 2,
  "organization_id": 3,
  "organization_name": "Hydra Host",
  "location_id": 4,
  "location_name": "phoenix",
  "name": "h-5254000000a5",
  "id": 809,
  "facts_hash": {
    "networking::ip6": "2606:a5c0:0:40:5054:ff:fe00:a5",
    "networking::mac": "52:54:00:00:00:a5",
    "os::architecture": "x86_64",
    "os::name": "CentOS"
  }
}

PUT /inventory/{inventoryId}

Provisions an inventory, turning it into a deployment.

• Request

enum OPERATING_SYSTEMS = {
	Debian: "4",
	Ubuntu18: "8",
	Ubuntu20: "2",
}

{
  "name": "Deployment Name",
  "operatingSystem": "2" // See above OPERATING_SYSTEMS
}

• Response (200)

{
    "id": 809
}

SSH Keys

Manages a users ssh keys for accessing their deployments.

POST /sshkeys

Creates a new ssh key.

• Request

{
	"name": "Mac Pro",
	"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCWt0/V4a7bOVjGj5PTa1CZzuMhv/+5S9dV1DhwTRABK9ydSlfWbc5kODHdGvgOrhLBPNFQmdmKRxu85ALDoTqKCiuxPfiJ+HyQX100kbmsfeuGbR83HHaEJ6I0aPQoLZF7XV0xP2Bt1HUfDpWjEzlNibGBBaat92uxoPkyfKuoRqqPXiYRuXifgT7GVL46JXTUX3FwQleTU70du72lprIQZCB0i7t0pYjNctDKGGeDBjDn1HGmXQvRnVNlWLjY/5NHHg7adDpIg13XaCSab1seOrGEk1Ecu/67jOgQe38VcdkMD+hcTuZZtUFnHq65xIMFQn572jsU18zwb+ke45n7"
}

• Response (200)

{
    "id": 67
}

GET /sshkeys

Gets all ssh keys.

• Response (200)

{
	"sshKeys": [
		{
			"created_at": "2023-07-28T03:48:30.251Z",
      "updated_at": "2023-07-28T03:48:30.251Z",
      "id": 67,
      "name": "Mac Pro",
      "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCWt0/V4a7bOVjGj5PTa1CZzuMhv/+5S9dV1DhwTRABK9ydSlfWbc5kODHdGvgOrhLBPNFQmdmKRxu85ALDoTqKCiuxPfiJ+HyQX100kbmsfeuGbR83HHaEJ6I0aPQoLZF7XV0xP2Bt1HUfDpWjEzlNibGBBaat92uxoPkyfKuoRqqPXiYRuXifgT7GVL46JXTUX3FwQleTU70du72lprIQZCB0i7t0pYjNctDKGGeDBjDn1HGmXQvRnVNlWLjY/5NHHg7adDpIg13XaCSab1seOrGEk1Ecu/67jOgQe38VcdkMD+hcTuZZtUFnHq65xIMFQn572jsU18zwb+ke45n7",
      "length": 2048,
      "fingerprint": "RSpoMfSX1MNzWq5hWeeWgVVVir+abdPz7ykLOL4xzX8="
		}
	]
}

GET /sshkeys/{sshkey_id}

Gets a single ssh key.

• Response (200)

{
  "created_at": "2023-07-28T03:48:30.251Z",
  "updated_at": "2023-07-28T03:48:30.251Z",
  "id": 67,
  "name": "Mac Pro",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCWt0/V4a7bOVjGj5PTa1CZzuMhv/+5S9dV1DhwTRABK9ydSlfWbc5kODHdGvgOrhLBPNFQmdmKRxu85ALDoTqKCiuxPfiJ+HyQX100kbmsfeuGbR83HHaEJ6I0aPQoLZF7XV0xP2Bt1HUfDpWjEzlNibGBBaat92uxoPkyfKuoRqqPXiYRuXifgT7GVL46JXTUX3FwQleTU70du72lprIQZCB0i7t0pYjNctDKGGeDBjDn1HGmXQvRnVNlWLjY/5NHHg7adDpIg13XaCSab1seOrGEk1Ecu/67jOgQe38VcdkMD+hcTuZZtUFnHq65xIMFQn572jsU18zwb+ke45n7",
  "length": 2048,
  "fingerprint": "RSpoMfSX1MNzWq5hWeeWgVVVir+abdPz7ykLOL4xzX8="
}

DELETE /sshkeys/{sshkey_id}

Deletes a single ssh key.

• Response (200)

{
    "id": 68
}