API documentation

Params

Param name	Description
thin optional	Only list ID and name of hosts Validations: Must be one of: `true`, `false`, `1`, `0`.
hostgroup_id optional	ID of host group Validations: Must be a String
location_id optional	ID of location Validations: Must be a String
organization_id optional	ID of organization Validations: Must be a String
environment_id optional	ID of environment Validations: Must be a String
include optional	Array of extra information types to include Validations: Must be one of: `parameters`, `all_parameters`.
search optional	filter results Validations: Must be a String
order optional	Sort field and order, eg. ‘id DESC’ Validations: Must be a String
page optional	Page number, starting at 1 Validations: Must be a number.
per_page optional	Number of results per page to return Validations: Must be a number.

Search fields

Field name	Type	Possible values
architecture	string
boot_time	datetime
build		true, false
class	string
comment	text
compute_resource	string
compute_resource_id	integer
config_group	string
created_at	datetime
domain	string
domain_id	integer
environment	string
facts	string
global_status		ok, warning, error
has_ip	string
has_mac	string
hostgroup	string
hostgroup_fullname	string
hostgroup_id	integer
hostgroup_name	string
hostgroup_title	string
image	string
installed_at	datetime
ip	string
last_report	datetime
location	string
location_id	integer
mac	string
managed		true, false
model	string
name	string
organization	string
organization_id	integer
origin	string
os	string
os_description	string
os_id	integer
os_major	string
os_minor	string
os_title	string
owner	string
owner_id	integer
owner_type	string
params	string
params_name	string
parent_hostgroup	string
puppet_ca	string
puppet_proxy_id	integer
puppetmaster	string
realm	string
realm_id	integer
smart_proxy	string
status.applied	integer
status.enabled		true, false
status.failed	integer
status.failed_restarts	integer
status.interesting		true, false
status.pending	integer
status.restarted	integer
status.skipped	integer
subnet	string
subnet.name	text
subnet6	string
subnet6.name	text
user.firstname	string
user.lastname	string
user.login	string
user.mail	string
usergroup	string
usergroup.name	string
uuid	string

Examples

GET /api/hosts/6
200
{
  "ip": null,
  "ip6": null,
  "environment_id": null,
  "environment_name": null,
  "last_report": null,
  "mac": null,
  "realm_id": null,
  "realm_name": null,
  "sp_mac": null,
  "sp_ip": null,
  "sp_name": null,
  "domain_id": null,
  "domain_name": null,
  "architecture_id": null,
  "architecture_name": null,
  "operatingsystem_id": null,
  "operatingsystem_name": null,
  "subnet_id": null,
  "subnet_name": null,
  "subnet6_id": null,
  "subnet6_name": null,
  "sp_subnet_id": null,
  "ptable_id": null,
  "ptable_name": null,
  "medium_id": null,
  "medium_name": null,
  "pxe_loader": null,
  "build": false,
  "comment": null,
  "disk": null,
  "installed_at": null,
  "model_id": null,
  "hostgroup_id": null,
  "owner_id": 135138680,
  "owner_name": "Admin User",
  "owner_type": "User",
  "enabled": true,
  "managed": false,
  "use_image": null,
  "image_file": "",
  "uuid": null,
  "compute_resource_id": null,
  "compute_resource_name": null,
  "compute_profile_id": null,
  "compute_profile_name": null,
  "capabilities": [
    "build"
  ],
  "provision_method": "build",
  "certname": "host10",
  "image_id": null,
  "image_name": null,
  "created_at": "2020-03-11 07:54:42 UTC",
  "updated_at": "2020-03-11 07:54:42 UTC",
  "last_compile": null,
  "global_status": 0,
  "global_status_label": "OK",
  "uptime_seconds": null,
  "organization_id": 447626438,
  "organization_name": "Organization 1",
  "location_id": 255093256,
  "location_name": "Location 1",
  "puppet_status": 0,
  "model_name": null,
  "name": "host10",
  "id": 6,
  "puppet_proxy_id": null,
  "puppet_proxy_name": null,
  "puppet_ca_proxy_id": null,
  "puppet_ca_proxy_name": null,
  "puppet_proxy": null,
  "puppet_ca_proxy": null,
  "hostgroup_name": null,
  "hostgroup_title": null,
  "parameters": [
    {
      "priority": 70,
      "created_at": "2020-03-11 07:54:42 UTC",
      "updated_at": "2020-03-11 07:54:42 UTC",
      "id": 767575241,
      "name": "foo",
      "parameter_type": "string",
      "value": 42
    }
  ],
  "all_parameters": [
    {
      "priority": 70,
      "created_at": "2020-03-11 07:54:42 UTC",
      "updated_at": "2020-03-11 07:54:42 UTC",
      "id": 767575241,
      "name": "foo",
      "parameter_type": "string",
      "value": 42
    },
    {
      "priority": null,
      "created_at": "2020-03-11 07:54:36 UTC",
      "updated_at": "2020-03-11 07:54:36 UTC",
      "id": 513706444,
      "name": "loc_param",
      "parameter_type": "string",
      "value": "abc"
    },
    {
      "priority": null,
      "created_at": "2020-03-11 07:54:36 UTC",
      "updated_at": "2020-03-11 07:54:36 UTC",
      "id": 32400255,
      "name": "org_param",
      "parameter_type": "string",
      "value": "xyz"
    },
    {
      "priority": null,
      "created_at": "2020-03-11 07:54:36 UTC",
      "updated_at": "2020-03-11 07:54:36 UTC",
      "id": 636252244,
      "name": "test",
      "parameter_type": "string",
      "value": "myvalue"
    }
  ],
  "interfaces": [
    {
      "subnet_id": null,
      "subnet_name": null,
      "subnet6_id": null,
      "subnet6_name": null,
      "domain_id": null,
      "domain_name": null,
      "created_at": "2020-03-11 07:54:42 UTC",
      "updated_at": "2020-03-11 07:54:42 UTC",
      "managed": true,
      "identifier": null,
      "id": 6,
      "name": "host10",
      "ip": null,
      "ip6": null,
      "mac": null,
      "mtu": null,
      "fqdn": "host10",
      "primary": true,
      "provision": true,
      "type": "interface",
      "virtual": false
    }
  ],
  "puppetclasses": [],
  "config_groups": [],
  "all_puppetclasses": [],
  "permissions": {
    "view_hosts": true,
    "create_hosts": true,
    "edit_hosts": true,
    "destroy_hosts": true,
    "build_hosts": true,
    "power_hosts": true,
    "console_hosts": true,
    "ipmi_boot_hosts": true,
    "puppetrun_hosts": true
  }
}

