Host collections

>>>

GET /katello/api/host_collections/:id
Show a host collection

Examples

GET /katello/api/host_collections/992660475
200
{
  "host_ids": [
    980190962
  ],
  "name": "Simple Host Collection",
  "organization_id": 114267492,
  "max_hosts": null,
  "description": "The simplest of host collections.",
  "total_hosts": 1,
  "unlimited_hosts": true,
  "created_at": "2022-11-08 19:09:32 UTC",
  "updated_at": "2022-11-08 19:09:32 UTC",
  "id": 992660475,
  "permissions": {
    "deletable": true,
    "editable": true
  }
}

Params

Param name Description
id
required

Id of the host collection

Validations:

  • Must be a number.
organization_id
optional

organization identifier

Validations:

  • Must be a number.
>>>

GET /katello/api/host_collections
List host collections

GET /katello/api/organizations/:organization_id/host_collections
List host collections within an organization

GET /katello/api/activation_keys/:activation_key_id/host_collections
List host collections in an activation key

Examples

GET /katello/api/host_collections
200
{
  "total": 5,
  "subtotal": 5,
  "selectable": 5,
  "page": 1,
  "per_page": 20,
  "error": null,
  "search": null,
  "sort": {
    "by": "name",
    "order": "asc"
  },
  "results": [
    {
      "name": "Another Simple Host Collection",
      "organization_id": 114267492,
      "max_hosts": null,
      "description": "Another collection,keeping it simple.",
      "total_hosts": 0,
      "unlimited_hosts": true,
      "created_at": "2022-11-08 19:09:32 UTC",
      "updated_at": "2022-11-08 19:09:32 UTC",
      "id": 1031461452,
      "permissions": {
        "deletable": true,
        "editable": true
      }
    },
    {
      "name": "Five Host Collection",
      "organization_id": 114267492,
      "max_hosts": 5,
      "description": "A collection of five hosts",
      "total_hosts": 1,
      "unlimited_hosts": false,
      "created_at": "2022-11-08 19:09:32 UTC",
      "updated_at": "2022-11-08 19:09:32 UTC",
      "id": 822851436,
      "permissions": {
        "deletable": true,
        "editable": true
      }
    },
    {
      "name": "Simple Host Collection",
      "organization_id": 114267492,
      "max_hosts": null,
      "description": "The simplest of host collections.",
      "total_hosts": 1,
      "unlimited_hosts": true,
      "created_at": "2022-11-08 19:09:32 UTC",
      "updated_at": "2022-11-08 19:09:32 UTC",
      "id": 992660475,
      "permissions": {
        "deletable": true,
        "editable": true
      }
    },
    {
      "name": "Single-host Collection",
      "organization_id": 114267492,
      "max_hosts": 1,
      "description": "A collection of one host",
      "total_hosts": 0,
      "unlimited_hosts": false,
      "created_at": "2022-11-08 19:09:32 UTC",
      "updated_at": "2022-11-08 19:09:32 UTC",
      "id": 944981076,
      "permissions": {
        "deletable": true,
        "editable": true
      }
    },
    {
      "name": "Yet Another Host Collection",
      "organization_id": 114267492,
      "max_hosts": null,
      "description": "Here we are in a collection again!",
      "total_hosts": 0,
      "unlimited_hosts": true,
      "created_at": "2022-11-08 19:09:32 UTC",
      "updated_at": "2022-11-08 19:09:32 UTC",
      "id": 230792737,
      "permissions": {
        "deletable": true,
        "editable": true
      }
    }
  ]
}

Params

Param name Description
search
optional

Search string

Validations:

  • String
page
optional

Page number, starting at 1

Validations:

  • Must be a number.
per_page
optional

Number of results per page to return

Validations:

  • Must be a number.
order
optional

Sort field and order, eg. 'id DESC'

Validations:

  • String
full_result
optional

Whether or not to show all results

Validations:

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

Field to sort the results on

Validations:

  • String
sort_order
optional

How to order the sorted results (e.g. ASC for ascending)

Validations:

  • String
organization_id
optional

organization identifier

Validations:

  • Must be a number.
name
optional

host collection name to filter by

Validations:

  • String
activation_key_id
optional

activation key identifier

Validations:

  • string from 2 to 128 characters containing only alphanumeric characters, space, '_', '-' with no leading or trailing space..
host_id
optional

Filter products by host id

Validations:

  • Must be a number.
available_for
optional

Interpret specified object to return only Host Collections that can be associated with specified object. The value 'host' is supported.

