Documentation

16. Host List API Endpoint

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

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

The resulting data structure contains:

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

The count field indicates the total number of hosts 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 host records.

16.1. Results

Each host data structure includes the following fields:

  • id: Database ID for this host. (integer)
  • type: Data type for this host. (multiple choice)
    • host: Host
  • url: URL for this host. (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 host was created. (datetime)
  • modified: Timestamp when this host was last modified. (datetime)
  • name: (string)
  • description: (string)
  • inventory: (field)
  • enabled: Is this host online and available for running jobs? (boolean)
  • instance_id: (string)
  • variables: Host variables in JSON or YAML format. (string)
  • has_active_failures: Flag indicating whether the last job failed for this host. (boolean)
  • has_inventory_sources: Flag indicating whether this host was created/updated from any external inventory sources. (boolean)
  • last_job: (field)
  • last_job_host_summary: (field)

16.2. Create Hosts

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

  • name: (string, required)
  • description: (string, default=””)
  • inventory: (field, required)
  • enabled: Is this host online and available for running jobs? (boolean, default=True)
  • instance_id: (string, default=””)
  • variables: Host variables in JSON or YAML format. (string, default=””)
  • last_job: (field, default=None)
  • last_job_host_summary: (field, default=None)

16.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 Host List
description # List Hosts: Make a GET request to this resource to retrieve the list of hosts.
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
enabled
type boolean
required
false
label enabled
help_text Is this host online and available for running jobs?
default
true
instance_id
type string
required
false
label instance id
max_length 100
default (Empty Text)
variables
type string
required
false
label variables
help_text Host variables in JSON or YAML format.
default (Empty Text)
last_job
type field
required
false
default null
last_job_host_summary
type field
required
false
default null
GET
id
type integer
label ID
help_text Database ID for this host.
type
type multiple choice
help_text Data type for this host.
choices
0
0 host
1 Host
url
type string
help_text URL for this host.
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 host was created.
modified
type datetime
help_text Timestamp when this host was last modified.
name
type string
label name
description
type string
label description
inventory
type field
enabled
type boolean
label enabled
help_text Is this host online and available for running jobs?
instance_id
type string
label instance id
variables
type string
label variables
help_text Host variables in JSON or YAML format.
has_active_failures
type boolean
label has active failures
help_text Flag indicating whether the last job failed for this host.
has_inventory_sources
type boolean
label has inventory sources
help_text Flag indicating whether this host was created/updated from any external inventory sources.
last_job
type field
last_job_host_summary
type field
types
0 host
search_fields
0 description
1 name