Inventories

Overview

Inventories are collections of hosts that can be targeted by Ansible playbooks. AWX supports regular inventories, smart inventories (dynamic host filtering), and constructed inventories.

Endpoints

Method	Endpoint	Description
GET	`/api/v2/inventories/`	List inventories
POST	`/api/v2/inventories/`	Create inventory
GET	`/api/v2/inventories/{id}/`	Retrieve inventory
PATCH	`/api/v2/inventories/{id}/`	Update inventory
DELETE	`/api/v2/inventories/{id}/`	Delete inventory
POST	`/api/v2/inventories/{id}/copy/`	Copy inventory

List Inventories

curl -X GET \
  https://awx.example.com/api/v2/inventories/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Inventory

Standard Inventory

curl -X POST \
  https://awx.example.com/api/v2/inventories/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Servers",
    "description": "Production infrastructure",
    "organization": 1,
    "kind": "",
    "variables": "---\nansible_connection: ssh"
  }'

Smart Inventory

curl -X POST \
  https://awx.example.com/api/v2/inventories/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ubuntu Hosts",
    "description": "All Ubuntu servers",
    "organization": 1,
    "kind": "smart",
    "host_filter": "ansible_facts__ansible_distribution__icontains=ubuntu"
  }'

name

string

required

Inventory name

description

string

Inventory description

organization

integer

required

Organization ID

kind

string

default:""

Inventory type: “ (regular), smart, or constructed

host_filter

string

Smart inventory host filter (required for smart inventories)

variables

string

Inventory variables in YAML or JSON format

prevent_instance_group_fallback

boolean

default:"false"

Prevent falling back to default instance group

Retrieve Inventory

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Schema

integer

Inventory ID

name

string

Inventory name

description

string

Inventory description

organization

integer

Organization ID

kind

string

Inventory kind: “, smart, or constructed

host_filter

string

Smart inventory filter

variables

string

Inventory-level variables

has_active_failures

boolean

Whether any hosts have active failures

total_hosts

integer

Total number of hosts

hosts_with_active_failures

integer

Number of hosts with failures

total_groups

integer

Total number of groups

has_inventory_sources

boolean

Whether inventory has sources

total_inventory_sources

integer

Number of inventory sources

inventory_sources_with_failures

integer

Number of failed sources

pending_deletion

boolean

Whether inventory is pending deletion

Links to related resources:

hosts - Inventory hosts
groups - Inventory groups
root_groups - Top-level groups
variable_data - All variables
script - Dynamic inventory script
tree - Inventory tree view
inventory_sources - Inventory sources
update_inventory_sources - Trigger source updates
activity_stream - Activity log
job_templates - Job templates using this inventory
ad_hoc_commands - Ad hoc commands
access_list - Access list
object_roles - Available roles
instance_groups - Instance groups
labels - Inventory labels
copy - Copy endpoint
input_inventories - Input inventories (constructed only)

Update Inventory

curl -X PATCH \
  https://awx.example.com/api/v2/inventories/3/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "variables": "---\nansible_user: admin"
  }'

Delete Inventory

curl -X DELETE \
  https://awx.example.com/api/v2/inventories/3/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Deleting an inventory also deletes all hosts, groups, and inventory sources.

Inventory Hosts

List Hosts

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/hosts/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Add Host

curl -X POST \
  https://awx.example.com/api/v2/inventories/3/hosts/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web01.example.com",
    "description": "Web server 01",
    "variables": "ansible_host: 192.168.1.10"
  }'

Inventory Groups

List Groups

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/groups/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Group

curl -X POST \
  https://awx.example.com/api/v2/inventories/3/groups/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "webservers",
    "description": "Web server group",
    "variables": "http_port: 80"
  }'

Inventory Sources

List Inventory Sources

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/inventory_sources/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Inventory Source

curl -X POST \
  https://awx.example.com/api/v2/inventories/3/inventory_sources/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AWS EC2",
    "description": "EC2 dynamic inventory",
    "source": "ec2",
    "credential": 5,
    "source_vars": "---\nregions:\n  - us-east-1",
    "update_on_launch": true,
    "overwrite": false,
    "overwrite_vars": false
  }'

Update All Inventory Sources

curl -X POST \
  https://awx.example.com/api/v2/inventories/3/update_inventory_sources/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Inventory Script

Get dynamic inventory script output:

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/script/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns Ansible dynamic inventory JSON.

Inventory Tree

Get hierarchical tree view:

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/tree/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Variable Data

Get all inventory variables (inventory + group + host):

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/variable_data/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Ad Hoc Commands

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/ad_hoc_commands/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Job Templates

