Create a Publishing Session

A release starts by creating a new publishing session. To create the session, a client submits aPOST request to the root URL like:

{"meta":{"api-version":"2.0"},"name":"foo","version":"1.0",}

The request includes the following top-level keys:

meta (required)

Describes information about the payload itself. Currently, the only defined sub-key isapi-version the value of which must be the string"2.0". Optional sub-keys can defineindex-specific behavior.

name (required)

The name of the project that this session is attempting to release a new version of. The nameMUST conform to thestandard package name formatand the serverMUST normalize the name.

version (required)

The version of the project that this session is attempting to add files to. The version stringMUST conform to thepackaging version specification.

Upon successful session creation, the server returns a201Created response. The responseMUST alsoinclude aLocation header containing the same URL as thelinks.sessionkey in theresponse body.

If a session is created for a project which has no previous release,then the indexMAY reserve the project name before the session is published,however itMUST NOT be possible to navigate to that project usingthe “regular” (i.e.unstaged) access protocols,until the stage is published.If this first-release stage gets canceled,then the indexSHOULD delete the project record, as if it were never uploaded.

The session is owned by the user that created it,and all subsequent requestsMUST be performed with the same credentials,otherwise a403Forbidden will be returned on those subsequent requests.

Optional Index-specific Metadata

Index can optionally define their own metadata for index-specific behavior. The metadata keyMUST begin with an underscore, with the following value easily and uniquely identifying theindex. For example, PyPI could allow for projects to be created in anorganization account of which the publisher is a member by using thefollowing index-specific metadata section:

{"meta":{"api-version":"2.0","_pypi.org":{"organization":"my-main-org"}},"name":"foo","version":"1.0",}

This is only an example. This PEP does not define or reserve any index-specific keys or metadata;that is left up to the index to specify and document. The semantics (e.g. whether bogus keys orvalues result in an error or are ignored) of the index-specific metadata is also undefined here.

{"meta":{"api-version":"2.0"},"links":{"stage":"...","upload":"...","session":"...",},"mechanisms":["http-post-bytes"],"session-token":"<token-string>","expires-at":"2025-08-01T12:00:00Z","status":"pending","files":{},"notices":["a notice to display to the user"]}

Complete a Publishing Session

To complete a session and publish the files that have been included in it, a client issues aPOST request to thesessionlinkgiven in thesession creation response body.

The request looks like:

{"meta":{"api-version":"2.0"},"action":"publish",}

If the server is able to immediately complete the publishing session, it may do so and return a201Created response. If it is unable to immediately complete the publishing session(for instance, if it needs to do validation that may take longer than reasonable in a single HTTPrequest), then it may return a202Accepted response.

The serverMUST include aLocation header in the response pointing back to thePublishingSession status URL, which can be used to query the current session status. If the serverreturned a202Accepted, polling that URL can be used to watch for session status changes.

Publishing Session Cancellation

To cancel a publishing session, a client issues aDELETE request tothesessionlinkgiven in thesession creation response body.The server then marks the session as canceled, andSHOULD purge any data that was uploadedas part of that session.Future attempts to access that session URL or any of the publishing session URLsMUST return a404NotFound.

To prevent dangling sessions, servers may also choose to cancel timed-out sessions on their ownaccord. It is recommended that servers expunge their sessions after no less than a week, but eachserver may choose their own schedule. ServersMAY support client-directedsessionextensions.

Publishing Session Status

At any time, a client can query the status of a session by issuing aGET request to the URL given in thelinks.session URL (also provided in thesession creation response’sLocation header).

The server will respond to thisGET request with the samepublishing session creation response, that they got when they initially created the publishing session, except withany changes tostatus,expires-at, orfiles reflected.

Publishing Session Extension

ServersMAY allow clients to extend sessions, but the overall lifetime and number of extensionsallowed is left to the server. To extend a session, a client issues aPOST request to thelinks.session URL (same as above, also theLocation header).

The request looks like:

{"meta":{"api-version":"2.0"},"action":"extend","extend-for":3600}

