API Guide

The benefits of using the REST API are:

You can use the REST API to perform the following tasks:

As you prepare to upgrade Satellite Server, ensure that any scripts you use that contain Satellite API commands are up to date. API commands differ between versions of Satellite.

For many tasks, you can use both Hammer and Satellite API. You can use Hammer as a human-friendly interface to Satellite API. For example, to test responses to API calls before applying them in a script, use the --debug option to inspect API calls that Hammer issues: hammer --debug organization list.

In the background, each Hammer command first establishes a binding to the API and then sends a request. This can have performance implications when executing a large number of Hammer commands in sequence. In contrast, scripts that use API commands communicate directly with the Satellite API.

Note that you must manually update scripts that use API commands, while Hammer automatically reflects changes in the API. For more information, see the Hammer CLI Guide.

The built-in API reference shows the API route, or path, preceded by an HTTP verb:

HTTP_VERB API_ROUTE

To work with the API, construct a command using the curl command syntax and the API route from the reference document:

$ curl --request HTTP_VERB \                   1
--insecure \                                   2
--user sat_username:sat_password \             3
--data @file.json \                            4
--header "Accept:application/json" \ 5
--header "Content-Type:application/json" \      6
--output file                                  7
API_ROUTE \                                    8
| python3 -m json.tool                          9

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/hosts | python3 -m json.tool