List job templates using this inventory:

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/job_templates/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Labels

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/labels/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Instance Groups

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/instance_groups/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Object Roles

curl -X GET \
  https://awx.example.com/api/v2/inventories/3/object_roles/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Available roles:

admin_role - Full inventory administration
use_role - Use inventory in job templates
update_role - Trigger inventory source updates
adhoc_role - Run ad hoc commands
read_role - View inventory details

Copy Inventory

curl -X POST \
  https://awx.example.com/api/v2/inventories/3/copy/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Servers Copy"
  }'

Filtering

# By name
?name__icontains=prod

# By organization
?organization=1

# By kind
?kind=smart

# With active failures
?has_active_failures=true

# By total hosts
?total_hosts__gte=10

Ordering

# By name
?order_by=name

# By host count
?order_by=-total_hosts

# By creation date
?order_by=-created

Smart Inventory Host Filters

Smart inventories use advanced filtering:

# Distribution
host_filter=ansible_facts__ansible_distribution__icontains=ubuntu

# Multiple conditions
host_filter=ansible_facts__ansible_distribution=Ubuntu and name__startswith=web

# OR conditions
host_filter=name__startswith=web or name__startswith=db

# Group membership
host_filter=groups__name=webservers

Complete Example

import requests
import json

base_url = "https://awx.example.com/api/v2"
token = "YOUR_TOKEN"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Create inventory
inventory_data = {
    "name": "Development Servers",
    "description": "Dev environment",
    "organization": 1,
    "variables": "---\nansible_connection: ssh\nansible_user: ubuntu"
}

response = requests.post(
    f"{base_url}/inventories/",
    headers=headers,
    data=json.dumps(inventory_data)
)

if response.status_code == 201:
    inventory = response.json()
    inv_id = inventory['id']
    print(f"Created inventory {inv_id}")
    
    # Add hosts
    hosts = ["web01", "web02", "db01"]
    for host_name in hosts:
        host_data = {
            "name": f"{host_name}.example.com",
            "variables": f"server_role: {host_name[:3]}"
        }
        requests.post(
            f"{base_url}/inventories/{inv_id}/hosts/",
            headers=headers,
            data=json.dumps(host_data)
        )
    
    # Create group
    group_data = {
        "name": "webservers",
        "variables": "http_port: 8080"
    }
    requests.post(
        f"{base_url}/inventories/{inv_id}/groups/",
        headers=headers,
        data=json.dumps(group_data)
    )
    
    print(f"Inventory setup complete")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

Getting Started

Core Resources

Job Management

Advanced

Inventories

Overview

Endpoints

List Inventories

Create Inventory

Standard Inventory

Smart Inventory

Retrieve Inventory

Response Schema

Update Inventory

Delete Inventory

Inventory Hosts

List Hosts

Add Host

Inventory Groups

List Groups

Create Group

Inventory Sources

List Inventory Sources

Create Inventory Source

Update All Inventory Sources

Inventory Script

Inventory Tree

Variable Data

Ad Hoc Commands

Job Templates

Labels

Instance Groups

Object Roles

Copy Inventory

Filtering

Ordering

Smart Inventory Host Filters

Complete Example

Build docs developers (and LLMs) love

Getting Started

Core Resources

Job Management

Advanced

​Overview

​Endpoints

​List Inventories

​Create Inventory

​Standard Inventory

​Smart Inventory

​Retrieve Inventory

​Response Schema

​Update Inventory

​Delete Inventory

​Inventory Hosts

​List Hosts

​Add Host

​Inventory Groups

​List Groups

​Create Group

​Inventory Sources

​List Inventory Sources

​Create Inventory Source

​Update All Inventory Sources

​Inventory Script

​Inventory Tree

​Variable Data

​Ad Hoc Commands

​Job Templates

​Labels

​Instance Groups

​Object Roles

​Copy Inventory

​Filtering

​Ordering

​Smart Inventory Host Filters

​Complete Example

Build docs developers (and LLMs) love

Overview

Endpoints

List Inventories

Create Inventory

Standard Inventory

Smart Inventory

Retrieve Inventory

Response Schema

Update Inventory

Delete Inventory

Inventory Hosts

List Hosts

Add Host

Inventory Groups

List Groups

Create Group

Inventory Sources

List Inventory Sources

Create Inventory Source

Update All Inventory Sources

Inventory Script

Inventory Tree

Variable Data

Ad Hoc Commands

Job Templates

Labels

Instance Groups

Object Roles

Copy Inventory

Filtering

Ordering

Smart Inventory Host Filters

Complete Example