PyPI JSON API

openapi: 3.1.0
info:
  title: PyPI JSON API
  description: >-
    The PyPI JSON API provides metadata about individual Python packages hosted
    on the Python Package Index. It returns project-level information including
    the latest version, all available releases, download URLs, and hash digests
    for MD5, SHA256, and BLAKE2b-256. Responses are cached by CDN and support
    ETag headers for conditional requests.
  version: '1.0'
  contact:
    name: PyPI Support
    url: https://pypi.org/help/
  termsOfService: https://pypi.org/policy/terms-of-use/
externalDocs:
  description: PyPI JSON API Documentation
  url: https://docs.pypi.org/api/json/
servers:
  - url: https://pypi.org
    description: Production Server
tags:
  - name: Projects
    description: >-
      Retrieve metadata about Python packages hosted on PyPI, including release
      information, download URLs, and vulnerability data.
paths:
  /pypi/{project}/json:
    get:
      operationId: getProjectMetadata
      summary: Get project metadata
      description: >-
        Returns metadata about an individual project at the latest version,
        including a list of all releases for that project, project URLs,
        and known vulnerabilities. The response includes info, last_serial,
        releases, urls, and vulnerabilities fields.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectName'
      responses:
        '200':
          description: Project metadata retrieved successfully
          headers:
            ETag:
              description: >-
                Entity tag for cache validation. Use with If-None-Match header
                for conditional requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '404':
          description: Project not found
  /pypi/{project}/{version}/json:
    get:
      operationId: getProjectVersionMetadata
      summary: Get project version metadata
      description: >-
        Returns metadata about an individual release at a specific version.
        Identical to the project-level endpoint but scoped to a single version
        and excludes the releases key.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectName'
        - $ref: '#/components/parameters/VersionString'
      responses:
        '200':
          description: Version metadata retrieved successfully
          headers:
            ETag:
              description: >-
                Entity tag for cache validation. Use with If-None-Match header
                for conditional requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'
        '404':
          description: Project or version not found