{
  "total": 2,
  "subtotal": 2,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results":
output truncated

$ curl --header "Accept:application/json" \
--header "Content-Type:application/json" --request DELETE \
--user sat_username:sat_password --insecure \
https://satellite.example.com/katello/api/activation_keys/2 \
| python3 -m json.tool

output omitted
    "started_at": "2017-02-16 12:58:17 UTC",
    "ended_at": "2017-02-16 12:58:18 UTC",
    "state": "stopped",
    "result": "success",
    "progress": 1.0,
    "input": {
        "activation_key": {
            "id": 2,
            "name": "TestKey"
output truncated

Nested_Resource.Attribute_Name

Resource[Nested_Resource_attributes][Attribute_Name_id]

Calls to the API return results in JSON format. The API call returns the result for a single-option response or for responses collections.

This is an example of the format for a single-object request for the Satellite domain which ID is 23:

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/domains/23 | python3 -m json.tool

Example response:

{
    "id": 23,
    "name": "qa.lab.example.com",
    "fullname": "QA",
    "dns_id": 10,
    "created_at": "2013-08-13T09:02:31Z",
    "updated_at": "2013-08-13T09:02:31Z"
}

This is an example of the format for a collection request for a list of Satellite domains:

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/domains | python3 -m json.tool

Example response:

{
    "total": 3,
    "subtotal": 3,
    "page": 1,
    "per_page": 20,
    "search": null,
    "sort": {
        "by": null,
        "order": null
    },
    "results": [
        {
            "id": 23,
            "name": "qa.lab.example.com",
            "fullname": "QA",
            "dns_id": 10,
            "created_at": "2013-08-13T09:02:31Z",
            "updated_at": "2013-08-13T09:02:31Z"
        },
        {
            "id": 25,
            "name": "sat.lab.example.com",
            "fullname": "SATLAB",
            "dns_id": 8,
            "created_at": "2013-08-13T08:32:48Z",
            "updated_at": "2013-08-14T07:04:03Z"
        },
        {
            "id": 32,
            "name": "hr.lab.example.com",
            "fullname": "HR",
            "dns_id": 8,
            "created_at": "2013-08-16T08:32:48Z",
            "updated_at": "2013-08-16T07:04:03Z"
        }
    ]
}

Red Hat Satellite uses HTTPS, which provides a degree of encryption and identity verification when communicating with a Red Hat Satellite Server. Satellite 6.14 does not support non-SSL communications.

Each Red Hat Satellite Server uses a self-signed certificate. This certificate acts as both the server certificate to verify the encryption key and the certificate authority (CA) to trust the identity of Satellite Server.

All requests to the Satellite API require a valid Satellite user name and password. The API uses HTTP Basic Authentication to encode these credentials and add to the Authorization header. For more information about Basic Authentication, see RFC 2617 HTTP Authentication: Basic and Digest Access Authentication. If a request does not include an appropriate Authorization header, the API returns a 401 Authorization Required error

Some base64 libraries break encoded credentials into multiple lines and terminate each line with a newline character. This invalidates the header and causes a faulty request. The Authorization header requires that the encoded credentials be on a single line within the header.

Red Hat Satellite supports Personal Access Tokens that you can use to authenticate API requests instead of using your password. You can set an expiration date for your Personal Access Token and you can revoke it if you decide it should expire before the expiration date.

As an alternative to basic authentication, you can use limited OAuth 1.0 authentication. This is sometimes referred to as 1-legged OAuth in version 1.0a of the protocol.

To view OAuth settings, in the Satellite web UI, navigate to Administer > Settings > Authentication. The OAuth consumer key is the token to be used by all OAuth clients.

Satellite stores OAuth settings in the /etc/foreman/settings.yaml file. Use the satellite-installer script to configure these settings, because Satellite overwrites any manual changes to this file when upgrading.

# satellite-installer --full-help | grep oauth

# satellite-installer --foreman-oauth-map-users true

--header 'FOREMAN-USER: sat_username' \
--header 'Authorization: OAuth oauth_version="1.0",oauth_consumer_key="secretkey",oauth_signature_method="hmac-sha1",oauth_timestamp=timestamp,oauth_signature=signature'

$ curl 'https://satellite.example.com/api/architectures' \
--header 'Content-Type: application/json' \
--header 'Accept:application/json' \
--header 'FOREMAN-USER: sat_username' \
--header 'Authorization: OAuth oauth_version="1.0",oauth_consumer_key="secretkey",oauth_signature_method="hmac-sha1",oauth_timestamp=1321473112,oauth_signature=Il8hR8/ogj/XVuOqMPB9qNjSy6E='

This section outlines how to use curl with the Satellite API to perform various tasks.

Red Hat Satellite requires the use of HTTPS, and by default a certificate for host identification. If you have not added the Satellite Server certificate as described in Section 3.1, “SSL authentication overview”, then you can use the --insecure option to bypass certificate checks.

For user authentication, you can use the --user option to provide Satellite user credentials in the form --user username:password or, if you do not include the password, the command prompts you to enter it. To reduce security risks, do not include the password as part of the command, because it then becomes part of your shell history. Examples in this section include the password only for the sake of simplicity.

Be aware that if you use the --silent option, curl does not display a progress meter or any error messages.

Examples in this chapter use the Python json.tool module to format the output.

--header "Accept:application/json" \
--header "Content-Type:application/json"

$ json_verify < test_file.json

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/users | python3 -m json.tool

{
    "page": 1,
    "per_page": 20,
    "results": [
        {
            "admin": false,
            "auth_source_id": 1,
            "auth_source_name": "Internal",
            "created_at": "2018-09-21 08:59:22 UTC",
            "default_location": null,
            "default_organization": null,
            "description": "",
            "effective_admin": false,
            "firstname": "",
            "id": 5,
            "last_login_on": "2018-09-21 09:03:25 UTC",
            "lastname": "",
            "locale": null,
            "locations": [],
            "login": "test",
            "mail": "example@domain.com",
            "organizations": [
                {
                    "id": 1,
                    "name": "Default Organization"
                }
            ],
            "ssh_keys": [],
            "timezone": null,
            "updated_at": "2018-09-21 09:04:45 UTC"
        },
        {
            "admin": true,
            "auth_source_id": 1,
            "auth_source_name": "Internal",
            "created_at": "2018-09-20 07:09:41 UTC",
            "default_location": null,
            "default_organization": {
                "description": null,
                "id": 1,
                "name": "Default Organization",
                "title": "Default Organization"
            },
            "description": "",
            "effective_admin": true,
            "firstname": "Admin",
            "id": 4,
            "last_login_on": "2018-12-07 07:31:09 UTC",
            "lastname": "User",
            "locale": null,
            "locations": [
                {
                    "id": 2,
                    "name": "Default Location"
                }
            ],
            "login": "admin",
            "mail": "root@example.com",
            "organizations": [
                {
                    "id": 1,
                    "name": "Default Organization"
                }
            ],
            "ssh_keys": [],
            "timezone": null,
            "updated_at": "2018-11-14 08:19:46 UTC"
        }
    ],
    "search": null,
    "sort": {
        "by": null,
        "order": null
    },
    "subtotal": 2,
    "total": 2
}

$ curl --header "Accept:application/json" \
--header "Content-Type:application/json" --request POST \
--user sat_username:sat_password --insecure \
--data "{\"firstname\":\"Test Name\",\"mail\":\"test@example.com\",\"login\":\"test_user\",\"password\":\"password123\",\"auth_source_id\":1}" \
https://satellite.example.com/api/users | python3 -m json.tool

$ curl --header "Accept:application/json" \
--header "Content-Type:application/json" --request PUT \
--user sat_username:sat_password --insecure \
--data "{\"firstname\":\"New Test Name\",\"mail\":\"test@example.com\",\"login\":\"new_test_user\",\"password\":\"password123\",\"auth_source_id\":1}" \
https://satellite.example.com/api/users/8 | python3 -m json.tool

This section outlines how to use Ruby with the Satellite API to perform various tasks.

#!/usr/bin/ruby

require 'rest-client'
require 'json'

url = 'https://satellite.example.com/api/v2/'
katello_url = "#{url}/katello/api/v2/"

$username = 'admin'
$password = 'changeme'

org_name = "MyOrg"
environments = [ "Development", "Testing", "Production" ]

# Performs a GET using the passed URL location
def get_json(location)
  response = RestClient::Request.new(
    :method => :get,
    :url => location,
    :user => $username,
    :password => $password,
    :headers => { :accept => :json,
    :content_type => :json }
  ).execute
  JSON.parse(response.to_str)
end

# Performs a POST and passes the data to the URL location
def post_json(location, json_data)
  response = RestClient::Request.new(
    :method => :post,
    :url => location,
    :user => $username,
    :password => $password,
    :headers => { :accept => :json,
    :content_type => :json},
    :payload => json_data
  ).execute
  JSON.parse(response.to_str)
end

# Creates a hash with ids mapping to names for an array of records
def id_name_map(records)
  records.inject({}) do |map, record|
    map.update(record['id'] => record['name'])
  end
end

# Get list of existing organizations
orgs = get_json("#{katello_url}/organizations")
org_list = id_name_map(orgs['results'])

if !org_list.has_value?(org_name)
  # If our organization is not found, create it
  puts "Creating organization: \t#{org_name}"
  org_id = post_json("#{katello_url}/organizations", JSON.generate({"name"=> org_name}))["id"]
else
  # Our organization exists, so let's grab it
  org_id = org_list.key(org_name)
  puts "Organization \"#{org_name}\" exists"
end

# Get list of organization's lifecycle environments
envs = get_json("#{katello_url}/organizations/#{org_id}/environments")
env_list = id_name_map(envs['results'])
prior_env_id = env_list.key("Library")

# Exit the script if at least one life cycle environment already exists
environments.each do |e|
  if env_list.has_value?(e)
    puts "ERROR: One of the Environments is not unique to organization"
    exit
  end
end

 # Create life cycle environments
environments.each do |environment|
  puts "Creating environment: \t#{environment}"
  prior_env_id = post_json("#{katello_url}/organizations/#{org_id}/environments", JSON.generate({"name" => environment, "organization_id" => org_id, "prior_id" => prior_env_id}))["id"]
end

#!/usr/bin/tfm-ruby

require 'apipie-bindings'

org_name = "MyOrg"
environments = [ "Development", "Testing", "Production" ]

# Create an instance of apipie bindings
@api = ApipieBindings::API.new({
  :uri => 'https://satellite.example.com/',
  :username => 'admin',
  :password => 'changeme',
  :api_version => 2
})

# Performs an API call with default options
def call_api(resource_name, action_name, params = {})
  http_headers = {}
  apipie_options = { :skip_validation => true }
  @api.resource(resource_name).call(action_name, params, http_headers, apipie_options)
end

# Creates a hash with IDs mapping to names for an array of records
def id_name_map(records)
  records.inject({}) do |map, record|
    map.update(record['id'] => record['name'])
  end
end

# Get list of existing organizations
orgs = call_api(:organizations, :index)
org_list = id_name_map(orgs['results'])

if !org_list.has_value?(org_name)
  # If our organization is not found, create it
  puts "Creating organization: \t#{org_name}"
  org_id = call_api(:organizations, :create, {'organization' => { :name => org_name }})['id']
else
  # Our organization exists, so let's grab it
  org_id = org_list.key(org_name)
  puts "Organization \"#{org_name}\" exists"
end

# Get list of organization's life cycle environments
envs = call_api(:lifecycle_environments, :index, {'organization_id' => org_id})
env_list = id_name_map(envs['results'])
prior_env_id = env_list.key("Library")

# Exit the script if at least one life cycle environment already exists
environments.each do |e|
  if env_list.has_value?(e)
    puts "ERROR: One of the Environments is not unique to organization"
    exit
  end
end

 # Create life cycle environments
environments.each do |environment|
  puts "Creating environment: \t#{environment}"
  prior_env_id = call_api(:lifecycle_environments, :create, {"name" => environment, "organization_id" => org_id, "prior_id" => prior_env_id })['id']
end

This section outlines how to use Python with the Satellite API to perform various tasks.

Example scripts in this section do not use SSL verification for interacting with the REST API.

#!/usr/bin/python

import json
import sys

try:
    import requests
except ImportError:
    print "Please install the python-requests module."
    sys.exit(-1)

# URL to your Satellite 6 server
URL = "https://satellite.example.com"
# URL for the API to your deployed Satellite 6 server
SAT_API = "%s/katello/api/v2/" % URL
# Katello-specific API
KATELLO_API = "%s/katello/api/" % URL
POST_HEADERS = {'content-type': 'application/json'}
# Default credentials to login to Satellite 6
USERNAME = "admin"
PASSWORD = "changeme"
# Ignore SSL for now
SSL_VERIFY = False

# Name of the organization to be either created or used
ORG_NAME = "MyOrg"
# Name for life cycle environments to be either created or used
ENVIRONMENTS = ["Development", "Testing", "Production"]


def get_json(location):
    """
    Performs a GET using the passed URL location
    """

    r = requests.get(location, auth=(USERNAME, PASSWORD), verify=SSL_VERIFY)

    return r.json()


def post_json(location, json_data):
    """
    Performs a POST and passes the data to the URL location
    """

    result = requests.post(
        location,
        data=json_data,
        auth=(USERNAME, PASSWORD),
        verify=SSL_VERIFY,
        headers=POST_HEADERS)

    return result.json()


def main():
    """
    Main routine that creates or re-uses an organization and
    life cycle environments. If life cycle environments already
    exist, exit out.
    """

    # Check if our organization already exists
    org = get_json(SAT_API + "organizations/" + ORG_NAME)

    # If our organization is not found, create it
    if org.get('error', None):
        org_id = post_json(
            SAT_API + "organizations/",
            json.dumps({"name": ORG_NAME}))["id"]
        print "Creating organization: \t" + ORG_NAME
    else:
        # Our organization exists, so let's grab it
        org_id = org['id']
        print "Organization '%s' exists." % ORG_NAME

    # Now, let's fetch all available life cycle environments for this org...
    envs = get_json(
        SAT_API + "organizations/" + str(org_id) + "/environments/")

    # ... and add them to a dictionary, with respective 'Prior' environment
    prior_env_id = 0
    env_list = {}
    for env in envs['results']:
        env_list[env['id']] = env['name']
        prior_env_id = env['id'] if env['name'] == "Library" else prior_env_id

    # Exit the script if at least one life cycle environment already exists
    if all(environment in env_list.values() for environment in ENVIRONMENTS):
        print "ERROR: One of the Environments is not unique to organization"
        sys.exit(-1)

    # Create life cycle environments
    for environment in ENVIRONMENTS:
        new_env_id = post_json(
            SAT_API + "organizations/" + str(org_id) + "/environments/",
            json.dumps(
                {
                    "name": environment,
                    "organization_id": org_id,
                    "prior": prior_env_id}
            ))["id"]

        print "Creating environment: \t" + environment
        prior_env_id = new_env_id


if __name__ == "__main__":
    main()

#!/usr/bin/python
import json
import sys
try:
    import requests
except ImportError:
    print "Please install the python-requests module."
    sys.exit(-1)

SAT_API = 'https://satellite.example.com/api/v2/'
USERNAME = "admin"
PASSWORD = "password"
SSL_VERIFY = False   # Ignore SSL for now

def get_json(url):
    # Performs a GET using the passed URL location
    r = requests.get(url, auth=(USERNAME, PASSWORD), verify=SSL_VERIFY)
    return r.json()

def get_results(url):
    jsn = get_json(url)
    if jsn.get('error'):
        print "Error: " + jsn['error']['message']
    else:
        if jsn.get('results'):
            return jsn['results']
        elif 'results' not in jsn:
            return jsn
        else:
            print "No results found"
    return None

def display_all_results(url):
    results = get_results(url)
    if results:
        print json.dumps(results, indent=4, sort_keys=True)

def display_info_for_hosts(url):
    hosts = get_results(url)
    if hosts:
        for host in hosts:
            print "ID: %-10d Name: %-30s IP: %-20s OS: %-30s" % (host['id'], host['name'], host['ip'], host['operatingsystem_name'])

def main():
    host = 'satellite.example.com'
    print "Displaying all info for host %s ..." % host
    display_all_results(SAT_API + 'hosts/' + host)

    print "Displaying all facts for host %s ..." % host
    display_all_results(SAT_API + 'hosts/%s/facts' % host)

    host_pattern = 'example'
    print "Displaying basic info for hosts matching pattern '%s'..." % host_pattern
    display_info_for_hosts(SAT_API + 'hosts?search=' + host_pattern)

    environment = 'production'
    print "Displaying basic info for hosts in environment %s..." % environment
    display_info_for_hosts(SAT_API + 'hosts?search=environment=' + environment)

    model = 'RHEV Hypervisor'
    print "Displaying basic info for hosts with model name %s..." % model
    display_info_for_hosts(SAT_API + 'hosts?search=model="' + model + '"')

if __name__ == "__main__":
    main()

#!/usr/bin/env python3

import json
import sys

try:
    import requests
except ImportError:
    print("Please install the python-requests module.")
    sys.exit(-1)

SAT = "satellite.example.com"
# URL for the API to your deployed Satellite 6 server
SAT_API = f"https://{SAT}/api/"
KATELLO_API = f"https://{SAT}/katello/api/v2/"

POST_HEADERS = {'content-type': 'application/json'}
# Default credentials to login to Satellite 6
USERNAME = "admin"
PASSWORD = "password"
# Ignore SSL for now
SSL_VERIFY = False
#SSL_VERIFY = "./path/to/CA-certificate.crt" # Put the path to your CA certificate here to allow SSL_VERIFY


def get_json(url):
    # Performs a GET using the passed URL location
    r = requests.get(url, auth=(USERNAME, PASSWORD), verify=SSL_VERIFY)
    return r.json()

def get_results(url):
    jsn = get_json(url)
    if jsn.get('error'):
        print("Error: " + jsn['error']['message'])
    else:
        if jsn.get('results'):
            return jsn['results']
        elif 'results' not in jsn:
            return jsn
        else:
            print("No results found")
    return None

def display_all_results(url):
    results = get_results(url)
    if results:
        print(json.dumps(results, indent=4, sort_keys=True))

def display_info_for_hosts(url):
    hosts = get_results(url)
    if hosts:
        print(f"{'ID':10}{'Name':40}{'IP':30}{'Operating System':30}")
        for host in hosts:
            print(f"{str(host['id']):10}{host['name']:40}{str(host['ip']):30}{str(host['operatingsystem_name']):30}")

def display_info_for_subs(url):
    subs = get_results(url)
    if subs:
        print(f"{'ID':10}{'Name':90}{'Start Date':30}")
        for sub in subs:
            print(f"{str(sub['id']):10}{sub['name']:90}{str(sub['start_date']):30}")

def main():
    host = SAT
    print(f"Displaying all info for host {host} ...")
    display_all_results(SAT_API + 'hosts/' + host)

    print(f"Displaying all facts for host {host} ...")
    display_all_results(SAT_API + f'hosts/{host}/facts')

    host_pattern = 'example'
    print(f"Displaying basic info for hosts matching pattern '{host_pattern}'...")
    display_info_for_hosts(SAT_API + 'hosts?per_page=1&search=name~' + host_pattern)

    print(f"Displaying basic info for subscriptions")
    display_info_for_subs(KATELLO_API + 'subscriptions')

    environment = 'production'
    print(f"Displaying basic info for hosts in environment {environment}...")
    display_info_for_hosts(SAT_API + 'hosts?search=environment=' + environment)


if __name__ == "__main__":
    main()

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts | python3 -m json.tool

Example response:

{
      ...
       "total" => 2,
    "subtotal" => 2,
        "page" => 1,
    "per_page" => 1000,
      "search" => nil,
        "sort" => {
           "by" => nil,
        "order" => nil
    },
     "results" => [
      ...
}

Example request:

$  curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts/satellite.example.com \
| python3 -m json.tool

Example response:

{
    "all_puppetclasses": [],
    "architecture_id": 1,
    "architecture_name": "x86_64",
    "build": false,
    "capabilities": [
        "build"
    ],
    "certname": "satellite.example.com",
    "comment": null,
    "compute_profile_id": null,
    ...
}

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts/satellite.example.com/facts \
| python3 -m json.tool

Example response:

{
    ...
    "results": {
        "satellite.example.com": {
            "augeasversion": "1.0.0",
            "bios_release_date": "01/01/2007",
            "bios_version": "0.5.1",
            "blockdevice_sr0_size": "1073741312",
            "facterversion": "1.7.6",
            ...
}

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts?search=example \
| python3 -m json.tool

Example response:

{
    ...
    "results": [
        {
            "name": "satellite.example.com",
            ...
        }
    ],
    "search": "example",
    ...
}

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts?search=environment=production \
| python3 -m json.tool

Example response:

{
    ...
    "results": [
        {
            "environment_name": "production",
            "name": "satellite.example.com",
            ...
        }
    ],
    "search": "environment=production",
    ...
}

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts?search=model=\"RHEV+Hypervisor\" \
| python3 -m json.tool

Example response:

{
    ...
    "results": [
        {
            "model_id": 1,
            "model_name": "RHEV Hypervisor",
            "name": "satellite.example.com",
            ...
        }
    ],
    "search": "model=\"RHEV Hypervisor\"",
    ...
}

Example request:

$ curl --request DELETE --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts/host1.example.com \
| python3 -m json.tool

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/bootdisk/api/hosts/host_ID?full=true \
--output image.iso

Satellite divides application life cycles into life cycle environments, which represent each stage of the application life cycle. Life cycle environments are linked to from an environment path. To create linked life cycle environments with the API, use the prior_id parameter.

You can find the built-in API reference for life cycle environments at https://satellite.example.com/apidoc/v2/lifecycle_environments.html. The API routes include /katello/api/environments and /katello/api/organizations/:organization_id/environments.

Example request:

$ curl --header "Accept:application/json" \
--header "Content-Type:application/json" \
--request GET --user sat_username:sat_password --insecure \
https://satellite.example.com/katello/api/organizations/1/environments \
| python3 -m json.tool`

Example response:

      output omitted
   "description": null,
   "id": 1,
   "label": "Library",
   "library": true,
   "name": "Library",
   "organization": {
        "id": 1,
        "label": "Default_Organization",
        "name": "Default Organization"
   },
   "permissions": {
       "destroy_lifecycle_environments": false,
       "edit_lifecycle_environments": true,
       "promote_or_remove_content_views_to_environments": true,
       "view_lifecycle_environments": true
   },
   "prior": null,
   "successor": null,
   output truncated

This procedure uses the default Library environment with ID 1 as the starting point for creating life cycle environments.

This example request updates a description of the life cycle environment with ID 3.

Example request:

$ curl --header "Accept:application/json" \
--header "Content-Type:application/json" \
--request POST --user sat_username:sat_password --insecure \
--data '{"description":"Quality Acceptance Testing"}' \
https://satellite.example.com/katello/api/environments/3 \
| python3 -m json.tool

Example response:

      output omitted
    "description": "Quality Acceptance Testing",
    "id": 3,
    "label": "api-qa",
    "library": false,
    "name": "API QA",
    "organization": {
        "id": 1,
        "label": "Default_Organization",
        "name": "Default Organization"
    },
    "permissions": {
        "destroy_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "promote_or_remove_content_views_to_environments": true,
        "view_lifecycle_environments": true
    },
    "prior": {
        "id": 2,
        "name": "API Development"
    },
    output truncated

Example request:

$ curl --request DELETE --user sat_username:sat_password --insecure \
https://satellite.example.com/katello/api/environments/:id

This section outlines how to use the Satellite 6 API to upload and import large files to your Satellite Server. This process involves four steps:

The maximum file size that you can upload is 2MB. For information about uploading larger content, see Uploading content larger than 2 MB.

Example request:

$ curl -H 'Content-Type: application/json' -X POST -k \
-u sat_username:sat_password -d "{\"size\": \"$size\", \"checksum\":\"$checksum\"}" \
https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads

The call will return a content unit ID instead of an upload ID, similar to this:

{"content_unit_href":"/pulp/api/v3/content/file/files/c1bcdfb8-d840-4604-845e-86e82454c747/"}

You can copy this output and call import uploads directly to add the content to a repository:

Example request:

$ curl -H "Content-Type:application/json" -X PUT -u \
sat_username:sat_password -k \-d \
"{\"uploads\":[{\"content_unit_id\": \"/pulp/api/v3/content/file/files/c1bcdfb8-d840-4604-845e-86e82454c747/\", \
\"name\": \"$name\", \ \"checksum\": \"$checksum\" }]}" https://$(hostname -f)/katello/api/v2/repositories/76/import_uploads

Note that the call changes from using upload_id to using content_unit_id.

You can use the API to apply errata to a host, host group, or host collection. The following is the basic syntax of a PUT request:

$ curl --header "Accept:application/json" \
--header "Content-Type:application/json" --request PUT \
--user sat_username:sat_password --insecure \
--data json-formatted-data https://satellite7.example.com

You can browse the built in API doc to find a URL to use for applying Errata. You can use the Satellite web UI to help discover the format for the search query. Navigate to Hosts > Host Collections and select a host collection. Go to Collection Actions > Errata Installation and notice the search query box contents. For example, for a Host Collection called my-collection, the search box contains host_collection="my-collection".

Example request:

$ curl --header "Accept:application/json" \
--header "Content-Type:application/json" --request PUT \
--user sat_username:sat_password --insecure \
--data "{\"organization_id\":1,\"included\":{\"search\":\"my-host\"},\"content_type\":\"errata\",\"content\":[\"RHBA-2016:1981\"]}" \
https://satellite.example.com/api/v2/hosts/bulk/install_content

Example request:

$ curl --header "Accept:application/json" \
--header "Content-Type:application/json" --request PUT \
--user sat_username:sat_password --insecure \
--data "{\"organization_id\":1,\"included\":{\"search\":\"host_collection=\\\"my-collection\\\"\"},\"content_type\":\"errata\",\"content\":[\"RHBA-2016:1981\"]}" \
https://satellite.example.com/api/v2/hosts/bulk/install_content

You can find search parameters that you can use to build your search queries in the web UI. For more information, see Building Search Queries in Administering Red Hat Satellite.

For example, to search for hosts, complete the following steps:

You can use the per_page and page pagination parameters to limit the search results that an API search query returns. The per_page parameter specifies the number of results per page and the page parameter specifies which page, as calculated by the per_page parameter, to return.

The default number of items to return is set to 1000 when you do not specify any pagination parameters, but the per_page value has a default of 20 which applies when you specify the page parameter.

Example request:

$ curl --request GET --user sat_username:sat_password \
https://satellite.example.com/katello/api/content_views?per_page=10&page=3

Example request:

$ curl --request GET --user sat_username:sat_password \
https://satellite.example.com/katello/api/activation_keys?organization_id=1&per_page=30&page=2

This example returns pages 1 to 3 of Content Views with 5 results per page:

$ for i in seq 1 3; do \
curl --request GET --user sat_username:sat_password \
https://satellite.example.com/katello/api/content_views?per_page=5&page=$i; \
done

You can search for Smart Parameters using the API and supply a value to override a Smart Parameter in a Class. You can find the full list of attributes that you can modify in the built-in API reference at https://satellite.example.com/apidoc/v2/smart_class_parameters/update.html.

Using external files simplifies working with JSON data. Using an editor with syntax highlighting can help you avoid and locate mistakes.

In Satellite Server, you can delete one or more OpenSCAP reports. However, when you delete reports, you must delete one page at a time. If you want to delete all Openscap reports, use the bash script that follows.

#!/bin/bash

#this script removes all the arf reports from the satellite server

#settings
USER=username
PASS=password
URI=https://satellite.example.com

#check amount of reports
 while [ $(curl --insecure --user $USER:$PASS $URI/api/v2/compliance/arf_reports/ | python3 -m json.tool | grep \"\total\": | cut --fields=2 --delimiter":" | cut --fields=1 --delimiter"," | sed "s/ //g") -gt 0 ]; do

#fetch reports
 for i in $(curl --insecure --user $USER:$PASS $URI/api/v2/compliance/arf_reports/ | python3 -m json.tool | grep \"\id\": | cut --fields=2 --delimiter":" | cut --fields=1 --delimiter"," | sed "s/ //g")

#delete reports
  do
  curl --insecure --user $USER:$PASS --header "Content-Type: application/json" --request DELETE $URI/api/v2/compliance/arf_reports/$i
  done
done

When sending API requests to Pulp integrated with Satellite, use certificate-based authentication.

The following examples of Pulp API requests include examples of how to use the Pulp CLI as an alternative. When you run pulp commands as root, Pulp CLI uses system certificates configured in /root/.config/pulp/cli.toml.

Example request:

curl --cacert /etc/pki/katello/certs/katello-server-ca.crt \
--cert /etc/foreman/client_cert.pem --key /etc/foreman/client_key.pem \
https://<satellite.example.com>/pulp/api/v3/repositories/ \
| python3 -m json.tool

Example response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "pulp_href": "/pulp/api/v3/repositories/rpm/rpm/018cd05a-4b83-73db-b71c-587c6181d89b/",
            "pulp_created": "2024-01-03T17:23:47.715882Z",
            "versions_href": "/pulp/api/v3/repositories/rpm/rpm/018cd05a-4b83-73db-b71c-587c6181d89b/versions/",
            "pulp_labels": {},
            "latest_version_href": "/pulp/api/v3/repositories/rpm/rpm/018cd05a-4b83-73db-b71c-587c6181d89b/versions/1/",
            "name": "Red_Hat_Enterprise_Linux_8_for_x86_64_-_BaseOS_Kickstart_8_9-49838",
            "description": null,
            "retain_repo_versions": null,
            "remote": null
        }
    ]
}

Alternatively, use the Pulp CLI to list repositories:

# pulp repository list
[
  {
    "pulp_href": "/pulp/api/v3/repositories/rpm/rpm/018cd025-c6ef-7237-a99e-70bab3d30941/",
    "pulp_created": "2024-01-03T16:26:25.904682Z",
    "versions_href": "/pulp/api/v3/repositories/rpm/rpm/018cd025-c6ef-7237-a99e-70bab3d30941/versions/",
    "pulp_labels": {},
    "latest_version_href": "/pulp/api/v3/repositories/rpm/rpm/018cd025-c6ef-7237-a99e-70bab3d30941/versions/1/",
    "name": "Red_Hat_Enterprise_Linux_8_for_x86_64_-_AppStream_RPMs_8-2875",
    "description": null,
    "retain_repo_versions": null,
    "remote": null
  }
]

Example request:

curl https://<satellite.example.com>/pulp/api/v3/status/ \
| python3 -m json.tool

Example response:

{
    "versions": [
        {
            "component": "core",
            "version": "3.39.4",
            "package": "pulpcore",
            "domain_compatible": true
        },
        {
            "component": "rpm",
            "version": "3.23.0",
            "package": "pulp-rpm",
            "domain_compatible": true
        },
...

Alternatively, use the Pulp CLI to retrieve Pulp status:

# pulp status
{
  "versions": [
    {
      "component": "core",
      "version": "3.39.4",
      "package": "pulpcore",
      "domain_compatible": true
    },
    {
      "component": "rpm",
      "version": "3.23.0",
      "package": "pulp-rpm",
      "domain_compatible": true
    },
...