Params

Param name	Description
location_id optional	Set the current location context for the request Validations: Must be a Integer
organization_id optional	Set the current organization context for the request Validations: Must be a Integer
id required	Validations: Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, dot(.), space, underscore(_), hypen(-) with no leading or trailing space.
show_hidden_parameters optional	Display hidden parameter values Validations: Must be one of: `true`, `false`, `1`, `0`.

Examples

POST /api/hosts
{
  "host": {
    "id": null,
    "name": "host14",
    "last_compile": null,
    "last_report": null,
    "updated_at": null,
    "created_at": null,
    "root_pass": "xybxa6JUkz63w",
    "architecture_id": null,
    "operatingsystem_id": null,
    "environment_id": null,
    "ptable_id": null,
    "medium_id": null,
    "build": false,
    "comment": null,
    "disk": null,
    "installed_at": null,
    "model_id": null,
    "hostgroup_id": null,
    "owner_id": null,
    "owner_type": null,
    "enabled": true,
    "puppet_ca_proxy_id": null,
    "managed": false,
    "use_image": null,
    "image_file": null,
    "uuid": null,
    "compute_resource_id": null,
    "puppet_proxy_id": null,
    "certname": null,
    "image_id": null,
    "organization_id": 447626438,
    "location_id": 255093256,
    "type": "Host::Managed",
    "otp": null,
    "realm_id": null,
    "compute_profile_id": null,
    "provision_method": null,
    "grub_pass": "",
    "global_status": 0,
    "lookup_value_matcher": null,
    "pxe_loader": null,
    "initiated_at": null,
    "build_errors": null,
    "parameters": [
      {
        "name": "foo",
        "value": 42,
        "parameter_type": "integer"
      }
    ]
  }
}
201
{
  "ip": null,
  "ip6": null,
  "environment_id": null,
  "environment_name": null,
  "last_report": null,
  "mac": null,
  "realm_id": null,
  "realm_name": null,
  "sp_mac": null,
  "sp_ip": null,
  "sp_name": null,
  "domain_id": null,
  "domain_name": null,
  "architecture_id": null,
  "architecture_name": null,
  "operatingsystem_id": null,
  "operatingsystem_name": null,
  "subnet_id": null,
  "subnet_name": null,
  "subnet6_id": null,
  "subnet6_name": null,
  "sp_subnet_id": null,
  "ptable_id": null,
  "ptable_name": null,
  "medium_id": null,
  "medium_name": null,
  "pxe_loader": null,
  "build": false,
  "comment": null,
  "disk": null,
  "installed_at": null,
  "model_id": null,
  "hostgroup_id": null,
  "owner_id": 135138680,
  "owner_name": "Admin User",
  "owner_type": "User",
  "enabled": true,
  "managed": false,
  "use_image": null,
  "image_file": "",
  "uuid": null,
  "compute_resource_id": null,
  "compute_resource_name": null,
  "compute_profile_id": null,
  "compute_profile_name": null,
  "capabilities": [
    "build"
  ],
  "provision_method": "build",
  "certname": "host14",
  "image_id": null,
  "image_name": null,
  "created_at": "2020-03-11 07:54:43 UTC",
  "updated_at": "2020-03-11 07:54:43 UTC",
  "last_compile": null,
  "global_status": 0,
  "global_status_label": "OK",
  "uptime_seconds": null,
  "organization_id": 447626438,
  "organization_name": "Organization 1",
  "location_id": 255093256,
  "location_name": "Location 1",
  "puppet_status": 0,
  "model_name": null,
  "name": "host14",
  "id": 10,
  "puppet_proxy_id": null,
  "puppet_proxy_name": null,
  "puppet_ca_proxy_id": null,
  "puppet_ca_proxy_name": null,
  "puppet_proxy": null,
  "puppet_ca_proxy": null,
  "hostgroup_name": null,
  "hostgroup_title": null,
  "parameters": [],
  "all_parameters": [
    {
      "priority": null,
      "created_at": "2020-03-11 07:54:36 UTC",
      "updated_at": "2020-03-11 07:54:36 UTC",
      "id": 513706444,
      "name": "loc_param",
      "parameter_type": "string",
      "value": "abc"
    },
    {
      "priority": null,
      "created_at": "2020-03-11 07:54:36 UTC",
      "updated_at": "2020-03-11 07:54:36 UTC",
      "id": 32400255,
      "name": "org_param",
      "parameter_type": "string",
      "value": "xyz"
    },
    {
      "priority": null,
      "created_at": "2020-03-11 07:54:36 UTC",
      "updated_at": "2020-03-11 07:54:36 UTC",
      "id": 636252244,
      "name": "test",
      "parameter_type": "string",
      "value": "myvalue"
    }
  ],
  "interfaces": [
    {
      "subnet_id": null,
      "subnet_name": null,
      "subnet6_id": null,
      "subnet6_name": null,
      "domain_id": null,
      "domain_name": null,
      "created_at": "2020-03-11 07:54:43 UTC",
      "updated_at": "2020-03-11 07:54:43 UTC",
      "managed": true,
      "identifier": null,
      "id": 10,
      "name": "host14",
      "ip": null,
      "ip6": null,
      "mac": null,
      "mtu": null,
      "fqdn": "host14",
      "primary": true,
      "provision": true,
      "type": "interface",
      "virtual": false
    }
  ],
  "puppetclasses": [],
  "config_groups": [],
  "all_puppetclasses": [],
  "permissions": {
    "view_hosts": true,
    "create_hosts": true,
    "edit_hosts": true,
    "destroy_hosts": true,
    "build_hosts": true,
    "power_hosts": true,
    "console_hosts": true,
    "ipmi_boot_hosts": true,
    "puppetrun_hosts": true
  }
}

