Inventory List API Endpoint¶

Results¶

Each inventory data structure includes the following fields:

• id: Database ID for this inventory. (integer)

• type: Data type for this inventory. (choice)

  • inventory: Inventory

• url: URL for this inventory. (string)
• related: Data structure with URLs of related resources. (object)
• summary_fields: Data structure with name/description for related resources. (object)
• created: Timestamp when this inventory was created. (datetime)
• modified: Timestamp when this inventory was last modified. (datetime)
• name: Name of this inventory. (string)
• description: Optional description of this inventory. (string)
• organization: Organization containing this inventory. (field)

• kind: Kind of inventory being represented. (choice)

  • "": Hosts have a direct link to this inventory.
  • smart: Hosts for inventory generated using the host_filter property.

• host_filter: Filter that will be applied to the hosts of this inventory. (string)
• variables: Inventory variables in JSON or YAML format. (string)
• has_active_failures: Flag indicating whether any hosts in this inventory have failed. (boolean)
• total_hosts: Total number of hosts in this inventory. (integer)
• hosts_with_active_failures: Number of hosts in this inventory with active failures. (integer)
• total_groups: Total number of groups in this inventory. (integer)
• groups_with_active_failures: Number of groups in this inventory with active failures. (integer)
• has_inventory_sources: Flag indicating whether this inventory has any external inventory sources. (boolean)
• total_inventory_sources: Total number of external inventory sources configured within this inventory. (integer)
• inventory_sources_with_failures: Number of external inventory sources in this inventory with failures. (integer)
• insights_credential: Credentials to be used by hosts belonging to this inventory when accessing Red Hat Insights API. (field)
• pending_deletion: Flag indicating the inventory is being deleted. (boolean)

Sorting¶

To specify that inventories are returned in a particular order, use the order_by query string parameter on the GET request.

?order_by=name

Prefix the field name with a dash - to sort in reverse:

?order_by=-name

Multiple sorting fields may be specified by separating the field names with a comma ,:

?order_by=name,some_other_field

Pagination¶

Use the page_size query string parameter to change the number of results returned for each request. Use the page query string parameter to retrieve a particular page of results.

?page_size=100&page=2

The previous and next links returned with the results will set these query string parameters automatically.

Searching¶

Use the search query string parameter to perform a case-insensitive search within all designated text fields of a model.

?search=findme

Search across related fields (added in AWX 1.4 / Ansible Tower 3.1):

?related__search=findme

Filtering¶

Any additional query string parameters may be used to filter the list of results returned to those matching a given value. Only fields and relations that exist in the database may be used for filtering. Any special characters in the specified value should be URL-encoded. For example:

?field=value%20xyz

Fields may also span relations, only for fields and relationships defined in the database:

?other__field=value

To exclude results matching certain criteria, prefix the field parameter with not__:

?not__field=value

By default, all query string filters are AND’ed together, so only the results matching all filters will be returned (added in AWX 1.4). To combine results matching any one of multiple criteria, prefix each query string parameter with or__:

?or__field=value&or__field=othervalue
?or__not__field=value&or__field=othervalue

The default AND filtering applies all filters simultaneously to each related object being filtered across database relationships (added in Ansible Tower 1.4.5). The chain filter instead applies filters separately for each related object. To use, prefix the query string parameter with chain__:

?chain__related__field=value&chain__related__field2=othervalue
?chain__not__related__field=value&chain__related__field2=othervalue

If the first query above were written as ?related__field=value&related__field2=othervalue, it would return only the primary objects where the same related object satisfied both conditions. As written using the chain filter, it would return the intersection of primary objects matching each condition.

Field lookups may also be used for more advanced queries, by appending the lookup to the field name:

?field__lookup=value

The following field lookups are supported:

• exact: Exact match (default lookup if not specified).
• iexact: Case-insensitive version of exact.
• contains: Field contains value.
• icontains: Case-insensitive version of contains.
• startswith: Field starts with value.
• istartswith: Case-insensitive version of startswith.
• endswith: Field ends with value.
• iendswith: Case-insensitive version of endswith.
• regex: Field matches the given regular expression.
• iregex: Case-insensitive version of regex.
• gt: Greater than comparison.
• gte: Greater than or equal to comparison.
• lt: Less than comparison.
• lte: Less than or equal to comparison.
• isnull: Check whether the given field or related object is null; expects a boolean value.
• in: Check whether the given field’s value is present in the list provided; expects a list of items.

Boolean values may be specified as True or 1 for true, False or 0 for false (both case-insensitive).

Null values may be specified as None or Null (both case-insensitive), though it is preferred to use the isnull lookup to explicitly check for null values.

Lists (for the in lookup) may be specified as a comma-separated list of values.

Filtering based on the requesting user’s level of access by query string parameter (added in Ansible Tower 3.1).

• role_level: Level of role to filter on, such as admin_role

Create Inventories¶

Make a POST request to this resource with the following inventory fields to create a new inventory:

• name: Name of this inventory. (string, required)
• description: Optional description of this inventory. (string, default=””)
• organization: Organization containing this inventory. (field, required)

• kind: Kind of inventory being represented. (choice)

  • "": Hosts have a direct link to this inventory. (default)
  • smart: Hosts for inventory generated using the host_filter property.

• host_filter: Filter that will be applied to the hosts of this inventory. (string, default=””)
• variables: Inventory variables in JSON or YAML format. (string, default=””)

Reviewing the Options Endpoint¶

The Options Endpoint table offers a view of the Options for this endpoint. When viewing the endpoint in the browsable API, clicking the “Options” button gives you the raw JSON for the following: