History

Howtos ยป

API

Foreman 1.1 API

The documentation previously held on this page has been incorporated into the main theforeman.org web site. You can access it here:

NOTE: Starting with Foreman 1.1 API documentation can be auto generated on your installation using rake apipie:static, then access using /apidoc on your foreman instance. Auto generated Ruby binding and CLI are also available.

DEPRECATED: pre-Foreman 1.1 API

This API is officially deprecated as of Foreman 1.2. Please use the API under /api instead, see the Foreman API documentation for full details.

NOTE: Version of 0.1-6 or git develop branch are required to use the API

Foreman provides a REST API, communicating via JSON.

Please refer to this document for latest information about Foreman API.

Examples below are either via curl, perl, ruby rest_client

most pages can be browsed via adding the format option to the url (at least for get requests), i.e.

http://foreman/environments?format=json

Or using HTTP Headers

curl -H "Content-Type:application/json" -H "Accept:application/json"  http://foreman/hosts

Output is JSON formatted, in the last example expect a similar output:

[{"host":{"name":"pm1.local.net"}},{"host":{"name":"pm2.local.net"}}....]

List of API's

Path REST Type Description Example Input JSON
Architectures
/architectures POST Create a new Architecture {architecture : {"name":string}}
/architectures/NAME DELETE Delete a Architecture
/architectures GET Retrieve a list of Architectures
/architectures/NAME PUT Update an existing Architecture {architecture : {"name":string}}
Auth source ldaps
/auth_source_ldaps POST Create a new Auth source ldap {authsourceldap : {"account":string, "account_password":string, "attr_firstname":string, "attr_lastname":string, "attr_login":string, "attr_mail":string, "base_dn":string, "host":string, "name":string, "onthefly_register":string, "port":string, "tls":string, "type":string}}
/auth_source_ldaps/ID DELETE Delete a Auth source ldap
/auth_source_ldaps GET Retrieve a list of Auth source ldaps
/auth_source_ldaps/ID PUT Update an existing Auth source ldap {authsourceldap : {"account":string, "account_password":string, "attr_firstname":string, "attr_lastname":string, "attr_login":string, "attr_mail":string, "base_dn":string, "host":string, "name":string, "onthefly_register":string, "port":string, "tls":string, "type":string}}
Common parameters
/common_parameters POST Create a new Common parameter {commonparameter : {"name":string, "reference_id":int, "type":string, "value":string}}
/common_parameters/ID DELETE Delete a Common parameter
/common_parameters GET Retrieve a list of Common parameters
/common_parameters/ID PUT Update an existing Common parameter {commonparameter : {"name":string, "reference_id":int, "type":string, "value":string}}
Config templates
/config_templates POST Create a new Config template {config_template : {"hostgroup_id":int, "name":string, "snippet":boolean, "template":string, "template_kind_id":int}}
/config_templates/ID DELETE Delete a Config template
/config_templates GET Retrieve a list of Config templates
/config_templates/ID PUT Update an existing Config template {config_template : {"hostgroup_id":int, "name":string, "snippet":boolean, "template":string, "template_kind_id":int}}
/config_templates/build_pxe_default GET Deploy the default pxe template to all smart proxies.
Domains
/domains POST Create a new Domain {domain : {"dns_id":int, "fullname":string, "name":string}}
/domains/NAME DELETE Delete a Domain
/domains GET Retrieve a list of Domains
/domains/NAME PUT Update an existing Domain {domain : {"dns_id":int, "fullname":string, "name":string}}
Environments
/environments POST Create a new Environment {environment : {"name":string}}
/environments/NAME DELETE Delete a Environment
/environments GET Retrieve a list of Environments
/environments/NAME PUT Update an existing Environment {environment : {"name":string}}
Fact names
/facts GET Gets list of all fact names
/facts/<factname>/values GET return all hosts with the given factname and its value
Fact values
/fact_values POST Create a new Fact value {factvalue : {"fact_name_id":int, "host_id":int, "value":string}}
/fact_values GET Retrieve a list of Fact values
Hostgroups
/hostgroups POST Create a new Hostgroup {hostgroup : {"architecture_id":int, "environment_id":int, "medium_id":int, "name":string, "operatingsystem_id":int, "ptable_id":int, "puppetmaster":string, "root_pass":string}}
/hostgroups/ID DELETE Delete a Hostgroup
/hostgroups GET Retrieve a list of Hostgroups
/hostgroups/ID PUT Update an existing Hostgroup {hostgroup : {"architecture_id":int, "environment_id":int, "medium_id":int, "name":string, "operatingsystem_id":int, "ptable_id":int, "puppetmaster":string, "root_pass":string}}
Hosts
/hosts POST Create a new Host {host : {"architecture_id":int, "build":string, "comment":string, "disk":string, "domain_id":int, "enabled":string, "environment":string, "environment_id":int, "hostgroup_id":int, "installed_at":string, "ip":string, "last_compile":string, "last_freshcheck":string, "last_report":string, "mac":string, "medium_id":int, "model_id":int, "name":string, "operatingsystem_id":int, "owner_id":int, "owner_type":string, "ptable_id":int, "puppet_status":string, "puppetmaster":string, "root_pass":string, "serial":string, "source_file_id":int, "sp_ip":string, "sp_mac":string, "sp_name":string, "sp_subnet_id":int, "subnet_id":int}}
/hosts/FQDN DELETE Delete a Host
/hosts GET Retrieve a list of Hosts
/hosts/FQDN PUT Update an existing Host {host : {"architecture_id":int, "build":string, "comment":string, "disk":string, "domain_id":int, "enabled":string, "environment":string, "environment_id":int, "hostgroup_id":int, "installed_at":string, "ip":string, "last_compile":string, "last_freshcheck":string, "last_report":string, "mac":string, "medium_id":int, "model_id":int, "name":string, "operatingsystem_id":int, "owner_id":int, "owner_type":string, "ptable_id":int, "puppet_status":string, "puppetmaster":string, "root_pass":string, "serial":string, "source_file_id":int, "sp_ip":string, "sp_mac":string, "sp_name":string, "sp_subnet_id":int, "subnet_id":int}}
/hosts/errors GET List of hosts in error state(only name)
/hosts/active GET List of active hosts (only name)
/hosts/out_of_sync GET List of out of sync hosts(only name)
/hosts/disabled GET List of disabled hosts(only name)
/hosts/FQDN/setBuild GET Move host to Build state
/hosts/FQDN/facts GET Returns host facts
/hosts/FQDN/puppetclasses GET Returns host classes (direct and indirect(via a hostgroup)
/hosts/FQDN/reports GET Reports for host FQDN
/hosts/FQDN/reports/last GET Last report for host FQDN
/hosts/FQDN/pxe_config GET Returns syslinux configuration file for fqdn
Hypervisors
/hypervisors POST Create a new Hypervisor {hypervisor : {"kind":string, "name":string, "uri":string}}
/hypervisors/ID DELETE Delete a Hypervisor
/hypervisors GET Retrieve a list of Hypervisors
/hypervisors/ID PUT Update an existing Hypervisor {hypervisor : {"kind":string, "name":string, "uri":string}}
Smart Variables
/lookup_keys POST Create a new SmartVar key {lookupkey : {"key":string}}
/lookup_keys/ID DELETE Delete a Smart key
/lookup_keys GET Retrieve a list of Smartvar keys
/lookup_keys/ID PUT Update an existing Smart key {lookupkey : {"key":string}}
Smart Variables values
/lookup_values POST Create a new SmartVar value {lookupvalue : {"lookup_key_id":integer, "match":string, "value":string}}
/lookup_values/ID DELETE Delete a Smart value
/lookup_values GET Retrieve a list of Smartvar values
/lookup_values/ID PUT Update an existing Smart value {lookupvalue : {"value":string}}
Medias
/media POST Create a new Medium {medium : {"name":string, "path":string}}
/media/ID DELETE Delete a Medium
/media GET Retrieve a list of Media
/media/ID PUT Update an existing Medium {medium : {"name":string, "path":string}}
Models
/models POST Create a new Model {model : {"info":string, "name":string}}
/models/ID DELETE Delete a Model
/models GET Retrieve a list of Models
/models/ID PUT Update an existing Model {model : {"info":string, "name":string}}
Operatingsystems
/operatingsystems POST Create a new Operatingsystem {operatingsystem : {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}
/operatingsystems/ID DELETE Delete a Operatingsystem
/operatingsystems GET Retrieve a list of Operatingsystems
/operatingsystems/ID PUT Update an existing Operatingsystem {operatingsystem : {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}
/operatingsystems/ID/bootfiles?media=<media_name>&architecture=x86_64 GET tftp boot files and their respective urls (where they can be found)
Ptables
/ptables POST Create a new Ptable {ptable : {"layout":string, "name":string, "operatingsystem_id":int}}
/ptables/ID DELETE Delete a Ptable
/ptables GET Retrieve a list of Ptables
/ptables/ID PUT Update an existing Ptable {ptable : {"layout":string, "name":string, "operatingsystem_id":int}}
Puppetclasses
/puppetclasses POST Create a new Puppetclass {puppetclass : {"name":string, "nameindicator":string, "operatingsystem_id":int}}
/puppetclasses/ID DELETE Delete a Puppetclass
/puppetclasses GET Retrieve a list of Puppetclasses
/puppetclasses/ID PUT Update an existing Puppetclass {puppetclass : {"name":string, "nameindicator":string, "operatingsystem_id":int}}
Reports
/reports POST Create a new Report {report : {"host_id":int, "metrics":string, "reported_at":string, "status":string}}
/reports/ID DELETE Delete a Report
/reports/last GET Retrieve the last report information
/reports?numreports=xx GET Retrieve reports xx items at a single time
Roles
/roles POST Create a new Role {role : {"builtin":string, "name":string, "permissions":string}}
/roles/ID DELETE Delete a Role
/roles GET Retrieve a list of Roles
/roles/ID PUT Update an existing Role {role : {"builtin":string, "name":string, "permissions":string}}
Smart proxies
/smart_proxies POST Create a new Smart proxy {smartproxy : {"name":string, "url":string}}
/smart_proxies/ID DELETE Delete a Smart proxy
/smart_proxies GET Retrieve a list of Smart proxies
/smart_proxies/ID PUT Update an existing Smart proxy {smartproxy : {"name":string, "url":string}}
Subnets
/subnets POST Create a new Subnet {subnet : {"dhcp_id":int, "domain_id":int, "mask":string, "name":string, "network":string, "priority":string, "ranges":string, "tftp_id":int, "vlanid":int}}
/subnets/ID DELETE Delete a Subnet
/subnets GET Retrieve a list of Subnets
/subnets/ID PUT Update an existing Subnet {subnet : {"dhcp_id":int, "domain_id":int, "mask":string, "name":string, "network":string, "priority":string, "ranges":string, "tftp_id":int, "vlanid":int}}
Usergroups
/usergroups POST Create a new Usergroup {usergroup : {"name":string}}
/usergroups/ID DELETE Delete a Usergroup
/usergroups GET Retrieve a list of Usergroups
/usergroups/ID PUT Update an existing Usergroup {usergroup : {"name":string}}
Users
/users POST Create a new User {user : {"admin":string, "auth_source_id":int, "domains_andor":string, "facts_andor":string, "filter_on_owner":string, "firstname":string, "hostgroups_andor":string, "last_login_on":string, "lastname":string, "login":string, "mail":string, "password_hash":string, "password_salt":string, "role_id":int}}
/users/ID DELETE Delete a User
/users GET Retrieve a list of Users
/users/ID PUT Update an existing User {user : {"admin":string, "auth_source_id":int, "domains_andor":string, "facts_andor":string, "filter_on_owner":string, "firstname":string, "hostgroups_andor":string, "last_login_on":string, "lastname":string, "login":string, "mail":string, "password_hash":string, "password_salt":string, "role_id":int}}
Miscellaneous
/dashboard GET Summary statistcs (total hosts, active hosts, hosts in error etc)
/status GET System status (result ok/failed, database lag in miliseconds)

see also [[Smart-Proxy:API]]

Please raise a new issue if you need additional API's

New version of API

There is a new version of API being developed. Version 1 will cover current API.