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 operators

See the AST query language page 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.

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