PyPI Stats API — Downloads

naftiko: 1.0.0-alpha2
info:
  label: PyPI Stats API — Downloads
  description: 'PyPI Stats API — Downloads. 5 operations. Lead operation: Get overall download time series. Self-contained
    Naftiko capability covering one Pypi business surface.'
  tags:
  - Pypi
  - Downloads
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    PYPI_API_KEY: PYPI_API_KEY
capability:
  consumes:
  - type: http
    namespace: stats-downloads
    baseUri: https://pypistats.org/api
    description: PyPI Stats API — Downloads business capability. Self-contained, no shared references.
    resources:
    - name: packages-package-overall
      path: /packages/{package}/overall
      operations:
      - name: getoveralldownloads
        method: GET
        description: Get overall download time series
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: mirrors
          in: query
          type: string
          description: Filter by whether downloads from known mirrors are included. Use true to include only mirror downloads,
            false to exclude them.
    - name: packages-package-python_major
      path: /packages/{package}/python_major
      operations:
      - name: getdownloadsbypythonmajor
        method: GET
        description: Get downloads by Python major version
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: version
          in: query
          type: string
          description: Filter to a specific Python major version. If omitted, returns all versions including null.
    - name: packages-package-python_minor
      path: /packages/{package}/python_minor
      operations:
      - name: getdownloadsbypythonminor
        method: GET
        description: Get downloads by Python minor version
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: version
          in: query
          type: string
          description: Filter to a specific Python minor version. If omitted, returns all versions including null.
    - name: packages-package-recent
      path: /packages/{package}/recent
      operations:
      - name: getrecentdownloads
        method: GET
        description: Get recent download counts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: period
          in: query
          type: string
          description: Filter to a specific time period. If omitted, returns all three periods.
    - name: packages-package-system
      path: /packages/{package}/system
      operations:
      - name: getdownloadsbysystem
        method: GET
        description: Get downloads by operating system
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: os
          in: query
          type: string
          description: Filter to a specific operating system. If omitted, returns all operating systems including null.
  exposes:
  - type: rest
    namespace: stats-downloads-rest
    port: 8080
    description: REST adapter for PyPI Stats API — Downloads. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/packages/{package}/overall
      name: packages-package-overall
      description: REST surface for packages-package-overall.
      operations:
      - method: GET
        name: getoveralldownloads
        description: Get overall download time series
        call: stats-downloads.getoveralldownloads
        with:
          mirrors: rest.mirrors
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/packages/{package}/python-major
      name: packages-package-python-major
      description: REST surface for packages-package-python_major.
      operations:
      - method: GET
        name: getdownloadsbypythonmajor
        description: Get downloads by Python major version
        call: stats-downloads.getdownloadsbypythonmajor
        with:
          version: rest.version
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/packages/{package}/python-minor
      name: packages-package-python-minor
      description: REST surface for packages-package-python_minor.
      operations:
      - method: GET
        name: getdownloadsbypythonminor
        description: Get downloads by Python minor version
        call: stats-downloads.getdownloadsbypythonminor
        with:
          version: rest.version
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/packages/{package}/recent
      name: packages-package-recent
      description: REST surface for packages-package-recent.
      operations:
      - method: GET
        name: getrecentdownloads
        description: Get recent download counts
        call: stats-downloads.getrecentdownloads
        with:
          period: rest.period
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/packages/{package}/system
      name: packages-package-system
      description: REST surface for packages-package-system.
      operations:
      - method: GET
        name: getdownloadsbysystem
        description: Get downloads by operating system
        call: stats-downloads.getdownloadsbysystem
        with:
          os: rest.os
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: stats-downloads-mcp
    port: 9090
    transport: http
    description: MCP adapter for PyPI Stats API — Downloads. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: get-overall-download-time-series
      description: Get overall download time series
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stats-downloads.getoveralldownloads
      with:
        mirrors: tools.mirrors
      outputParameters:
      - type: object
        mapping: $.
    - name: get-downloads-python-major-version
      description: Get downloads by Python major version
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stats-downloads.getdownloadsbypythonmajor
      with:
        version: tools.version
      outputParameters:
      - type: object
        mapping: $.
    - name: get-downloads-python-minor-version
      description: Get downloads by Python minor version
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stats-downloads.getdownloadsbypythonminor
      with:
        version: tools.version
      outputParameters:
      - type: object
        mapping: $.
    - name: get-recent-download-counts
      description: Get recent download counts
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stats-downloads.getrecentdownloads
      with:
        period: tools.period
      outputParameters:
      - type: object
        mapping: $.
    - name: get-downloads-operating-system
      description: Get downloads by operating system
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stats-downloads.getdownloadsbysystem
      with:
        os: tools.os
      outputParameters:
      - type: object
        mapping: $.