Params

Param name	Description
location_id optional	Set the current location context for the request Validations: Must be a Integer
organization_id optional	Set the current organization context for the request Validations: Must be a Integer
host required	Validations: Must be a Hash
host[name] required	Validations: Must be a String
host[location_id] required	Validations: Must be a number.
host[organization_id] required	Validations: Must be a number.
host[environment_id] optional , nil allowed	required if host is managed and value is not inherited from host group Validations: Must be a String
host[ip] optional , nil allowed	not required if using a subnet with DHCP proxy Validations: Must be a String
host[mac] optional , nil allowed	required for managed host that is bare metal, not required if it’s a virtual machine Validations: Must be a String
host[architecture_id] optional , nil allowed	required if host is managed and value is not inherited from host group Validations: Must be a number.
host[domain_id] optional , nil allowed	required if host is managed and value is not inherited from host group Validations: Must be a number.
host[realm_id] optional , nil allowed	Validations: Must be a number.
host[puppet_proxy_id] optional , nil allowed	Puppet proxy ID Validations: Must be a number.
host[puppet_ca_proxy_id] optional , nil allowed	Puppet CA proxy ID Validations: Must be a number.
host[puppetclass_ids] optional , nil allowed	Validations: Must be an array of any type
host[config_group_ids] optional , nil allowed	IDs of associated config groups Validations: Must be an array of any type
host[operatingsystem_id] optional , nil allowed	required if host is managed and value is not inherited from host group Validations: Must be a String
host[medium_id] optional , nil allowed	required if not imaged based provisioning and host is managed and value is not inherited from host group Validations: Must be a String
host[pxe_loader] optional , nil allowed	DHCP filename option (Grub2/PXELinux by default) Validations: Must be one of: `None`, `PXELinux BIOS`, `PXELinux UEFI`, `Grub UEFI`, `Grub2 BIOS`, `Grub2 ELF`, `Grub2 UEFI`, `Grub2 UEFI SecureBoot`, `Grub2 UEFI HTTP`, `Grub2 UEFI HTTPS`, `Grub2 UEFI HTTPS SecureBoot`, `iPXE Embedded`, `iPXE UEFI HTTP`, `iPXE Chain BIOS`, `iPXE Chain UEFI`.
host[ptable_id] optional , nil allowed	required if host is managed and custom partition has not been defined Validations: Must be a number.
host[subnet_id] optional , nil allowed	required if host is managed and value is not inherited from host group Validations: Must be a number.
host[compute_resource_id] optional , nil allowed	nil means host is bare metal Validations: Must be a number.
host[root_pass] optional , nil allowed	required if host is managed and value is not inherited from host group or default password in settings Validations: Must be a String
host[model_id] optional , nil allowed	Validations: Must be a number.
host[hostgroup_id] optional , nil allowed	Validations: Must be a number.
host[owner_id] optional , nil allowed	Validations: Must be a number.
host[owner_type] optional , nil allowed	Host’s owner type Validations: Must be one of: `User`, `Usergroup`.
host[image_id] optional , nil allowed	Validations: Must be a number.
host[host_parameters_attributes] optional , nil allowed	Host’s parameters (array or indexed hash) Validations: Must be an Array of nested elements
host[host_parameters_attributes][name] required	Name of the parameter Validations: Must be a String
host[host_parameters_attributes][value] required	Parameter value Validations: Must be a String
host[host_parameters_attributes][parameter_type] optional , nil allowed	Type of value Validations: Must be one of: `string`, `boolean`, `integer`, `real`, `array`, `hash`, `yaml`, `json`.
host[host_parameters_attributes][hidden_value] optional , nil allowed	Validations: Must be one of: `true`, `false`, `1`, `0`.
host[build] optional , nil allowed	Validations: Must be one of: `true`, `false`, `1`, `0`.
host[enabled] optional , nil allowed	Include this host within Foreman reporting Validations: Must be one of: `true`, `false`, `1`, `0`.
host[provision_method] optional , nil allowed	The method used to provision the host. Validations: Must be one of: `build`, `image`.
host[managed] optional , nil allowed	True/False flag whether a host is managed or unmanaged. Note: this value also determines whether several parameters are required or not Validations: Must be one of: `true`, `false`, `1`, `0`.
host[progress_report_id] optional , nil allowed	UUID to track orchestration tasks status, GET /api/orchestration/:UUID/tasks Validations: Must be a String
host[comment] optional , nil allowed	Additional information about this host Validations: Must be a String
host[capabilities] optional , nil allowed	Validations: Must be a String
host[compute_profile_id] optional , nil allowed	Validations: Must be a number.
host[interfaces_attributes] optional , nil allowed	Host’s network interfaces. Validations: Must be an Array of nested elements
host[interfaces_attributes][mac] optional , nil allowed	MAC address of interface. Required for managed interfaces on bare metal. Validations: Must be a String
host[interfaces_attributes][ip] optional , nil allowed	IPv4 address of interface Validations: Must be a String
host[interfaces_attributes][ip6] optional , nil allowed	IPv6 address of interface Validations: Must be a String
host[interfaces_attributes][type] optional , nil allowed	Interface type, e.g. bmc. Default is interface Validations: Must be one of: `interface`, `bmc`, `bond`, `bridge`.
host[interfaces_attributes][name] optional , nil allowed	Interface’s DNS name Validations: Must be a String
host[interfaces_attributes][subnet_id] optional , nil allowed	Foreman subnet ID of IPv4 interface Validations: Must be a number.
host[interfaces_attributes][subnet6_id] optional , nil allowed	Foreman subnet ID of IPv6 interface Validations: Must be a number.
host[interfaces_attributes][domain_id] optional , nil allowed	Foreman domain ID of interface. Required for primary interfaces on managed hosts. Validations: Must be a number.
host[interfaces_attributes][identifier] optional , nil allowed	Device identifier, e.g. eth0 or eth1.1 Validations: Must be a String
host[interfaces_attributes][managed] optional , nil allowed	Should this interface be managed via DHCP and DNS smart proxy and should it be configured during provisioning? Validations: Must be one of: `true`, `false`, `1`, `0`.
host[interfaces_attributes][primary] optional , nil allowed	Should this interface be used for constructing the FQDN of the host? Each managed hosts needs to have one primary interface. Validations: Must be one of: `true`, `false`, `1`, `0`.
host[interfaces_attributes][provision] optional , nil allowed	Should this interface be used for TFTP of PXELinux (or SSH for image-based hosts)? Each managed hosts needs to have one provision interface. Validations: Must be one of: `true`, `false`, `1`, `0`.
host[interfaces_attributes][username] optional , nil allowed	Only for BMC interfaces. Validations: Must be a String
host[interfaces_attributes][password] optional , nil allowed	Only for BMC interfaces. Validations: Must be a String
host[interfaces_attributes][provider] optional , nil allowed	Interface provider, e.g. IPMI. Only for BMC interfaces. Validations: Must be one of: `IPMI`, `SSH`.
host[interfaces_attributes][virtual] optional , nil allowed	Alias or VLAN device Validations: Must be one of: `true`, `false`, `1`, `0`.
host[interfaces_attributes][tag] optional , nil allowed	VLAN tag, this attribute has precedence over the subnet VLAN ID. Only for virtual interfaces. Validations: Must be a String
host[interfaces_attributes][mtu] optional , nil allowed	MTU, this attribute has precedence over the subnet MTU. Validations: Must be a Integer
host[interfaces_attributes][attached_to] optional , nil allowed	Identifier of the interface to which this interface belongs, e.g. eth1. Only for virtual interfaces. Validations: Must be a String
host[interfaces_attributes][mode] optional , nil allowed	Bond mode of the interface, e.g. balance-rr. Only for bond interfaces. Validations: Must be one of: `balance-rr`, `active-backup`, `balance-xor`, `broadcast`, `802.3ad`, `balance-tlb`, `balance-alb`.
host[interfaces_attributes][attached_devices] optional , nil allowed	Identifiers of attached interfaces, e.g. `['eth1', 'eth2']`. For bond interfaces those are the slaves. Only for bond and bridges interfaces. Validations: Must be an array of any type
host[interfaces_attributes][bond_options] optional , nil allowed	Space separated options, e.g. miimon=100. Only for bond interfaces. Validations: Must be a String
host[interfaces_attributes][compute_attributes] optional , nil allowed	Additional compute resource specific attributes for the interface. Validations: Must be a Hash
host[compute_attributes] optional , nil allowed	Additional compute resource specific attributes. Validations: Must be a Hash

