Puppet User Operations API

openapi: 3.0.2
info:
  title: Puppet Forge v3 Module Operations User Operations API
  version: '29'
  description: "## Introduction\nThe Puppet Forge API (hereafter referred to as the Forge API) provides quick access to all the\ndata on the Puppet Forge via a RESTful interface. Using the Forge API, you can write scripts and\ntools that interact with the Puppet Forge website.\n\nThe Forge API's current version is `v3`. It is considered regression-stable, meaning that the returned\ndata is guaranteed to include the fields described in the schemas on this page; however, additional data\nmight be added in the future and clients must ignore any properties they do not recognize.\n\n## OpenAPI Specification\nThe Puppet Forge v3 API is described by an\n[OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md) formatted\nspecification file. The most up-to-date version of this specification file can be accessed at\n[https://forgeapi.puppet.com/v3/openapi.json](/v3/openapi.json).\n\n## Features\n* The API is accessed over HTTPS via either the `forgeapi.puppet.com` (IPv4 or IPv6). All data is returned in JSON\n  format.\n* Blank fields are included as `null`.\n* Nested resources may use an abbreviated representation. A link to the full representation for the\n  resource is always included.\n* All timestamps in JSON responses are returned in ISO 8601 format: `YYYY-MM-DD HH:MM:SS ±HHMM`.\n* The HTTP response headers include caching hints for conditional requests.\n\n## Concepts and Terminology\n* **Module**: Modules are self-contained bundles of code and data with a specific directory structure. Modules are identified by a combination of the author's username and the module's name, separated by a hyphen. For example: `puppetlabs-apache`\n* **Release**: A single, specific version of a module is called a Release. Releases are identified by a combination of the module identifier (see above) and the Release version, separated by a hyphen. For example: `puppetlabs-apache-4.0.0`\n\n## Errors\nThe Puppet Forge API follows [RFC 2616](https://tools.ietf.org/html/rfc2616) and\n[RFC 6585](https://tools.ietf.org/html/rfc6585).\n\nError responses are served with a `4xx` or `5xx` status code, and are sent as a JSON document with a content type\nof `application/json`. The error document contains the following top-level keys and values:\n\n  * `message`: a string value that summarizes the problem\n  * `errors`: a list (array) of strings containing additional details describing the underlying cause(s) of the\n    failure\n\nAn example error response is shown below:\n\n```json\n{\n  \"message\": \"400 Bad Request\",\n  \"errors\": [\n    \"Cannot parse request body as JSON\"\n  ]\n}\n```\n\n## User-Agent Required\nAll API requests must include a valid `User-Agent` header. Requests with no `User-Agent` header will\nbe rejected. The `User-Agent` header helps identify your application or library, so we can communicate\nwith you if necessary. If your use of the API is informal or personal, we recommend using your username\nas the value for the `User-Agent` header.\n\nUser-Agent headers are a list of one or more product descriptions, generally taking this form:\n\n```\n<name-without-spaces>/<version> (comments)\n```\n\nFor example, the following are all useful User-Agent values:\n\n```\nMyApplication/0.0.0 Her/0.6.8 Faraday/0.8.8 Ruby/1.9.3-p194 (i386-linux)\nMy-Library-Name/1.2.4\nmyusername\n```\n\n## Hostname Configuration\nMost tools that interact with the Forge API allow specification of the hostname to use. You can configure\na few common tools to use a specified hostname as follows:\n\nFor **Puppet Enterprise** users, in [r10k](https://puppet.com/docs/pe/latest/r10k_customize_config.html#r10k_configuring_forge_settings)\nor [Code Manager](https://puppet.com/docs/pe/latest/code_mgr_customizing.html#config_forge_settings), specify\n`forge_settings` in Hiera:\n```\npe_r10k::forge_settings:\n  baseurl: 'https://forgeapi.puppet.com'\n```\nor\n```\npuppet_enterprise::master::code_manager::forge_settings:\n  baseurl: 'https://forgeapi.puppet.com'\n```\n<br />\n\nIf you are an **open source Puppet** user using r10k, you'll need to [edit your r10k.yaml\ndirectly](https://github.com/puppetlabs/r10k/blob/main/doc/dynamic-environments/configuration.mkd#forge):\n```\nforge:\n  baseurl: 'https://forgeapi.puppet.com'\n```\nor set the appropriate class param for the [open source r10k module](https://forge.puppet.com/puppet/r10k#forge_settings):\n```\n$forge_settings = {\n  'baseurl' => 'https://forgeapi.puppet.com',\n}\n```\n<br />\n\nIn [**Bolt**](https://puppet.com/docs/bolt/latest/bolt_installing_modules.html#install-forge-modules-from-an-alternate-forge), set a `baseurl` for the Forge in `bolt-project.yaml`:\n```\nmodule-install:\n  forge:\n    baseurl: https://forgeapi.puppet.com\n```\n<br />\n\nUsing `puppet config`:\n```\n$ puppet config set module_repository https://forgeapi.puppet.com\n```\n"
