Catalogs endpoint

• 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 info about queries, see our guide to query structure.

If a query parameter is not provided, all results will be returned.

See the AST query language page.

• certname (string): the certname associated with the catalog.

• version (string): an arbitrary string that uniquely identifies each catalog for a node.

• environment (string): the environment associated with the catalog's certname.

• transaction_uuid (string): a string used to tie a catalog to a report from the same Puppet run (use catalog_uuid when running off a cached catalog).

• catalog_uuid (string): a string used to tie a catalog to a report to the catalog used from that Puppet run.

• code_id (string): a string used to tie a catalog to the Puppet code which generated the catalog.

• hash (string): SHA-1 hash of the resources of associated with a node's most recent catalog.

• producer_timestamp (string): a string representing the time at which the replace_catalog command for a given catalog was submitted from the Puppet Server.

• producer (string): the certname of the Puppet Server that sent the catalog to PuppetDB.

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

• producers: the Puppet Server that sent the catalog to PuppetDB.

• environments: environment for a catalog.

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>,
  "version" : <catalog version>,
  "environment" : <catalog environment>,
  "hash" : <sha1 sum of catalog resources>,
  "transaction_uuid" : <string to identify puppet run>,
  "code_id" : <string to identify puppet code>,
  "producer_timestamp": <time of transmission by Puppet Server>,
  "producer": <Puppet Server certname>
  "resources" : <expanded resources>,
  "edges" : <expanded edges>
}

The <expanded resources> object is of the following form:

{
  "href": <url>,
  "data": [ {
    "certname": <string>,
    "resource": <string>,
    "type": <string>,
    "title": <sttring>,
    "exported": <boolean>,
    "tags": [<tags>, ...],
    "file": <string>,
    "line": <number>,
    "parameters": <any>
  } ... ]
}

In parameters map, any rich data values will appear as readable strings.

The <expanded edges> object is of the follow form:

{
  "href": <url>,
  "data": [ {
    "relationship": <string>,
    "source_title": <string>,
    "source_type": <string>,
    "target_title": <string>,
    "target_type": <string>
  } ... ]
}

This query will return the complete list of catalogs:

curl -X GET http://localhost:8080/pdb/query/v4/catalogs

[ {
  "certname" : "yo.delivery.puppetlabs.net",
  "hash" : "62cdc40a78750144b1e1ee06638ac2dd0eeb9a46",
  "version" : "e4c339f",
  "transaction_uuid" : "53b72442-3b73-11e3-94a8-1b34ef7fdc95",
  "code_id" : null,
  "producer_timestamp": "2014-10-13T20:46:00.000Z",
  "producer": "dad.puppetlabs.net",
  "environment" : "production",
  "edges" : {...},
  "resources" : {...}
},
{
  "certname" : "foo.delivery.puppetlabs.net",
  "hash" : "e1a4610ecbb3483fa5e637f42374b2cc46d06474",
  "version" : "449720",
  "transaction_uuid" : "9a3c8da6-f48c-4567-b24e-ddae5f80a6c6",
  "code_id" : null,
  "producer_timestamp": "2014-11-20T02:15:20.861Z",
  "producer": "mom.puppetlabs.net",
  "environment" : "production",
  "edges" : {...},
  "resources" : {...}
} ]

This query will return all catalogs with producer_timestamp after 2014-11-19:

curl -X GET http://localhost:8080/pdb/query/v4/catalogs \
  --data-urlencode 'query=[">","producer_timestamp","2014-11-19"]'

[ {
  "certname" : "foo.delivery.puppetlabs.net",
  "hash" : "e1a4610ecbb3483fa5e637f42374b2cc46d06474",
  "version" : "449720",
  "transaction_uuid" : "9a3c8da6-f48c-4567-b24e-ddae5f80a6c6",
  "code_id" : null,
  "producer_timestamp": "2014-11-20T02:15:20.861Z",
  "producer": "mom.puppetlabs.net",
  "environment" : "production",
  "edges" : {...},
  "resources" : {...}
} ]

curl -X GET http://localhost:8080/pdb/query/v4/catalogs/foo.localdomain

{
 "certname" : "yo.delivery.puppetlabs.net",
 "hash" : "62cdc40a78750144b1e1ee06638ac2dd0eeb9a46",
 "version" : "e4c339f",
 "transaction_uuid" : "53b72442-3b73-11e3-94a8-1b34ef7fdc95",
 "code_id" : null,
 "catalog_uuid" : null,
 "producer_timestamp": "2014-10-13T20:46:00.000Z",
 "producer": "dad.puppetlabs.net",
 "environment" : "production",
 "edges" : {...},
 "resources" : {...}
}

curl -X GET http://localhost:8080/pdb/query/v4/catalogs/my_fake_hostname

{
  "error" : "Could not find catalog for my_fake_hostname"
}

This route is an extension of the edges endpoint. It uses the same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.

This route is an extension of the /resources endpoint. It uses the exact same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.

This route is an extension of the /pdb/query/v4/catalogs endpoint. It uses the exact same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.

Here is a list of related entities that can be used to constrain the result set using implicit subqueries. For more information consult the documentation for subqueries.

• nodes: Node for a catalog.

• environments: Environment for a catalog.