Puppet Forge API

The Puppet Forge API (hereafter referred to as the Forge API) provides quick access to all the data on the Puppet Forge via a RESTful interface. Using the Forge API, you can write scripts and tools that interact with the Puppet Forge website. For example, you can use it to create custom aggregations against module metadata.

Tools like the puppet module tool and librarian-puppet use the Forge API to query and install modules; additional tools, such as Geppetto or Pulp, leverage the API to manage development workflow.

Interact with the API

Try out the Forge API below by crafting queries and seeing the results of your calls immediately. This interactive environment also provides information about the different endpoints and available parameters of the Forge API.

Current Version

The Forge API’s current version is v3. It’s considered regression-stable, meaning that the returned data is guaranteed to match the schema described on this page; however, additional data might be added in the future and existing clients may ignore any properties they do not recognize.

The API currently exposes three resource types: Users, Modules, and Releases. Details for these resources, including available parameters and response schemas, can be found within the interactive UI above this section.

This version of the API does not currently support authentication or any of the operations that would normally require authentication, such as publishing, updating, or deleting modules.

Note: If you need to publish modules using the Forge API, you must file a ticket that includes: a brief statement of purpose, your name and contact information, a simple name we can use to identify your application, and the timeframe for how soon you need access.

Features

The API is accessed over HTTPS via the forgeapi.puppetlabs.com domain. All data is returned in JSON format.
Blank fields are included as null.
Nested resources use an abbreviated representation. A link to the full representation for the resource is always included.
All timestamps are returned in ISO 8601 format: YYYY-MM-DD HH:MM:SS ±HHMM.
The HTTP response headers include caching hints for conditional requests.

Errors

The Puppet Forge API follows RFC 2616 and RFC 6585.

Error responses are served with a 4xx or 5xx status code, and are sent as a JSON hash with a message key, describing the cause of the failure.

 { "message": "Cannot parse request body as JSON" }

If the error has more specific causes (e.g. trying to update a User account with invalid data), an errors key will be provided containing a list of specific problems with the request.

 {
      "message": "Validation Failed",
      "errors": [
        {
          "resource": "User",
          "field": "username",
          "code": "not_unique"
        },
        {
          "resource": "User",
          "field": "display_name",
          "code": "missing"
        }
      ]
    }

User-Agent Required

All API requests must include a valid User-Agent header. Requests with no User-Agent header will be rejected. The User-Agent header helps identify your application or library, so we can communicate with you if necessary. If your use of the API is informal or personal, we recommend using your username as the header.

User-Agent headers are a list of one or more product descriptions, generally taking this form:

<name-without-spaces>/<version> (comments)

For example, the following are all useful User-Agent values:

MyApplication/0.0.0 Her/0.6.8 Faraday/0.8.8 Ruby/1.9.3-p194 (i486-linux)
My-Library-Name/1.2.4
myusername

↑ Back to top