Params

Param name	Description
location_id optional	Set the current location context for the request Validations: Must be a Integer
organization_id optional	Set the current organization context for the request Validations: Must be a Integer
id required	Validations: Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, space, underscore(_), hypen(-) with no leading or trailing space.
host required	Validations: Must be a Hash
host[name] optional	Validations: Must be a String
host[location_id] optional	Validations: Must be a number.
host[organization_id] optional	Validations: Must be a number.
host[environment_id] optional , nil allowed	required if host is managed and value is not inherited from host group Validations: Must be a String
host[ip] optional , nil allowed	not required if using a subnet with DHCP proxy Validations: Must be a String
host[mac] optional , nil allowed	required for managed host that is bare metal, not required if it’s a virtual machine Validations: Must be a String
host[architecture_id] optional , nil allowed	required if host is managed and value is not inherited from host group Validations: Must be a number.
host[domain_id] optional , nil allowed	required if host is managed and value is not inherited from host group Validations: Must be a number.
host[realm_id] optional , nil allowed	Validations: Must be a number.
host[puppet_proxy_id] optional , nil allowed	Puppet proxy ID Validations: Must be a number.
host[puppet_ca_proxy_id] optional , nil allowed	Puppet CA proxy ID Validations: Must be a number.
host[puppetclass_ids] optional , nil allowed	Validations: Must be an array of any type
host[config_group_ids] optional , nil allowed	IDs of associated config groups Validations: Must be an array of any type
host[operatingsystem_id] optional , nil allowed	required if host is managed and value is not inherited from host group Validations: Must be a String
host[medium_id] optional , nil allowed	required if not imaged based provisioning and host is managed and value is not inherited from host group Validations: Must be a String
host[pxe_loader] optional , nil allowed	DHCP filename option (Grub2/PXELinux by default) Validations: Must be one of: `None`, `PXELinux BIOS`, `PXELinux UEFI`, `Grub UEFI`, `Grub2 BIOS`, `Grub2 ELF`, `Grub2 UEFI`, `Grub2 UEFI SecureBoot`, `Grub2 UEFI HTTP`, `Grub2 UEFI HTTPS`, `Grub2 UEFI HTTPS SecureBoot`, `iPXE Embedded`, `iPXE UEFI HTTP`, `iPXE Chain BIOS`, `iPXE Chain UEFI`.
host[ptable_id] optional , nil allowed	required if host is managed and custom partition has not been defined Validations: Must be a number.
host[subnet_id] optional , nil allowed	required if host is managed and value is not inherited from host group Validations: Must be a number.
host[compute_resource_id] optional , nil allowed	nil means host is bare metal Validations: Must be a number.
host[root_pass] optional , nil allowed	required if host is managed and value is not inherited from host group or default password in settings Validations: Must be a String
host[model_id] optional , nil allowed	Validations: Must be a number.
host[hostgroup_id] optional , nil allowed	Validations: Must be a number.
host[owner_id] optional , nil allowed	Validations: Must be a number.
host[owner_type] optional , nil allowed	Host’s owner type Validations: Must be one of: `User`, `Usergroup`.
host[image_id] optional , nil allowed	Validations: Must be a number.
host[host_parameters_attributes] optional , nil allowed	Host’s parameters (array or indexed hash) Validations: Must be an Array of nested elements
host[host_parameters_attributes][name] optional	Name of the parameter Validations: Must be a String
host[host_parameters_attributes][value] optional	Parameter value Validations: Must be a String
host[host_parameters_attributes][parameter_type] optional , nil allowed	Type of value Validations: Must be one of: `string`, `boolean`, `integer`, `real`, `array`, `hash`, `yaml`, `json`.
host[host_parameters_attributes][hidden_value] optional , nil allowed	Validations: Must be one of: `true`, `false`, `1`, `0`.
host[build] optional , nil allowed	Validations: Must be one of: `true`, `false`, `1`, `0`.
host[enabled] optional , nil allowed	Include this host within Foreman reporting Validations: Must be one of: `true`, `false`, `1`, `0`.
host[provision_method] optional , nil allowed	The method used to provision the host. Validations: Must be one of: `build`, `image`.
host[managed] optional , nil allowed	True/False flag whether a host is managed or unmanaged. Note: this value also determines whether several parameters are required or not Validations: Must be one of: `true`, `false`, `1`, `0`.
host[progress_report_id] optional , nil allowed	UUID to track orchestration tasks status, GET /api/orchestration/:UUID/tasks Validations: Must be a String
host[comment] optional , nil allowed	Additional information about this host Validations: Must be a String
host[capabilities] optional , nil allowed	Validations: Must be a String
host[compute_profile_id] optional , nil allowed	Validations: Must be a number.
host[interfaces_attributes] optional , nil allowed	Host’s network interfaces. Validations: Must be an Array of nested elements
host[interfaces_attributes][mac] optional , nil allowed	MAC address of interface. Required for managed interfaces on bare metal. Validations: Must be a String
host[interfaces_attributes][ip] optional , nil allowed	IPv4 address of interface Validations: Must be a String
host[interfaces_attributes][ip6] optional , nil allowed	IPv6 address of interface Validations: Must be a String
host[interfaces_attributes][type] optional , nil allowed	Interface type, e.g. bmc. Default is interface Validations: Must be one of: `interface`, `bmc`, `bond`, `bridge`.
host[interfaces_attributes][name] optional , nil allowed	Interface’s DNS name Validations: Must be a String
host[interfaces_attributes][subnet_id] optional , nil allowed	Foreman subnet ID of IPv4 interface Validations: Must be a number.
host[interfaces_attributes][subnet6_id] optional , nil allowed	Foreman subnet ID of IPv6 interface Validations: Must be a number.
host[interfaces_attributes][domain_id] optional , nil allowed	Foreman domain ID of interface. Required for primary interfaces on managed hosts. Validations: Must be a number.
host[interfaces_attributes][identifier] optional , nil allowed	Device identifier, e.g. eth0 or eth1.1 Validations: Must be a String
host[interfaces_attributes][managed] optional , nil allowed	Should this interface be managed via DHCP and DNS smart proxy and should it be configured during provisioning? Validations: Must be one of: `true`, `false`, `1`, `0`.
host[interfaces_attributes][primary] optional , nil allowed	Should this interface be used for constructing the FQDN of the host? Each managed hosts needs to have one primary interface. Validations: Must be one of: `true`, `false`, `1`, `0`.
host[interfaces_attributes][provision] optional , nil allowed	Should this interface be used for TFTP of PXELinux (or SSH for image-based hosts)? Each managed hosts needs to have one provision interface. Validations: Must be one of: `true`, `false`, `1`, `0`.
host[interfaces_attributes][username] optional , nil allowed	Only for BMC interfaces. Validations: Must be a String
host[interfaces_attributes][password] optional , nil allowed	Only for BMC interfaces. Validations: Must be a String
host[interfaces_attributes][provider] optional , nil allowed	Interface provider, e.g. IPMI. Only for BMC interfaces. Validations: Must be one of: `IPMI`, `SSH`.
host[interfaces_attributes][virtual] optional , nil allowed	Alias or VLAN device Validations: Must be one of: `true`, `false`, `1`, `0`.
host[interfaces_attributes][tag] optional , nil allowed	VLAN tag, this attribute has precedence over the subnet VLAN ID. Only for virtual interfaces. Validations: Must be a String
host[interfaces_attributes][mtu] optional , nil allowed	MTU, this attribute has precedence over the subnet MTU. Validations: Must be a Integer
host[interfaces_attributes][attached_to] optional , nil allowed	Identifier of the interface to which this interface belongs, e.g. eth1. Only for virtual interfaces. Validations: Must be a String
host[interfaces_attributes][mode] optional , nil allowed	Bond mode of the interface, e.g. balance-rr. Only for bond interfaces. Validations: Must be one of: `balance-rr`, `active-backup`, `balance-xor`, `broadcast`, `802.3ad`, `balance-tlb`, `balance-alb`.
host[interfaces_attributes][attached_devices] optional , nil allowed	Identifiers of attached interfaces, e.g. `['eth1', 'eth2']`. For bond interfaces those are the slaves. Only for bond and bridges interfaces. Validations: Must be an array of any type
host[interfaces_attributes][bond_options] optional , nil allowed	Space separated options, e.g. miimon=100. Only for bond interfaces. Validations: Must be a String
host[interfaces_attributes][compute_attributes] optional , nil allowed	Additional compute resource specific attributes for the interface. Validations: Must be a Hash
host[compute_attributes] optional , nil allowed	Additional compute resource specific attributes. Validations: Must be a Hash

