• Puppet 6 Platform
  • Quick start guides
  • Installing and upgrading
  • Configuration
  • Important directories and files
  • Environments
  • Modules
  • Puppet’s services and tools
  • Puppet Server
  • The Puppet language
  • Writing custom functions
  • Hiera
  • Facter
  • Resource types
  • Reports: Tracking Puppet’s activity
  • Extensions for assigning classes to nodes
  • Misc. references
  • Man pages
  • SSL and certificates
  • Adding file server mount points
  • Details about Puppet’s internals
  • Experimental features

Puppet Server: Puppet API: Catalog

This version is out of date. For current versions, see Puppet packages and versions.

The catalog API returns a compiled catalog for the node specified in the request, making use of provided metadata like facts or environment if specified. If not specified, it will attempt to fetch this data from Puppet’s configured sources (usually PuppetDB or a node classifier). The returned catalog is in JSON format, ready to be parsed and applied by an agent.

POST /puppet/v4/catalog

(Introduced in Puppet Server 6.3.0)

The input data for the catalog to be compiled is submitted as a JSON body with the following form:

  "certname": "<node name>",
  "persistence": { "facts": <true/false>, "catalog": <true/false> },
  "environment": "<environment name>",
  # The rest are optional:
  "facts": { "values": { "<fact name>": <fact value>, ... } },
  "trusted_facts": { "values": { "<fact name>": <fact value>, ... } },
  "transaction_uuid": "<uuid string>",
  "job_id": "<id string>",
  "options": { "prefer_requested_environment": <true/false>,
               "capture_logs": <true/false> }

certname (required)

The name of the node for which to compile the catalog.

persistence (required)

A hash containing two required keys, facts and catalog, which when set to true will cause the facts and reports to be stored in PuppetDB, or discarded if set to false.

environment (required)

The name of the environment for which to compile the catalog. If prefer_requested_environemnt is true, override the classified environment with this param. If it is false, only respect this if the classifier allows an agent-specified environment.


A hash with a required values key, containing a hash of all the facts for the node. If not provided, Puppet will attempt to fetch facts for the node from PuppetDB.


A hash with a required values key containing a hash of the trusted facts for a node. In a normal agent’s catalog request, these would be extracted from the cert, but this endpoint does not require a cert for the node whose catalog is being compiled. If not provided, Puppet will attempt to fetch the trusted facts for the node from PuppetDB or from the provided facts hash.


The id for tracking the catalog compilation and report submission.


The id of the orchestrator job that triggered this run.


A hash of options beyond direct input to catalogs.

prefer_requested_environment Whether to always override a node’s classified environment with the one supplied in the request. If this is true and no environment is supplied, fall back to the classified environment, or finally, ‘production’.

capture_logs Whether to return the errors and warnings that occurred during compilation alongside the catalog in the response body.


The catalog response body conforms to the catalog schema.


All requests made to the catalog API are authorized using the Trapperkeeper-based auth.conf. For more information about the Puppet Server authorization process and configuration settings, see the auth.conf documentation.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.