Documentation

15. Group List API Endpoint

Make a GET request to this resource to retrieve the list of groups.

GET /api/v1/groups/
HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
X-API-Time: 0.049s

The resulting data structure contains:

{
    "count": 99,
    "next": null,
    "previous": null,
    "results": [
        ...
    ]
}

The count field indicates the total number of groups found for the given query. The next and previous fields provides links to additional results if there are more than will fit on a single page. The results list contains zero or more group records.

15.1. Results

Each group data structure includes the following fields:

  • id: Database ID for this group. (integer)
  • type: Data type for this group. (multiple choice)
    • group: Group
  • url: URL for this group. (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 group was created. (datetime)
  • modified: Timestamp when this group was last modified. (datetime)
  • name: (string)
  • description: (string)
  • inventory: (field)
  • variables: Group variables in JSON or YAML format. (string)
  • has_active_failures: Flag indicating whether this group has any hosts with active failures. (boolean)
  • total_hosts: Total number of hosts directly or indirectly in this group. (integer)
  • hosts_with_active_failures: Number of hosts in this group with active failures. (integer)
  • total_groups: Total number of child groups contained within this group. (integer)
  • groups_with_active_failures: Number of child groups within this group that have active failures. (integer)
  • has_inventory_sources: Flag indicating whether this group was created/updated from any external inventory sources. (boolean)

15.2. Create Groups

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

  • name: (string, required)
  • description: (string, default=””)
  • inventory: (field, required)
  • variables: Group variables in JSON or YAML format. (string, default=””)

15.3. 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:

name Group List
description # List Groups: Make a GET request to this resource to retrieve the list of groups.
renders
0 application/json
1 text/html
parses
0 application/json
added_in_version 1.2
actions
POST
name
type string
required
true
label name
max_length 512
description
type string
required
false
label description
default (Empty Text)
inventory
type field
required
true
variables
type string
required
false
label variables
help_text Group variables in JSON or YAML format.
default (Empty Text)
GET
id
type integer
label ID
help_text Database ID for this group.
type
type multiple choice
help_text Data type for this group.
choices
0
0 group
1 Group
url
type string
help_text URL for this group.
related
type object
help_text Data structure with URLs of related resources.
summary_fields
type object
help_text Data structure with name/description for related resources.
created
type datetime
help_text Timestamp when this group was created.
modified
type datetime
help_text Timestamp when this group was last modified.
name
type string
label name
description
type string
label description
inventory
type field
variables
type string
label variables
help_text Group variables in JSON or YAML format.
has_active_failures
type boolean
label has active failures
help_text Flag indicating whether this group has any hosts with active failures.
total_hosts
type integer
label total hosts
help_text Total number of hosts directly or indirectly in this group.
hosts_with_active_failures
type integer
label hosts with active failures
help_text Number of hosts in this group with active failures.
total_groups
type integer
label total groups
help_text Total number of child groups contained within this group.
groups_with_active_failures
type integer
label groups with active failures
help_text Number of child groups within this group that have active failures.
has_inventory_sources
type boolean
label has inventory sources
help_text Flag indicating whether this group was created/updated from any external inventory sources.
types
0 group
search_fields
0 description
1 name