Params

Param name

Description

location_id
optional

Set the current location context for the request

Validations:

Must be a Integer

organization_id
optional

Set the current organization context for the request

Validations:

Must be a Integer

id
required

Validations:

Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, space, underscore(_), hypen(-) with no leading or trailing space.

Examples

GET /api/hosts/host782/enc
200
{
  "data": {
    "parameters": {
      "foreman_subnets": [],
      "foreman_interfaces": [
        {
          "ip": null,
          "ip6": null,
          "mac": null,
          "name": "host782",
          "attrs": {},
          "virtual": false,
          "link": true,
          "identifier": null,
          "managed": true,
          "primary": true,
          "provision": true,
          "subnet": null,
          "subnet6": null,
          "tag": null,
          "attached_to": null,
          "type": "Interface"
        }
      ],
      "location": "Location 1",
      "location_title": "Location 1",
      "organization": "Organization 1",
      "organization_title": "Organization 1",
      "owner_name": "Admin User",
      "owner_email": "admin@someware.com",
      "ssh_authorized_keys": [],
      "foreman_users": {
        "secret_admin": {
          "firstname": "Admin",
          "lastname": "User",
          "mail": "admin@someware.com",
          "description": null,
          "fullname": "Admin User",
          "name": "secret_admin",
          "ssh_authorized_keys": []
        }
      },
      "root_pw": "$5$uLoZGHzYcd1lEBPr$Ow4e9oRmN4/9E3y4rQFN8w1CsoATETimT3HLKRsMgP2",
      "foreman_config_groups": [],
      "puppetmaster": "",
      "foreman_env": "environment152",
      "test": "myvalue",
      "org_param": "xyz",
      "loc_param": "abc"
    },
    "classes": [
      "class30"
    ],
    "environment": "environment152"
  }
}

