Since PuppetDB collects lots of data from Puppet, it’s an ideal platform for new tools and applications that use that data. You can use the HTTP API described in these pages to interact with PuppetDB’s data.


PuppetDB’s API uses a Command/Query Responsibility Separation (CQRS) pattern. This means:

  • Data can be queried using a standard REST-style API. Queries are processed immediately.
  • When making changes to data (facts, catalogs, etc), you must send an explicit command (as opposed to submitting data without comment and letting the receiver determine intent). Commands are processed asynchronously in FIFO order.

The PuppetDB API consists of the following parts:


PuppetDB 1.3 (and later) supports versions 1 and 2 of the query API. Version 1 is backwards-compatible with PuppetDB 1.0.x, but version 2 has significant new capabilities, including subqueries.

PuppetDB’s data can be queried with a REST API.

The available query endpoints are documented in the pages linked below.

Query Endpoints

Version 3

Version 3 of the query API added new endpoints, and introduces paging and sorting operations. This is the current stable API.

Version 4 (Experimental)

Version 4 of the query API is currently experimental and may change without notice. For stability it is recommended to use the v3 query API.

Version 2 (Deprecated)

Version 2 of the query API is deprecated and will be retired soon. For stability it is recommended to use the v3 query API instead.


Commands are sent via HTTP but do not use a REST-style interface.

PuppetDB supports a relatively small number of commands. The command submission interface and the available commands are all described at the commands page:

Unlike the query API, these commands are generally only useful to Puppet itself, and all format conversion and command submission is handled by the PuppetDB terminus plugins on your puppet master.

The “replace” commands all require data in one of the wire formats described below.

Wire Formats

All of PuppetDB’s “replace” commands contain payload data, which must be in one of the following formats. These formats are also linked from the commands that use them.

Back to top
The page rank or the 1 our of 5 rating a user has given the page.
The email address of the user submitting feedback.
The URL of the page being ranked/rated.