openapi: 3.1.0
info:
  title: PyPI Index API
  description: >-
    The PyPI Index API implements the PEP 503 (HTML) and PEP 691 (JSON) simple
    repository standards for discovering and downloading Python packages. It
    provides a machine-readable index of all registered projects and their
    available distribution files. The API is available in both HTML and JSON
    formats, with JSON recommended for new integrations. This is the primary
    API that package installers like pip use to resolve and download
    dependencies from the Python Package Index.
  version: '1.0'
  contact:
    name: PyPI Support
    url: https://pypi.org/help/
  termsOfService: https://pypi.org/policy/terms-of-use/
externalDocs:
  description: PyPI Index API Documentation
  url: https://docs.pypi.org/api/index-api/
servers:
  - url: https://pypi.org
    description: Production Server
tags:
  - name: Index
    description: >-
      Browse the simple repository index of Python packages, listing all
      projects and their available distribution files.
paths:
  /simple/:
    get:
      operationId: listProjects
      summary: List all projects
      description: >-
        Returns the root index of all projects registered on PyPI. The response
        can be HTML (PEP 503) or JSON (PEP 691) depending on content
        negotiation. The JSON format is recommended for new integrations. Each
        project entry includes the project name as a link to its detail page.
      tags:
        - Index
      parameters:
        - $ref: '#/components/parameters/AcceptHeader'
        - $ref: '#/components/parameters/FormatQuery'
      responses:
        '200':
          description: Project index retrieved successfully
          headers:
            ETag:
              description: >-
                Entity tag for cache validation.
              schema:
                type: string
          content:
            application/vnd.pypi.simple.v1+json:
              schema:
                $ref: '#/components/schemas/ProjectIndex'
            text/html:
              schema:
                type: string
                description: >-
                  HTML page with anchor elements linking to each project.
  /simple/{project}/:
    get:
      operationId: getProjectFiles
      summary: Get project distribution files
      description: >-
        Returns the list of available distribution files for a given project.
        Each file entry includes the filename, download URL, hash digests, and
        optional metadata such as requires-python and data-yanked attributes.
        The response supports HTML (PEP 503) and JSON (PEP 691) formats.
      tags:
        - Index
      parameters:
        - $ref: '#/components/parameters/ProjectName'
        - $ref: '#/components/parameters/AcceptHeader'
        - $ref: '#/components/parameters/FormatQuery'
      responses:
        '200':
          description: Project files retrieved successfully
          headers:
            ETag:
              description: >-
                Entity tag for cache validation.
              schema:
                type: string
          content:
            application/vnd.pypi.simple.v1+json:
              schema:
                $ref: '#/components/schemas/ProjectDetail'
            text/html:
              schema:
                type: string
                description: >-
                  HTML page with anchor elements linking to each distribution
                  file.
        '404':
          description: Project 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
    AcceptHeader:
      name: Accept
      in: header
      required: false
      description: >-
        Content type negotiation header. Use
        application/vnd.pypi.simple.v1+json for JSON responses. The default
        fallback is text/html per PEP 691.
      schema:
        type: string
        default: text/html
        examples:
          - application/vnd.pypi.simple.v1+json
    FormatQuery:
      name: format
      in: query
      required: false
      description: >-
        Alternative to the Accept header for requesting a specific response
        format. Useful for previewing JSON responses in a browser.
      schema:
        type: string
        examples:
          - application/vnd.pypi.simple.v1+json
  schemas:
    ProjectIndex:
      type: object
      description: >-
        The root index listing all projects registered on PyPI in JSON format
        per PEP 691.
      properties:
        meta:
          type: object
          description: >-
            Metadata about the API response.
          properties:
            api-version:
              type: string
              description: >-
                The version of the Simple API being used.
              examples:
                - '1.0'
                - '1.1'
        projects:
          type: array
          description: >-
            List of all registered projects on PyPI.
          items:
            type: object
            properties:
              name:
                type: string
                description: >-
                  The normalized name of the project.
    ProjectDetail:
      type: object
      description: >-
        Detail listing of all distribution files for a specific project in JSON
        format per PEP 691.
      properties:
        meta:
          type: object
          description: >-
            Metadata about the API response.
          properties:
            api-version:
              type: string
              description: >-
                The version of the Simple API being used.
        name:
          type: string
          description: >-
            The normalized name of the project.
        versions:
          type: array
          description: >-
            A list of all version strings uploaded for this project, as defined
            by PEP 700.
          items:
            type: string
        files:
          type: array
          description: >-
            List of distribution files available for download.
          items:
            $ref: '#/components/schemas/FileEntry'
    FileEntry:
      type: object
      description: >-
        A single distribution file entry with download URL, hash digests, and
        metadata.
      properties:
        filename:
          type: string
          description: >-
            The name of the distribution file.
        url:
          type: string
          format: uri
          description: >-
            The URL to download the distribution file, with hash fragment for
            integrity verification.
        hashes:
          type: object
          description: >-
            Hash digests for the distribution file keyed by algorithm name.
          properties:
            sha256:
              type: string
              description: >-
                SHA-256 hash digest of the file.
          additionalProperties:
            type: string
        requires-python:
          type: string
          nullable: true
          description: >-
            The Python version requirement specifier for this file.
        dist-info-metadata:
          oneOf:
            - type: boolean
            - type: object
              additionalProperties:
                type: string
          description: >-
            Indicates whether PEP 658 metadata is available for this file, or
            provides hash digests for the metadata file.
        gpg-sig:
          type: boolean
          nullable: true
          description: >-
            Whether a PGP signature is available. Deprecated.
        yanked:
          oneOf:
            - type: boolean
            - type: string
          description: >-
            False if not yanked, or a string containing the yank reason.
        upload-time:
          type: string
          format: date-time
          nullable: true
          description: >-
            The ISO 8601 timestamp when the file was uploaded, as defined by
            PEP 700.
        size:
          type: integer
          nullable: true
          description: >-
            The size of the file in bytes, as defined by PEP 700.
        data-dist-info-metadata:
          oneOf:
            - type: boolean
            - type: object
              additionalProperties:
                type: string
          description: >-
            Legacy form of dist-info-metadata for backward compatibility.