POST /api/hosts
Create a host

Examples

POST /api/locations/255093256/organizations/447626438/hosts
{
  "name": "contenthost.example.com",
  "root_pass": "$6$Sb6vKf6ImGgHcHOA$9fIJ0ET4eb2fFFjtz2DIRULEpfTa6R0JlNrwaFZQBgkevQbYI7E85V8wvasESlFloY.15XYV7Au8R939B08cz1",
  "operatingsystem_id": 1073012930,
  "build": false,
  "comment": "",
  "owner_id": 135138680,
  "owner_type": "User",
  "enabled": true,
  "managed": false,
  "type": "Host::Managed",
  "global_status": 0,
  "creator_id": 135138680,
  "content_facet_attributes": {
    "content_view_id": 30237652,
    "lifecycle_environment_id": 562075838,
    "content_view_environments": [
      "Library"
    ]
  },
  "host": {
    "content_facet_attributes": {
      "content_view_id": 30237652,
      "lifecycle_environment_id": 562075838,
      "content_view_environments": [
        "Library"
      ]
    },
    "build": false,
    "global_status": 0,
    "owner_id": 135138680,
    "owner_type": "User",
    "comment": "",
    "enabled": true,
    "managed": false,
    "name": "contenthost.example.com",
    "root_pass": "$6$Sb6vKf6ImGgHcHOA$9fIJ0ET4eb2fFFjtz2DIRULEpfTa6R0JlNrwaFZQBgkevQbYI7E85V8wvasESlFloY.15XYV7Au8R939B08cz1",
    "type": "Host::Managed",
    "operatingsystem_id": 1073012930
  }
}
201
{
  "ip": null,
  "ip6": 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": 1073012930,
  "operatingsystem_name": "operatingsystem74 74",
  "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": "",
  "disk": null,
  "initiated_at": null,
  "installed_at": null,
  "model_id": null,
  "hostgroup_id": null,
  "owner_id": 135138680,
  "owner_name": "Admin User",
  "owner_type": "User",
  "creator_id": 135138680,
  "creator": "Admin User",
  "enabled": true,
  "managed": false,
  "use_image": null,
  "image_file": "",
  "uuid": null,
  "rebuild_requires_poweroff": false,
  "compute_resource_id": null,
  "compute_resource_name": null,
  "compute_profile_id": null,
  "compute_profile_name": null,
  "capabilities": [
    "build"
  ],
  "provision_method": "build",
  "certname": "contenthost.example.com",
  "image_id": null,
  "image_name": null,
  "created_at": "2026-11-03 08:09:28 UTC",
  "updated_at": "2026-11-03 08:09:28 UTC",
  "last_compile": null,
  "global_status_label": "OK",
  "global_status_fulltext": [],
  "bmc_available": false,
  "organization_id": 447626438,
  "organization_name": "Organization 1",
  "location_id": 255093256,
  "location_name": "Location 1",
  "puppet_status": 0,
  "model_name": null,
  "build_status": 0,
  "build_status_label": "Installed",
  "execution_status": 2,
  "execution_status_label": "Unknown execution status",
  "name": "contenthost.example.com",
  "id": 980191236,
  "display_name": "contenthost.example.com",
  "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,
  "cockpit_url": null,
  "global_status": 0,
  "operatingsystem_icon": "/assets/icons16x16/stub/black-x-885521a80c50a4794a7f635601a00d7b1d8b379097e5e0840fbdc40253c74548.png",
  "compute_resource_provider": null,
  "hostgroup_name": null,
  "hostgroup_title": null,
  "parameters": [],
  "all_parameters": [
    {
      "priority": null,
      "created_at": "2026-11-03 08:05:52 UTC",
      "updated_at": "2026-11-03 08:05:52 UTC",
      "id": 513706444,
      "name": "loc_param",
      "parameter_type": "string",
      "associated_type": "location",
      "hidden_value?": false,
      "value": "abc"
    },
    {
      "priority": null,
      "created_at": "2026-11-03 08:05:52 UTC",
      "updated_at": "2026-11-03 08:05:52 UTC",
      "id": 32400255,
      "name": "org_param",
      "parameter_type": "string",
      "associated_type": "organization",
      "hidden_value?": false,
      "value": "xyz"
    },
    {
      "priority": null,
      "created_at": "2026-11-03 08:05:52 UTC",
      "updated_at": "2026-11-03 08:05:52 UTC",
      "id": 636252244,
      "name": "test",
      "parameter_type": "string",
      "associated_type": "global",
      "hidden_value?": false,
      "value": "myvalue"
    }
  ],
  "host_collections": [],
  "operatingsystem_family": null,
  "operatingsystem_major": "74",
  "interfaces": [
    {
      "subnet_id": null,
      "subnet_name": null,
      "subnet6_id": null,
      "subnet6_name": null,
      "domain_id": null,
      "domain_name": null,
      "host_id": 980191236,
      "host_name": "contenthost.example.com",
      "created_at": "2026-11-03 08:09:28 UTC",
      "updated_at": "2026-11-03 08:09:28 UTC",
      "managed": true,
      "identifier": null,
      "id": 353,
      "name": "contenthost.example.com",
      "ip": null,
      "ip6": null,
      "mac": null,
      "mtu": null,
      "fqdn": "contenthost.example.com",
      "primary": true,
      "provision": true,
      "type": "interface",
      "execution": true,
      "virtual": false
    }
  ],
  "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,
    "cockpit_hosts": true
  }
}