Params

Param name

Description

location_id
optional

Set the current location context for the request

Validations:

Must be a Integer

organization_id
optional

Set the current organization context for the request

Validations:

Must be a Integer

id
required

Validations:

Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, dot(.), space, underscore(_), hypen(-) with no leading or trailing space.

Returns string representing a host status of a given type

Examples

GET /api/hosts/host823/status/global
200
{
  "status_label": "OK",
  "status": 0
}

Params

Param name	Description
location_id optional	Set the current location context for the request Validations: Must be a Integer
organization_id optional	Set the current organization context for the request Validations: Must be a Integer
id required	Validations: Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, dot(.), space, underscore(_), hypen(-) with no leading or trailing space.
type required	status type, can be one of * global * configuration * build Validations: Must be one of: `HostStatus::Global`, `configuration`, `build`.

Return the host’s compute attributes that can be used to create a clone of this VM

Examples

GET /api/hosts/host825/vm_compute_attributes
200
{
  "cpus": 4,
  "memory": null
}

Params

Param name

Description

location_id
optional

Set the current location context for the request

Validations:

Must be a Integer

organization_id
optional

Set the current organization context for the request

Validations:

Must be a Integer

id
required

Validations:

Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, dot(.), space, underscore(_), hypen(-) with no leading or trailing space.

Examples

PUT /api/hosts/host804/disassociate
{
  "host": {}
}
200
{
  "ip": null,
  "ip6": null,
  "environment_id": null,
  "environment_name": null,
  "last_report": null,
  "mac": null,
  "realm_id": null,
  "realm_name": null,
  "sp_mac": null,
  "sp_ip": null,
  "sp_name": null,
  "domain_id": null,
  "domain_name": null,
  "architecture_id": null,
  "architecture_name": null,
  "operatingsystem_id": null,
  "operatingsystem_name": null,
  "subnet_id": null,
  "subnet_name": null,
  "subnet6_id": null,
  "subnet6_name": null,
  "sp_subnet_id": null,
  "ptable_id": null,
  "ptable_name": null,
  "medium_id": null,
  "medium_name": null,
  "pxe_loader": null,
  "build": false,
  "comment": null,
  "disk": null,
  "installed_at": null,
  "model_id": null,
  "hostgroup_id": null,
  "owner_id": 135138680,
  "owner_name": "Admin User",
  "owner_type": "User",
  "enabled": true,
  "managed": false,
  "use_image": null,
  "image_file": "",
  "uuid": null,
  "compute_resource_id": null,
  "compute_resource_name": null,
  "compute_profile_id": null,
  "compute_profile_name": null,
  "capabilities": [
    "build"
  ],
  "provision_method": "build",
  "certname": "host804",
  "image_id": null,
  "image_name": null,
  "created_at": "2019-11-07 08:40:15 UTC",
  "updated_at": "2019-11-07 08:40:15 UTC",
  "last_compile": null,
  "global_status": 0,
  "global_status_label": "OK",
  "uptime_seconds": null,
  "organization_id": 447626438,
  "organization_name": "Organization 1",
  "location_id": 255093256,
  "location_name": "Location 1",
  "puppet_status": 0,
  "model_name": null,
  "name": "host804",
  "id": 120,
  "puppet_proxy_id": null,
  "puppet_proxy_name": null,
  "puppet_ca_proxy_id": null,
  "puppet_ca_proxy_name": null,
  "puppet_proxy": null,
  "puppet_ca_proxy": null,
  "hostgroup_name": null,
  "hostgroup_title": null,
  "interfaces": [
    {
      "subnet_id": null,
      "subnet_name": null,
      "subnet6_id": null,
      "subnet6_name": null,
      "domain_id": null,
      "domain_name": null,
      "created_at": "2019-11-07 08:40:15 UTC",
      "updated_at": "2019-11-07 08:40:15 UTC",
      "managed": true,
      "identifier": null,
      "id": 128,
      "name": "host804",
      "ip": null,
      "ip6": null,
      "mac": null,
      "mtu": null,
      "fqdn": "host804",
      "primary": true,
      "provision": true,
      "type": "interface",
      "virtual": false
    }
  ],
  "puppetclasses": [],
  "config_groups": [],
  "all_puppetclasses": [],
  "permissions": {
    "view_hosts": true,
    "create_hosts": true,
    "edit_hosts": true,
    "destroy_hosts": true,
    "build_hosts": true,
    "power_hosts": true,
    "console_hosts": true,
    "ipmi_boot_hosts": true,
    "puppetrun_hosts": true
  }
}

Params

Param name

Description

location_id
optional

Set the current location context for the request

Validations:

Must be a Integer

organization_id
optional

Set the current organization context for the request

Validations:

Must be a Integer

id
required

Validations:

Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, dot(.), space, underscore(_), hypen(-) with no leading or trailing space.

Examples

PUT /api/hosts/host644.example358.com/power
{
  "power_action": "status",
  "host": {}
}
200
{
  "power": "on"
}

Params

Param name	Description
location_id optional	Set the current location context for the request Validations: Must be a Integer
organization_id optional	Set the current organization context for the request Validations: Must be a Integer
id required	Validations: Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, dot(.), space, underscore(_), hypen(-) with no leading or trailing space.
power_action required	power action, valid actions are (on/start), (off/stop), (soft/reboot), (cycle/reset), (state/status) Validations: Must be a String