Validations:

  • String

Search fields

Field name Type Possible values
host string
name string
organization_id integer
>>>

POST /katello/api/host_collections
Create a host collection

POST /katello/api/organizations/:organization_id/host_collections
Create a host collection

Examples

POST /katello/api/organizations/114267492/host_collections
{
  "name": "Collection A",
  "description": "Collection A, World Cup 2014",
  "host_ids": [
    980191204
  ],
  "unlimited_hosts": true,
  "host_collection": {
    "name": "Collection A",
    "description": "Collection A, World Cup 2014",
    "unlimited_hosts": true,
    "host_ids": [
      980191204
    ]
  }
}
201
{
  "host_ids": [
    980191204
  ],
  "name": "Collection A",
  "organization_id": 114267492,
  "max_hosts": null,
  "description": "Collection A, World Cup 2014",
  "total_hosts": 1,
  "unlimited_hosts": true,
  "created_at": "2022-11-08 19:23:52 UTC",
  "updated_at": "2022-11-08 19:23:52 UTC",
  "id": 1031461454,
  "permissions": {
    "deletable": true,
    "editable": true
  }
}

Params

Param name Description
organization_id
required

organization identifier

Validations:

  • Must be a number.
name
required

Host Collection name

Validations:

  • String
description
optional

Validations:

  • String
host_ids
optional

List of host ids to replace the hosts in host collection

Validations:

  • Must be an array of any type
max_hosts
optional

Maximum number of hosts in the host collection

Validations:

  • Integer
unlimited_hosts
optional

Whether or not the host collection may have unlimited hosts

Validations:

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

PUT /katello/api/host_collections/:id
Update a host collection

Examples

PUT /katello/api/host_collections/992660475
{
  "organization_id": 114267492,
  "max_hosts": 0,
  "unlimited_hosts": false,
  "host_collection": {
    "max_hosts": 0,
    "organization_id": 114267492,
    "unlimited_hosts": false
  }
}
422
{
  "displayMessage": "Validation failed: Max hosts must be a positive integer value., Max host may not be less than the number of hosts associated with the host collection.",
  "errors": {
    "max_hosts": [
      "must be a positive integer value."
    ],
    "max_host": [
      "may not be less than the number of hosts associated with the host collection."
    ]
  }
}

Params

Param name Description
id
required

Id of the host collection

Validations:

  • Must be a number.
name
optional

Host Collection name

Validations:

  • String
description
optional

Validations:

  • String
host_ids
optional

List of host ids to replace the hosts in host collection

Validations:

  • Must be an array of any type
max_hosts
optional

Maximum number of hosts in the host collection

Validations:

  • Integer
unlimited_hosts
optional

Whether or not the host collection may have unlimited hosts

Validations:

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

PUT /katello/api/host_collections/:id/add_hosts
Add host to the host collection

Examples

PUT /katello/api/host_collections/992660475/add_hosts
{
  "host_ids": [
    980190962
  ],
  "host_collection": {
    "host_ids": [
      980190962
    ]
  }
}
200
{
  "displayMessages": {
    "success": [],
    "error": [
      "Host with ID 980190962 already exists in the host collection."
    ]
  }
}

Params

Param name Description
id
required

Id of the host collection

Validations:

  • Must be a number.
host_ids
optional

Array of host ids

Validations:

  • Must be an array of any type
>>>

PUT /katello/api/host_collections/:id/remove_hosts
Remove hosts from the host collection

Examples

PUT /katello/api/host_collections/992660475/remove_hosts
{
  "host_ids": [
    980190962
  ],
  "host_collection": {
    "host_ids": [
      980190962
    ]
  }
}
200
{
  "displayMessages": {
    "success": [
      "Successfully removed 1 Host(s)."
    ],
    "error": []
  }
}

Params

Param name Description
id
required

Id of the host collection

Validations:

  • Must be a number.
host_ids
optional

Array of host ids

Validations:

  • Must be an array of any type
>>>

DELETE /katello/api/host_collections/:id
Destroy a host collection

Examples

DELETE /katello/api/host_collections/992660475
{
  "host_collection": {}
}
200
{}

Params

Param name Description
id
required

Id of the host collection

Validations:

  • Must be a number.
>>>

POST /katello/api/host_collections/:id/copy
Make copy of a host collection

Params

Param name Description
id
required

ID of the host collection

Validations:

  • Must be a number.
name
required

New host collection name

Validations:

  • String