PuppetDB 4.3: Inventory endpoint

Included in Puppet Enterprise 2017.1. A newer version is available; see the version menu above for details.

The /inventory endpoint enables an alternative query syntax for digging into structured facts, and can be used instead of the facts, fact-contents, and factsets endpoints for most fact-related queries.


This will return an array of node inventories matching the given query. Inventories for deactivated nodes are not included in the response.

URL parameters

  • query: optional. A JSON array containing the query in prefix notation (["<OPERATOR>", "<FIELD>", "<VALUE>"]). See the sections below for the supported operators and fields. For general information about queries, see [our guide to query structure.][query]

Query operators

See [the AST query language page][ast] for the full list of available operators.

Note: This endpoint supports dot notation on the facts and trusted response fields.

Query fields

  • certname (string): the name of the node associated with the inventory.

  • timestamp (string): the time at which PuppetDB received the facts in the inventory.

  • environment (string): the environment associated with the inventory’s certname.

  • facts (json): a JSON hash of fact names to fact values.

  • trusted (json): a JSON hash of trusted data for the node.

Subquery relationships

The following list contains related entities that can be used to constrain the result set with implicit subqueries. For more information, consult the documentation for subqueries.

  • environments: the environment where a node inventory exists.
  • factsets: the factset corresponding to a node inventory’s certname.
  • catalogs: the catalog corresponding to a node inventory’s certname.
  • facts: the facts corresponding to a node inventory’s certname.
  • fact-contents: the fact contents corresponding to a node inventory’s certname.
  • events: the events corresponding to a node inventory’s certname.
  • edges: the catalog edges corresponding to a node inventory’s certname.
  • resources: the resources corresponding to a node inventory’s certname.
  • nodes: the node corresponding to an inventory.

Response format

Successful responses will be in application/json.

The result will be a JSON array with one entry per certname. Each entry is of the form:

  "certname": <node certname>,
  "timestamp": <timestamp of fact reception>,
  "environment": <node environment>,
  "facts": {
             <fact name>: <fact value>,
  "trusted": {
               <data name>: <data value>,


Using curl from localhost

curl -X GET http://localhost:8080/pdb/query/v4/inventory -d 'query=["=", "facts.operatingsystem", "Darwin"]'

[ {
    "certname" : "mbp.local",
        "timestamp" : "2016-07-11T20:02:33.190Z",
        "environment" : "production",
        "facts" : {
            "kernel" : "Darwin",
            "operatingsystem" : "Darwin",
            "memoryfree" : "3.51 GB",
            "macaddress_p2p0" : "0e:15:c2:d6:f8:4e",
            "system_uptime" : {
                "days" : 0,
                "hours" : 1,
                "uptime" : "1:52 hours",
                "seconds" : 6733
            "netmask_lo0" : "",
            "sp_physical_memory" : "16 GB",
            "operatingsystemrelease" : "14.4.0",
            "macosx_productname" : "Mac OS X",
            "sp_boot_mode" : "normal_boot",
            "macaddress_awdl0" : "6e:31:ef:e6:36:54",
        "trusted" : {
            "domain" : "local",
            "certname" : "mbp.local",
            "hostname" : "mbp",
            "extensions" : { },
            "authenticated" : "remote"
} ]

↑ Back to top