The number of seconds specified is just a suggestion to the server for the number of additional seconds toextend the current session. For example, if the client wants to extend the current session for another hour,extend-for would be3600. Upon successful extension, the server will respond with the samepublishing session creation response body that they got when theyinitially created the publishing session, except with any changes tostatus,expires-at, orfilesreflected.

If the server refuses to extend the session for the requested number of seconds, itMUST still return asuccess response, and theexpires-at key will simply reflect the current expiration time of the session.

Publishing Session Token

IndexesSHOULD supportpreview stages so that uploaded files can be live testedbefore publishing. E.g. a CI client could perform installation tests using pre-published wheels to ensurethat their new release works as expected before they publish the release publicly.

Indexes advertise their support for staged previews by returning two key pieces of information in theirresponse to publishing session creation. Indexes which don’t supportstaged previewsMUST NOT include these in their responses.

Thesession-token is a short token which could be used as a convenience for installation tool UX, if theywant to support staged previews via a command line switch, e.g.$TOOLinstall--staging$SESSION_TOKEN.Thelinks.stage key gives the full URL to the stage, which could be used in the CLI, e.g.pipinstall--extra-index-url$STAGE_URL. Both the session token and URLMUST be cryptographicallyunguessable, but the algorithm for generating the token is left to the index. The stage URLMUST becalculable from the session token, using a format documented by the index, but the exact format of the URL isalso left to the index.

Create a File Upload Session

After creating a publishing session, theupload endpoint from the response’ssession links mapping is used to begin the upload of new files into that session. ClientsMUST use the providedupload URL andMUST NOT assume there is any pattern or commonality to thoseURLs from one session to the next.

To initiate a file upload, a client first sends aPOST request to theupload URL.The request looks like:

{"meta":{"api-version":"2.0"},"filename":"foo-1.0.tar.gz","size":1000,"hashes":{"sha256":"...","blake2b":"..."},"metadata":"...","mechanism":"http-post-bytes"}

Besides the standardmeta key, the request JSON has the following additional keys:

filename (required)

The name of the file being uploaded. The filenameMUST conform to either thesource distributionfile name specificationor thebinary distribution file name convention.IndexesSHOULD validate these file names at the time of the request, returning a400BadRequesterror code and an RFC 9457 style error body, as described in theErrors section when thefile names do not conform.

size (required)

The size in bytes of the file being uploaded.

hashes (required)

A mapping of hash names to hex-encoded digests. Each of these digests are the checksums of thefile being uploaded when hashed by the algorithm identified in the name.

By default, any hash algorithm available inhashlib can be used as a key for the hashesdictionary[3]. At least one secure algorithm fromhashlib.algorithms_guaranteedMUST always be included. This PEP specifically recommendssha256.

Multiple hashes may be passed at a time, but all hashes providedMUST be valid for the file.

mechanism (required)

The file-upload mechanisms the client intends to use for this file.This mechanismSHOULD be chosen from the list of mechanisms advertised in thepublishing session creation response body.A clientMAY send a mechanism that is not advertised in cases where server operators havedocumented a new or upcoming mechanism that is available for use on a “pre-release” basis.

metadata (optional)

If given, this is a string value containing the file’score metadata.

ServersMAY use the data provided in this request to do some sanity checking prior to allowingthe file to be uploaded. These checks may include, but are not limited to:

• checking if thefilename already exists in a published release;
• checking if thesize would exceed any project or file quota;
• checking if the contents of themetadata, if provided, are valid.

If the server determines that upload should proceed, it will return a202Accepted response, with theresponse body below. Thestatus of the publishing session will alsoinclude the filename in thefiles mapping. If the server cannot proceed with an upload because themechanism supplied by the client is not supported itMUST return a422UnprocessableContent. TheserverMAY allow parallel uploads of files, but is not required to. If the server determines the uploadcannot proceed, itMUST return a409Conflict.

{"meta":{"api-version":"2.0"},"links":{"file-upload-session":"..."},"status":"pending","expires-at":"2025-08-01T13:00:00Z","mechanism":{"identifier":"http-post-bytes","file_url":"...","attestations_url":"..."}}