components:
  parameters:
    ProjectName:
      name: project
      in: path
      required: true
      description: >-
        The normalized name of the Python package on PyPI.
      schema:
        type: string
        examples:
          - requests
          - numpy
    VersionString:
      name: version
      in: path
      required: true
      description: >-
        The version string of the release to retrieve.
      schema:
        type: string
        examples:
          - '1.0.0'
          - '2.31.0'
  schemas:
    ProjectResponse:
      type: object
      description: >-
        Full project metadata response including all releases.
      properties:
        info:
          $ref: '#/components/schemas/ProjectInfo'
        last_serial:
          type: integer
          description: >-
            A monotonically increasing integer sequence that changes every time
            the project is updated.
        releases:
          type: object
          description: >-
            A mapping of version strings to arrays of release file objects.
            Deprecated in favor of the Index API.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/ReleaseFile'
        urls:
          type: array
          description: >-
            A list of release file objects associated with the latest version.
          items:
            $ref: '#/components/schemas/ReleaseFile'
        vulnerabilities:
          type: array
          description: >-
            Known vulnerabilities affecting the latest release of the project.
          items:
            $ref: '#/components/schemas/Vulnerability'
    VersionResponse:
      type: object
      description: >-
        Version-specific metadata response for a single release.
      properties:
        info:
          $ref: '#/components/schemas/ProjectInfo'
        last_serial:
          type: integer
          description: >-
            A monotonically increasing integer sequence that changes every time
            the project is updated.
        urls:
          type: array
          description: >-
            A list of release file objects associated with this specific version.
          items:
            $ref: '#/components/schemas/ReleaseFile'
        vulnerabilities:
          type: array
          description: >-
            Known vulnerabilities affecting this specific release.
          items:
            $ref: '#/components/schemas/Vulnerability'
    ProjectInfo:
      type: object
      description: >-
        Core metadata about the project, sourced from the values provided at
        upload time.
      properties:
        name:
          type: string
          description: >-
            The name of the project.
        version:
          type: string
          description: >-
            The version of the latest release.
        summary:
          type: string
          description: >-
            A one-line summary of the project.
        description:
          type: string
          description: >-
            The full description of the project.
        description_content_type:
          type: string
          description: >-
            The content type of the description field, such as text/markdown or
            text/x-rst.
        author:
          type: string
          description: >-
            The name of the project author.
        author_email:
          type: string
          description: >-
            The email address of the project author.
        maintainer:
          type: string
          nullable: true
          description: >-
            The name of the project maintainer.
        maintainer_email:
          type: string
          nullable: true
          description: >-
            The email address of the project maintainer.
        license:
          type: string
          description: >-
            The license text or identifier for the project.
        license_expression:
          type: string
          nullable: true
          description: >-
            A SPDX license expression for the project.
        license_files:
          type: array
          nullable: true
          description: >-
            List of license file paths included in the distribution.
          items:
            type: string
        keywords:
          type: string
          nullable: true
          description: >-
            Comma-separated keywords for the project.
        classifiers:
          type: array
          description: >-
            A list of Trove classifiers for the project.
          items:
            type: string
        platform:
          type: string
          nullable: true
          description: >-
            The platform specification for the project.
        home_page:
          type: string
          nullable: true
          description: >-
            The URL of the project home page.
        download_url:
          type: string
          nullable: true
          description: >-
            A URL to download the project. Deprecated.
        project_url:
          type: string
          format: uri
          description: >-
            The URL of the project on PyPI.
        project_urls:
          type: object
          nullable: true
          description: >-
            A mapping of label to URL for project-related links.
          additionalProperties:
            type: string
            format: uri
        docs_url:
          type: string
          nullable: true
          description: >-
            The URL of the project documentation. Deprecated, always null.
        bugtrack_url:
          type: string
          nullable: true
          description: >-
            The URL of the project bug tracker. Deprecated, always null.
        requires_python:
          type: string
          nullable: true
          description: >-
            The Python version requirement specifier for the project.
        requires_dist:
          type: array
          nullable: true
          description: >-
            A list of PEP 508 dependency specifiers.
          items:
            type: string
        provides_extra:
          type: array
          nullable: true
          description: >-
            A list of optional extra dependency groups provided by the project.
          items:
            type: string
        dynamic:
          type: array
          nullable: true
          description: >-
            A list of metadata fields that are dynamically specified.
          items:
            type: string
        yanked:
          type: boolean
          description: >-
            Whether the release has been yanked from the index.
        yanked_reason:
          type: string
          nullable: true
          description: >-
            The reason the release was yanked, if applicable.
    ReleaseFile:
      type: object
      description: >-
        Metadata about a single distribution file within a release.
      properties:
        filename:
          type: string
          description: >-
            The name of the distribution file.
        url:
          type: string
          format: uri
          description: >-
            The URL to download the distribution file.
        size:
          type: integer
          description: >-
            The size of the file in bytes.
        packagetype:
          type: string
          description: >-
            The type of distribution, such as sdist or bdist_wheel.
          enum:
            - sdist
            - bdist_wheel
            - bdist_egg
            - bdist_wininst
            - bdist_rpm
        python_version:
          type: string
          description: >-
            The Python version this distribution targets.
        requires_python:
          type: string
          nullable: true
          description: >-
            The Python version requirement for this file.
        upload_time:
          type: string
          format: date-time
          description: >-
            The timestamp when the file was uploaded. Deprecated in favor of
            upload_time_iso_8601.
        upload_time_iso_8601:
          type: string
          format: date-time
          description: >-
            The ISO 8601 timestamp when the file was uploaded.
        comment_text:
          type: string
          nullable: true
          description: >-
            Optional comment text associated with the upload.
        digests:
          type: object
          description: >-
            Hash digests for the distribution file.
          properties:
            md5:
              type: string
              description: >-
                MD5 hash digest of the file.
            sha256:
              type: string
              description: >-
                SHA-256 hash digest of the file.
            blake2b_256:
              type: string
              description: >-
                BLAKE2b-256 hash digest of the file.
        has_sig:
          type: boolean
          description: >-
            Whether the file has a PGP signature. Deprecated, always false.
        yanked:
          type: boolean
          description: >-
            Whether this file has been yanked.
        yanked_reason:
          type: string
          nullable: true
          description: >-
            The reason the file was yanked, if applicable.
    Vulnerability:
      type: object
      description: >-
        A known security vulnerability affecting the project release.
      properties:
        id:
          type: string
          description: >-
            The unique identifier for the vulnerability.
        aliases:
          type: array
          description: >-
            Alternative identifiers for this vulnerability, such as CVE numbers.
          items:
            type: string
        summary:
          type: string
          description: >-
            A brief summary of the vulnerability.
        details:
          type: string
          description: >-
            Detailed description of the vulnerability.
        fixed_in:
          type: array
          description: >-
            List of version strings in which the vulnerability is fixed.
          items:
            type: string
        link:
          type: string
          format: uri
          description: >-
            A URL with more information about the vulnerability.