• General information
  • Installation
  • Configuration
  • Usage/admin
  • Troubleshooting
  • PQL - Puppet Query Language
  • API
  • Query API version 4
  • Extensions API version 1 (PE-only)
  • Admin API version 1
  • Command API version 1
  • Status API version 1
  • Metadata API version 1
  • Metrics API version 1
  • Wire formats

Admin commands endpoint


The /cmd endpoint can be used to trigger PuppetDB maintenance operations. Only one maintenance operation can be running at a time. Any request received while an operation is already in progress will return an HTTP conflict status (409).

POST /pdb/admin/v1/cmd

The maintenance operations must be triggered by a POST.

Request format

The POST request should specify Content-Type: application/json and the request body should look like this:

{"version" : 1, "payload" : [REQUESTED_OPERATION, ...]}

where valid REQUESTED_OPERATIONs are "expire_nodes", "purge_nodes", "purge_reports", "gc_packages", and "other". In addition, a purge_nodes operation can be structured like this to specify a batch_limit:

["purge_nodes" {"batch_limit" : 50}]

When specified, the batch_limit restricts the maximum number of nodes purged to the value specified, and if not specified, the limit will be the node-purge-gc-batch-limit.

An empty payload vector requests all maintenance operations.

URL parameters

  • The POST endpoint accepts no URL parameters.

Response format

The response type will be application/json, and upon success will include this JSON map:

{"ok": true}

If any other maintenance operation is already in progress the HTTP response status will be 409 (conflict), will include a map like this

{"kind": "conflict",
 "msg": "Another cleanup is already in progress",
 "details": null}

and no additional maintenance will be performed. The msg and details may or may not vary, but the kind will always be “conflict”.


Using curl from localhost:

$ curl -X POST http://localhost:8080/pdb/admin/v1/cmd \
       -H 'Accept: application/json' \
       -H 'Content-Type: application/json' \
       -d '{"command": "clean",
            "version": 1,
            "payload": ["expire_nodes", "purge_nodes"]}'
{"ok": true}
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.