servers:
- url: https://forgeapi.puppet.com
tags:
- name: User Operations
paths:
  /v3/users:
    get:
      operationId: getUsers
      summary: List users
      description: 'Provides information about Puppet Forge user accounts. By default, results are returned in alphabetical

        order by username and paginated with 20 users per page. It''s also possible to sort by number of published

        releases, total download counts for all the user''s modules, or by the date of the user''s latest release.

        All parameters are optional.

        '
      tags:
      - User Operations
      parameters:
      - $ref: '#/components/parameters/limitQuery'
      - $ref: '#/components/parameters/offsetQuery'
      - in: query
        name: sort_by
        description: Desired order in which to return results
        schema:
          type: string
          enum:
          - username
          - releases
          - downloads
          - latest_release
      - $ref: '#/components/parameters/withHTML'
      - $ref: '#/components/parameters/includeFields'
      - $ref: '#/components/parameters/excludeFields'
      - $ref: '#/components/parameters/ifModifiedSince'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    allOf:
                    - $ref: '#/components/schemas/Pagination'
                    - properties:
                        first:
                          example: /v3/users?offset=0&limit=20
                        current:
                          example: /v3/users?offset=0&limit=20
                        next:
                          example: /v3/users?offset=20&limit=20
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
        '304':
          $ref: '#/components/responses/NotModified'
  /v3/users/{user_slug}:
    get:
      operationId: getUser
      summary: Fetch user
      description: 'Returns data for a single User resource identified by the user''s `slug` value.

        '
      tags:
      - User Operations
      parameters:
      - in: path
        name: user_slug
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]+$
        required: true
        description: Unique textual identifier (slug) of the User resource to retrieve
        example: puppetlabs
      - $ref: '#/components/parameters/withHTML'
      - $ref: '#/components/parameters/includeFields'
      - $ref: '#/components/parameters/excludeFields'
      - $ref: '#/components/parameters/ifModifiedSince'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    User:
      type: object
      properties:
        uri:
          type: string
          format: URL path and query string
          description: Relative URL for this User resource
          example: /v3/users/puppetlabs
        slug:
          type: string
          pattern: ^[a-zA-Z0-9]+$
          description: Unique textual identifier for this User resource
          example: puppetlabs
        gravatar_id:
          type: string
          description: Gravatar ID, learn more at [https://gravatar.com/]()
          example: fdd009b7c1ec96e088b389f773e87aec
        username:
          type: string
          description: Username for this User resource
          example: puppetlabs
        display_name:
          type: string
          description: Free form display name for this User resource
          example: Puppet
        release_count:
          type: integer
          description: Total number of module releases (versions) published under this User
          example: 1619
        module_count:
          type: integer
          description: Total number of unique modules published under this User
          example: 178
        created_at:
          type: string
          format: iso8601
          description: Date and time this User resource was created
          example: 2010-05-19 05:46:26 -0700
        updated_at:
          type: string
          format: iso8601
          description: Date and time this User resource was last modified
          example: 2018-09-18 11:46:25 -0700
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          example: 20
          description: Maximum number of results per page
        offset:
          type: integer
          example: 0
          description: Current page's offset from the beginning of the result set
        first:
          type: string
          format: URL path and query string
          example: /v3/<resource>?offset=0&limit=20
          description: Relative URL for the first page of the result set
        previous:
          type: string
          format: URL path and query string
          nullable: true
          example: null
          description: Relative URL for the previous page of the result set, or `null` if this is the first page
        current:
          type: string
          format: URL path and query string
          example: /v3/<resource>?offset=0&limit=20
          description: Relative URL for the current page of the result set
        next:
          type: string
          format: URL path and query string
          nullable: true
          example: /v3/<resource>?offset=20&limit=20
          description: Relative URL for the next page of the result set, or `null` if this is the last page
        total:
          type: integer
          example: 100
          description: Total number of all results
  parameters:
    includeFields:
      in: query
      name: include_fields
      description: List of top level keys to include in response object, only applies to fields marked 'optional'
      schema:
        type: array
        items:
          type: string
      style: spaceDelimited
      explode: false
      example:
      - docs
    excludeFields:
      in: query
      name: exclude_fields
      description: List of top level keys to exclude from response object
      schema:
        type: array
        items:
          type: string
      style: spaceDelimited
      explode: false
      example:
      - readme
      - changelog
      - license
      - reference
    withHTML:
      in: query
      name: with_html
      description: Render markdown files (README, REFERENCE, etc.) to HTML before returning results
      schema:
        type: boolean
    limitQuery:
      in: query
      name: limit
      description: The numbers of items to return per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    ifModifiedSince:
      in: header
      name: If-Modified-Since
      schema:
        type: string
        format: rfc2616 httpdate
        description: 'Only processes the request if the resource or list of resources has changed since the given time,

          otherwise returns a `304 Not Modified` response

          '
        example: Mon, 19 Feb 2019 10:15:08 GMT
    offsetQuery:
      in: query
      name: offset
      description: The number of items to skip before starting to collect the result set
      schema:
        type: integer
        minimum: 0
        default: 0
  responses:
    NotModified:
      description: Not Modified
      headers:
        Last-Modified:
          schema:
            type: string
            format: rfc2616 httpdate
            description: Date and time that this response last changed
            example: Mon, 19 Feb 2019 10:15:08 GMT
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: 404 Not Found
              errors:
                type: array
                items:
                  type: string
                example:
                - The requested resource could not be found
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: 400 Bad Request
              errors:
                type: array
                items:
                  type: string
                example:
                - '''puppetlabs-apache4.5.0'' is not a valid release slug'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: 'Authorization: Bearer <api_key>'
      description: 'Some of the Forge API endpoints require authentication in the form of a user API key. API keys may be created and revoked from a user''s profile on the [Forge website](https://forge.puppet.com), where other profile details are managed.


        To perform actions that require API key authentication, the key must be present in an `Authorization` header with the request. The header should be formatted as:


        ```

        Authorization: Bearer <api_key>

        ```


        If a request is made to a protected endpoint without the required `Authorization` header a `401 Unauthorized` response will be returned. If an `Authorization` header is sent with the request, but the provided key is invalid or has insufficent permissions a `403 Forbidden` response will be returned.

        '