Examples

GET /api/hosts/43/power
200
{
  "id": 43,
  "state": "on",
  "title": "On"
}

Params

Param name

Description

location_id
optional

Set the current location context for the request

Validations:

Must be a Integer

organization_id
optional

Set the current organization context for the request

Validations:

Must be a Integer

id
required

Validations:

Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, dot(.), space, underscore(_), hypen(-) with no leading or trailing space.

Examples

PUT /api/hosts/host68.example24.com/boot
{
  "device": "bios",
  "host": {}
}
200
{
  "boot": "{\"action\":\"bios\",\"result\":true}"
}

Params

Param name	Description
location_id optional	Set the current location context for the request Validations: Must be a Integer
organization_id optional	Set the current organization context for the request Validations: Must be a Integer
id required	Validations: Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, dot(.), space, underscore(_), hypen(-) with no leading or trailing space.
device required	boot device, valid devices are disk, cdrom, pxe, bios Validations: Must be a String

Examples

POST /api/hosts/facts
{
  "name": "brslc022.brs.infineon.com",
  "facts": {
    "is_virtual": "true",
    "processorcount": "2",
    "serialnumber": "VMware-56 4d 15 06 72 86 a9 d3-8a 09 fc 27 5a cf 00 45",
    "kernel": "Linux",
    "virtual": "vmware",
    "_timestamp": "2010-02-16 12:52:38.163833 +01:00",
    "network_eth0": "172.29.205.0",
    "operatingsystemrelease": "4",
    "uniqueid": "1dac16cd",
    "hardwaremodel": "i686",
    "rubysitedir": "/usr/lib/site_ruby/1.8",
    "platform": "Linux_2.6_i386_all",
    "uptime_seconds": "3756",
    "lsbrelease": ":core-3.0-ia32:core-3.0-noarch:graphics-3.0-ia32:graphics-3.0-noarch",
    "memorysize": "1.45 GB",
    "gi": "4",
    "netmask_eth0": "255.255.255.128",
    "ipaddress": "172.29.205.22",
    "physicalprocessorcount": "0",
    "swapfree": "1.95 GB",
    "vmware": "virtual",
    "netmask": "255.255.255.128",
    "clientversion": "0.24.8",
    "fqdn": "brslc022.brs.infineon.com",
    "timezone": "GMT",
    "ps": "ps -ef",
    "kernelrelease": "2.6.9-89.0.16.ELsmp",
    "hardwareisa": "i686",
    "domain": "brs.infineon.com",
    "type": "Other",
    "kernelversion": "2.6.9",
    "id": "root",
    "lsbdistdescription": "Red Hat Enterprise Linux AS release 4 (Nahant Update 8)",
    "uptime_hours": "1",
    "lsbdistrelease": "4",
    "macaddress_eth0": "00:0C:29:CF:00:45",
    "manufacturer": "VMware, Inc.",
    "memoryfree": "1.39 GB",
    "selinux": "false",
    "gateway_if": "eth0",
    "lsbdistcodename": "NahantUpdate8",
    "sshrsakey": "AAAAB3NzaC1yc2EAAAABIwAAAIEAyj0XAKzx4WlNE8Vzj0ABBEHxqHr2H4AZZnabnQkYTOfz5kObXL+BvYqPONg2EqeUYCTNaFtQQPpJ4H+TM+GCJDNvFEKJTRd+cFoOuramf9LunWN/+ETreQ5V8KhKvdYTNw5blPBKiQz/XxSxcm7beo5QiBVr/lOM0u8YhGTLawk=",
    "uptime_days": "0",
    "interfaces": "eth0",
    "hostname": "brslc022",
    "graphcard": "VMware",
    "uptime": "1:02 hours",
    "processor0": "Intel(R) Xeon(R) CPU           X5460  @ 3.16GHz",
    "puppetversion": "0.24.8",
    "productname": "VMware Virtual Platform",
    "architecture": "i386",
    "gateway": "172.29.205.1",
    "rubyversion": "1.8.1",
    "environment": "brs_test",
    "path": "/usr/bin:/sbin:/bin:/usr/sbin:/opt/csw/bin",
    "swapsize": "1.95 GB",
    "ipaddress_eth0": "172.29.205.22",
    "facterversion": "1.5.7",
    "kernelmajversion": "2.6",
    "operatingsystem": "RedHat",
    "macaddress": "00:0C:29:CF:00:45",
    "processor1": "Intel(R) Xeon(R) CPU           X5460  @ 3.16GHz",
    "lsbmajdistrelease": "4",
    "sshdsakey": "AAAAB3NzaC1kc3MAAACBAIUasO2eEvlRHfcO8wMPfbo98YfgVsJj0qhUDSSoSa6xmYI8QWBDMoxf1h8INiDfrNQ5e4VreLQjt4/2Ex7OXoeB7C9Cg18/TlfZU+RTNMdsL85W5hQrrKoBm+ksMnxidkDC66ROq+pmxBTGDwwxg3ugF8eZnVSzCZ1FE605AsStAAAAFQCrr3s1cLQFRc6oZJAx3EZDxDraCQAAAIBqIqIvY7KtRsI+8y8E5MSZXpRRZxf0zqbraDxASwzImUr6ysEmpJsHbHyi6UePnF55tG/iZNM4bSNg/3qExK8So040byV71qN4HNT48nIh3cCS0z8oKLqvlCRJ+dOY1QMkE8ZLfOyF4A6ZOTuE8TTsGpvUIR0HyXkpoiIR9XcgzgAAAIA4nkedBQi+VA01NvWx27GGz5P3TTQ36yDODZdLmXoepQM1rPfKWvPFFd5MxgJumSU5BKhYUiQTOImcRlQcY5DA3dGbog1dOAKlWyeJn4WRHbYr+VNgR/HwBzHLMW4TXLt38ThmPv9TiLS1RvTdHuDm2oRTadNZOrmQz619kZejmw==",
    "lsbdistid": "RedHatEnterpriseAS"
  },
  "host": {
    "name": "brslc022.brs.infineon.com"
  }
}
201
{
  "id": 10,
  "name": "brslc022.brs.infineon.com",
  "last_compile": "2010-02-16T11:52:38.163Z",
  "last_report": null,
  "updated_at": "2020-03-11T07:55:24.816Z",
  "created_at": "2020-03-11T07:55:24.123Z",
  "root_pass": null,
  "architecture_id": 922134523,
  "operatingsystem_id": 1073012829,
  "environment_id": 687036938,
  "ptable_id": null,
  "medium_id": null,
  "build": false,
  "comment": null,
  "disk": null,
  "installed_at": null,
  "model_id": 980190965,
  "hostgroup_id": null,
  "owner_id": null,
  "owner_type": null,
  "enabled": true,
  "puppet_ca_proxy_id": null,
  "managed": false,
  "use_image": null,
  "image_file": "",
  "uuid": null,
  "compute_resource_id": null,
  "puppet_proxy_id": 814728799,
  "certname": "brslc022.brs.infineon.com",
  "image_id": null,
  "organization_id": 447626438,
  "location_id": 255093256,
  "otp": null,
  "realm_id": null,
  "compute_profile_id": null,
  "provision_method": "build",
  "grub_pass": "",
  "global_status": 0,
  "lookup_value_matcher": "fqdn=brslc022.brs.infineon.com",
  "pxe_loader": null,
  "initiated_at": null,
  "build_errors": null,
  "reported_data_attributes": {
    "id": 1,
    "host_id": 10,
    "boot_time": "2020-03-11T06:52:48.000Z",
    "created_at": "2020-03-11T07:55:24.780Z",
    "updated_at": "2020-03-11T07:55:24.780Z",
    "virtual": true,
    "sockets": 0,
    "cores": 2,
    "ram": null
  }
}

