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.
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.