Project

General

Profile

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.