Params

Param name	Description
location_id optional	Set the current location context for the request Validations: Must be a Integer
organization_id optional	Set the current organization context for the request Validations: Must be a Integer
name required	hostname of the host Validations: Must be a String
facts required	hash containing the facts for the host Validations: Must be a Hash
certname optional	optional: certname of the host Validations: Must be a String
type optional	optional: the STI type of host to create Validations: Must be a String

Examples

POST /api/hosts/host381/rebuild_config
{
  "host": {}
}
422
{
  "message": "Configuration rebuild failed for: TFTP, DNS, and DHCP."
}

Params

Param name	Description
location_id optional	Set the current location context for the request Validations: Must be a Integer
organization_id optional	Set the current organization context for the request Validations: Must be a Integer
id required	Validations: Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, dot(.), space, underscore(_), hypen(-) with no leading or trailing space.
only optional	Limit rebuild steps, valid steps are DHCP, DNS, TFTP Validations: Must be an array of any type

Examples

GET /api/hosts/host784.example380.com/template/provitamin
404
{
  "message": "No template with kind provitamin for host784.example380.com"
}

Params

Param name	Description
location_id optional	Set the current location context for the request Validations: Must be a Integer
organization_id optional	Set the current organization context for the request Validations: Must be a Integer
id required	Validations: Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, dot(.), space, underscore(_), hypen(-) with no leading or trailing space.
kind required	Template kinds, available values: PXELinux, PXEGrub, PXEGrub2, iPXE, provision, finish, script, user_data, ZTP, POAP, cloud-init Validations: Must be a String

Hosts

GET /api/hosts List all hosts

GET /api/hostgroups/:hostgroup_id/hosts List all hosts for a host group

GET /api/locations/:location_id/hosts List hosts per location

GET /api/organizations/:organization_id/hosts List hosts per organization

GET /api/environments/:environment_id/hosts List hosts per environment

Params

Search fields

GET /api/hosts/:id Show a host

Examples

Params

POST /api/hosts Create a host

Examples

Params

PUT /api/hosts/:id Update a host

Params

DELETE /api/hosts/:id Delete a host

Params

GET /api/hosts/:id/enc Get ENC values of host

Examples

Params

GET /api/hosts/:id/status/:type Get status of host

Examples

Params

GET /api/hosts/:id/vm_compute_attributes Get vm attributes of host

Examples

Params

PUT /api/hosts/:id/disassociate Disassociate the host from a VM

Examples

Params

PUT /api/hosts/:id/power Run a power operation on host

Examples

Params

GET /api/hosts/:id/power Fetch the status of whether the host is powered on or not. Supported hosts are VMs and physical hosts with BMCs.

Examples

Params

PUT /api/hosts/:id/boot Boot host from specified device

Examples

Params

POST /api/hosts/facts Upload facts for a host, creating the host if required

Examples

Params

PUT /api/hosts/:id/rebuild_config Rebuild orchestration config

Examples

Params

GET /api/hosts/:id/template/:kind Preview rendered provisioning template content

Examples

Params

GET /api/hosts
List all hosts

GET /api/hostgroups/:hostgroup_id/hosts
List all hosts for a host group

GET /api/locations/:location_id/hosts
List hosts per location

GET /api/organizations/:organization_id/hosts
List hosts per organization

GET /api/environments/:environment_id/hosts
List hosts per environment

GET /api/hosts/:id
Show a host

POST /api/hosts
Create a host

PUT /api/hosts/:id
Update a host

DELETE /api/hosts/:id
Delete a host

GET /api/hosts/:id/enc
Get ENC values of host

GET /api/hosts/:id/status/:type
Get status of host

GET /api/hosts/:id/vm_compute_attributes
Get vm attributes of host

PUT /api/hosts/:id/disassociate
Disassociate the host from a VM

PUT /api/hosts/:id/power
Run a power operation on host

GET /api/hosts/:id/power
Fetch the status of whether the host is powered on or not. Supported hosts are VMs and physical hosts with BMCs.

PUT /api/hosts/:id/boot
Boot host from specified device

POST /api/hosts/facts
Upload facts for a host, creating the host if required

PUT /api/hosts/:id/rebuild_config
Rebuild orchestration config

GET /api/hosts/:id/template/:kind
Preview rendered provisioning template content