Params

Param name Description
location_id
optional

Set the current location context for the request

Validations:

  • Integer
organization_id
optional

Set the current organization context for the request

Validations:

  • Integer
host
required

Validations:

  • Hash
host[name]
required

Validations:

  • String
host[location_id]
required

Validations:

  • Must be a number.
host[organization_id]
required

Validations:

  • Must be a number.
host[ip]
optional , nil allowed

not required if using a subnet with DHCP proxy

Validations:

  • String
host[mac]
optional , nil allowed

required for managed host that is bare metal, not required if it’s a virtual machine

Validations:

  • 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[operatingsystem_id]
optional , nil allowed

required if host is managed and value is not inherited from host group

Validations:

  • Must be a number.
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:

  • String
host[pxe_loader]
optional , nil allowed

DHCP filename option (Grub2/PXELinux by default)

Validations:

  • Must be one of: None, PXELinux BIOS, PXELinux 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[uuid]
optional , nil allowed

UUID of a VM to import from a compute resource

Validations:

  • String
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:

  • String
host[model_id]
optional , nil allowed

Validations:

  • Must be a number.
host[hostgroup_id]
optional , nil allowed

ID of the host group. Note: Changing the host group will re-apply attributes inherited from the new host group, unless you explicitly override them again in the update request

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:

  • String
host[host_parameters_attributes][value]
required

Parameter value

Validations:

  • 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:

  • String
host[comment]
optional , nil allowed

Additional information about this host

Validations:

  • String
host[capabilities]
optional , nil allowed

Validations:

  • 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][id]
optional , nil allowed

ID of interface

Validations:

  • Must be a number.
host[interfaces_attributes][mac]
optional , nil allowed

MAC address of interface. Required for managed interfaces on bare metal.

Validations:

  • String
host[interfaces_attributes][ip]
optional , nil allowed

IPv4 address of interface

Validations:

  • String
host[interfaces_attributes][ip6]
optional , nil allowed

IPv6 address of interface

Validations:

  • 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:

  • 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:

  • 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:

  • String
host[interfaces_attributes][password]
optional , nil allowed

Only for BMC interfaces.

Validations:

  • String
host[interfaces_attributes][provider]
optional , nil allowed

Interface provider, e.g. IPMI. Only for BMC interfaces.

Validations:

  • Must be one of: IPMI, Redfish.
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:

  • String
host[interfaces_attributes][mtu]
optional , nil allowed

MTU, this attribute has precedence over the subnet MTU.

Validations:

  • 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:

  • 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:

  • String
host[interfaces_attributes][compute_attributes]
optional , nil allowed

Additional compute resource specific attributes for the interface.

Validations:

  • Hash
host[compute_attributes]
optional , nil allowed

Additional compute resource specific attributes.

Validations:

  • Hash
host[content_facet_attributes]
optional , nil allowed

Parameters for host’s content_facet facet

Validations:

  • Hash
host[content_facet_attributes][content_view_environments]
optional , nil allowed

Comma-separated list of content view environment labels to be associated with the host, in the format of ‘lifecycle_environment_label/content_view_label’. Ignored if content_view_environment_ids is specified. Requires allow_multiple_content_views setting to be on.

Validations:

  • Must be an array of any type
host[content_facet_attributes][content_view_environment_ids]
optional , nil allowed

Array of content view environment ids to be associated with the host. Requires allow_multiple_content_views setting to be on.

Validations:

  • Must be an array of any type
host[content_facet_attributes][content_source_id]
optional , nil allowed

Id of the smart proxy from which the host consumes content.

Validations:

  • Integer
host[content_facet_attributes][kickstart_repository_id]
optional , nil allowed

Repository Id associated with the kickstart repo used for provisioning

Validations:

  • Integer
host[subscription_facet_attributes]
optional , nil allowed

Parameters for host’s subscription_facet facet

Validations:

  • Hash
host[subscription_facet_attributes][release_version]
optional , nil allowed

Release version for this Host to use (7Server, 7.1, etc)

Validations:

  • String
host[subscription_facet_attributes][purpose_usage]
optional , nil allowed

Sets the system purpose usage

Validations:

  • String
host[subscription_facet_attributes][purpose_role]
optional , nil allowed

Sets the system purpose usage

Validations:

  • String
host[subscription_facet_attributes][service_level]
optional , nil allowed

Service level

Validations:

  • String
host[subscription_facet_attributes][hypervisor_guest_uuids]
optional , nil allowed

List of hypervisor guest uuids

Validations:

  • Must be an array of any type
host[subscription_facet_attributes][installed_products_attributes]
optional , nil allowed

List of products installed on the host

Validations:

  • Must be an Array of nested elements
host[subscription_facet_attributes][installed_products_attributes][product_id]
optional , nil allowed

Product id as listed from a host’s installed products, this is not the same product id as the products api returns

Validations:

  • String
host[subscription_facet_attributes][installed_products_attributes][product_name]
optional , nil allowed

Product name as listed from a host’s installed products

Validations:

  • String
host[subscription_facet_attributes][installed_products_attributes][arch]
optional , nil allowed

Product architecture

Validations:

  • String
host[subscription_facet_attributes][installed_products_attributes][version]
optional , nil allowed

Product version

Validations:

  • String
host[overwrite]
optional

Overwrite existing host (true by default)

Validations:

  • Must be one of: true, false, 1, 0.