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:

• *Foreman API documentation*

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.

Pre-Foreman 1.1 API¶

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.

• Source code lives in source:app/controllers/api
• Documentation can be accessed on http://path.to.foreman/apidoc
• API OAuth