Complete a File Upload Session

To complete a file upload session, which indicates that the file upload mechanism has been executedand did not produce an error, a client issues aPOST to thefile-upload-session link in thefile upload session creation response body.

The requests looks like:

{"meta":{"api-version":"2.0"},"action":"complete",}

If the server is able to immediately complete the file upload session, it may do so and return a201Created response and set the status of the file upload session tocomplete. If it is unable toimmediately complete the file upload session (for instance, if it needs to do validation that may take longerthan reasonable in a single HTTP request), then it may return a202Accepted response and set the statusof the file upload session toprocessing.

In either case, the server should include aLocation header pointing back to thefile upload sessionstatus URL.

ServersMUST allow clients to poll the file upload session status URL to watch for the status to change.If the server responds with a202Accepted, clients may poll the file upload session status URL to watchfor the status to change. ClientsSHOULD respect theRetry-After header value of the file uploadsession status response.

Cancellation and Deletion

A client can cancel an in-progress file upload session, or delete a file that has been completely uploaded.In both cases, the client performs this by issuing aDELETE request to thelinks.file-upload-sessionURL from thefile upload session creation response of the file they wantto delete.

A successful deletion requestMUST respond with a204NoContent.

Once canceled or deleted, a clientMUST NOT assume that the previous file upload session resource orassociated file upload mechanisms can be reused.

Replacing a Partially or Fully Uploaded File

To replace a session file, the file uploadMUST have been previously completed, canceled, ordeleted. It is not possible to replace a file if the upload for that file is in-progress.

To replace a session file, clients shouldcancel and delete the in-progress upload first. After this, the new file upload can be initiated by beginning theentirefile upload sequence over again. This means providing the metadatarequest again to retrieve a new upload resource URL. ClientsMUST NOT assume that the previous uploadresource URL can be reused after deletion.

File Upload Session Status

The client can query status of the file upload session by issuing aGET request to thelinks.file-upload-session URL from thefile upload session creation response. The server responds to this request with the same payload as the file uploadsession creation response, except with any changesstatus andexpires-at reflected.

File Upload Session Extension

ServersMAY allow clients to extend file upload sessions, but the overall lifetime and number ofextensions allowed is left to the server. To extend a file upload session, a client issues aPOST requestto thelinks.file-upload-session URL from thefile upload session creation response.

The request looks like:

{"meta":{"api-version":"2.0"},"action":"extend","extend-for":3600}

The number of seconds specified is just a suggestion to the server for the number of additional seconds toextend the current file upload session. For example, if the client wants to extend session for another hour,extend-for would be3600. Upon successful extension, the server will respond with the samefileupload session creation response body that they got when they initiallycreated the publishing session, except with any changes tostatus orexpires-at reflected.

If the server refuses to extend the session for the requested number of seconds, itMUST still return asuccess response, and theexpires-at key will simply reflect the current expiration time of the session.

Required File Upload Mechanisms

Content-Type: application/octet-stream<binary contents of the file to upload>

Content-Type: application/json[{"version": 1, "verification_material": {...}, "envelope": {...}},...]

Server Specific File Upload Mechanisms

A given serverMAY implement an arbitrary number of server specific mechanismsand is responsible for documenting their usage.

A server specific implementation file upload mechanism identifier has three parts:

<prefix>-<operator identifier>-<implementation identifier>

Server specific implementationsMUST usevnd as theirprefix.TheoperatoridentifierSHOULD clearly identify the server operator,be unique from other well known indexes,and contain only alphanumeric characters[a-z0-9].TheimplementationidentifierSHOULD concisely describe the underlying implementationand contain only alphanumeric characters[a-z0-9] and-.

When server operators need to make breaking changes to their upload mechanisms,theySHOULD create a new mechanism identifier rather than modifying the existing one.The recommended pattern is to append a version suffix like-v1,-v2, etc.to the implementation identifier.This allows clients to explicitly opt into new versions while maintainingbackward compatibility with existing clients.

For example:

If a server intends to precisely match the behavior of another server’s implementation, itMAY respondwith that implementation’s file upload mechanism name.