1---
2title: "Inventory endpoint"
3layout: default
4canonical: "/puppetdb/latest/api/query/v4/inventory.html"
5---
6# Inventory endpoint
7
8[curl]: ../curl.markdown#using-curl-from-localhost-non-sslhttp
9[subqueries]: ./ast.markdown#subquery-operators
10[dotted]: ./ast.markdown#dot-notation
11[environments]: ./environments.markdown
12[factsets]: ./factsets.markdown
13[catalogs]: ./catalogs.markdown
14[facts]: ./facts.markdown
15[fact-contents]: ./fact-contents.markdown
16[events]: ./events.markdown
17[edges]: ./edges.markdown
18[resources]: ./resources.markdown
19[nodes]: ./nodes.markdown
20[query]: query.markdown
21[ast]: ./ast.markdown
22
23The `/inventory` endpoint enables an alternative query syntax for digging into
24structured facts, and can be used instead of the `facts`, `fact-contents`, and
25`factsets` endpoints for most fact-related queries.
26
27## `/pdb/query/v4/inventory`
28
29This will return an array of `node inventories` matching the given query.
30Inventories for deactivated nodes are not included in the response.
31
32### URL parameters
33
34* `query`: optional. A JSON array containing the query in prefix notation
35  (`["<OPERATOR>", "<FIELD>", "<VALUE>"]`). See the sections below for the
36  supported operators and fields. For general information about queries, see
37  [our guide to query structure.][query]
38
39### Query operators
40
41See [the AST query language page][ast] for the full list of available operators.
42
43> **Note:** This endpoint supports [dot notation][dotted] on the `facts` and
44`trusted` response fields.
45
46### Query fields
47
48* `certname` (string): the name of the node associated with the inventory.
49
50* `timestamp` (string): the time at which PuppetDB received the facts in the inventory.
51
52* `environment` (string): the environment associated with the inventory's
53  certname.
54
55* `facts` (json): a JSON hash of fact names to fact values.
56
57* `trusted` (json): a JSON hash of trusted data for the node.
58
59### Response format
60
61Successful responses will be in `application/json`.
62
63The result will be a JSON array with one entry per certname. Each entry is of
64the form:
65
66    {
67      "certname": <node certname>,
68      "timestamp": <timestamp of fact reception>,
69      "environment": <node environment>,
70      "facts": {
71                 <fact name>: <fact value>,
72                 ...
73               },
74      "trusted": {
75                   <data name>: <data value>,
76                   ...
77                 }
78    }
79
80### Examples
81
82[Using `curl` from localhost][curl]
83
84    curl -X GET http://localhost:8080/pdb/query/v4/inventory -d 'query=["=", "facts.operatingsystem", "Darwin"]'
85
86    [ {
87        "certname" : "mbp.local",
88            "timestamp" : "2016-07-11T20:02:33.190Z",
89            "environment" : "production",
90            "facts" : {
91                "kernel" : "Darwin",
92                "operatingsystem" : "Darwin",
93                "memoryfree" : "3.51 GB",
94                "macaddress_p2p0" : "0e:15:c2:d6:f8:4e",
95                "system_uptime" : {
96                    "days" : 0,
97                    "hours" : 1,
98                    "uptime" : "1:52 hours",
99                    "seconds" : 6733
100                },
101                "netmask_lo0" : "255.0.0.0",
102                "sp_physical_memory" : "16 GB",
103                "operatingsystemrelease" : "14.4.0",
104                "macosx_productname" : "Mac OS X",
105                "sp_boot_mode" : "normal_boot",
106                "macaddress_awdl0" : "6e:31:ef:e6:36:54",
107                ...
108            },
109            "trusted" : {
110                "domain" : "local",
111                "certname" : "mbp.local",
112                "hostname" : "mbp",
113                "extensions" : { },
114                "authenticated" : "remote"
115            }
116    } ]
117