Create a Publishing Session

A release starts by creating a new publishing session. To create the session, a client submits a POST 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 is api-version the value of which must be the string "2.0". Optional sub-keys can define index-specific behavior.

name (required)

The name of the project that this session is attempting to release a new version of. The name MUST conform to the standard package name format and the server MUST normalize the name.

version (required)

The version of the project that this session is attempting to add files to. The version string MUST conform to the packaging version specification.

Upon successful session creation, the server returns a 201 Created response. The response MUST also include a Location header containing the same URL as the links.session key in the response body.

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

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

Optional Index-specific Metadata

Index can optionally define their own metadata for index-specific behavior. The metadata key MUST begin with an underscore, with the following value easily and uniquely identifying the index. For example, PyPI could allow for projects to be created in an organization account of which the publisher is a member by using the following 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 or values 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 a POST request to the session link given in the session 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 a 201 Created 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 HTTP request), then it may return a 202 Accepted response.

The server MUST include a Location header in the response pointing back to the Publishing Session status URL, which can be used to query the current session status. If the server returned a 202 Accepted, polling that URL can be used to watch for session status changes.

Publishing Session Cancellation

To cancel a publishing session, a client issues a DELETE request to the session link given in the session creation response body. The server then marks the session as canceled, and SHOULD purge any data that was uploaded as part of that session. Future attempts to access that session URL or any of the publishing session URLs MUST return a 404 Not Found.

To prevent dangling sessions, servers may also choose to cancel timed-out sessions on their own accord. It is recommended that servers expunge their sessions after no less than a week, but each server may choose their own schedule. Servers MAY support client-directed session extensions.

Publishing Session Status

At any time, a client can query the status of a session by issuing a GET request to the URL given in the links.session URL (also provided in the session creation response’s Location header).

The server will respond to this GET request with the same publishing session creation response, that they got when they initially created the publishing session, except with any changes to status, expires-at, or files reflected.

Publishing Session Extension

Servers MAY allow clients to extend sessions, but the overall lifetime and number of extensions allowed is left to the server. To extend a session, a client issues a POST request to the links.session URL (same as above, also the Location 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 to extend the current session. For example, if the client wants to extend the current session for another hour, extend-for would be 3600. Upon successful extension, the server will respond with the same publishing session creation response body that they got when they initially created the publishing session, except with any changes to status, expires-at, or files reflected.

If the server refuses to extend the session for the requested number of seconds, it MUST still return a success response, and the expires-at key will simply reflect the current expiration time of the session.

Publishing Session Token

Indexes SHOULD support preview stages so that uploaded files can be live tested before publishing. E.g. a CI client could perform installation tests using pre-published wheels to ensure that 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 their response to publishing session creation. Indexes which don’t support staged previews MUST NOT include these in their responses.

The session-token is a short token which could be used as a convenience for installation tool UX, if they want to support staged previews via a command line switch, e.g. $TOOL install --staging $SESSION_TOKEN. The links.stage key gives the full URL to the stage, which could be used in the CLI, e.g. pip install --extra-index-url $STAGE_URL. Both the session token and URL MUST be cryptographically unguessable, but the algorithm for generating the token is left to the index. The stage URL MUST be calculable from the session token, using a format documented by the index, but the exact format of the URL is also left to the index.

Create a File Upload Session

After creating a publishing session, the upload endpoint from the response’s session links mapping is used to begin the upload of new files into that session. Clients MUST use the provided upload URL and MUST NOT assume there is any pattern or commonality to those URLs from one session to the next.

To initiate a file upload, a client first sends a POST request to the upload 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 standard meta key, the request JSON has the following additional keys:

filename (required)

The name of the file being uploaded. The filename MUST conform to either the source distribution file name specification or the binary distribution file name convention. Indexes SHOULD validate these file names at the time of the request, returning a 400 Bad Request error code, as described in the Errors section when the file 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 the file being uploaded when hashed by the algorithm identified in the name.

By default, any hash algorithm available in hashlib can be used as a key for the hashes dictionary [3]. At least one secure algorithm from hashlib.algorithms_guaranteed MUST always be included. This PEP specifically recommends sha256.

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

mechanism (required)

The file-upload mechanisms the client intends to use for this file. This mechanism SHOULD be chosen from the list of mechanisms advertised in the publishing session creation response body. A client MAY send a mechanism that is not advertised in cases where server operators have documented 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’s core metadata.

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

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

If the server determines that upload should proceed, it will return a 202 Accepted response, with the response body below. The status of the publishing session will also include the filename in the files mapping. If the server cannot proceed with an upload because the mechanism supplied by the client is not supported it MUST return a 422 Unprocessable Content. The server MAY allow parallel uploads of files, but is not required to. If the server determines the upload cannot proceed, it MUST return a 409 Conflict.

{
  "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 executed and did not produce an error, a client issues a POST to the file-upload-session link in the file 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 a 201 Created response and set the status of the file upload session to complete. If it is unable to immediately complete the file upload session (for instance, if it needs to do validation that may take longer than reasonable in a single HTTP request), then it may return a 202 Accepted response and set the status of the file upload session to processing.

In either case, the server should include a Location header pointing back to the file upload session status URL.

Servers MUST allow clients to poll the file upload session status URL to watch for the status to change. If the server responds with a 202 Accepted, clients may poll the file upload session status URL to watch for the status to change. Clients SHOULD respect the Retry-After header value of the file upload session 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 a DELETE request to the links.file-upload-session URL from the file upload session creation response of the file they want to delete.

A successful deletion request MUST respond with a 204 No Content.

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

Replacing a Partially or Fully Uploaded File

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

To replace a session file, clients should cancel and delete the in-progress upload first. After this, the new file upload can be initiated by beginning the entire file upload sequence over again. This means providing the metadata request again to retrieve a new upload resource URL. Clients MUST NOT assume that the previous upload resource URL can be reused after deletion.

File Upload Session Status

The client can query status of the file upload session by issuing a GET request to the links.file-upload-session URL from the file upload session creation response. The server responds to this request with the same payload as the file upload session creation response, except with any changes status and expires-at reflected.

File Upload Session Extension

Servers MAY allow clients to extend file upload sessions, but the overall lifetime and number of extensions allowed is left to the server. To extend a file upload session, a client issues a POST request to the links.file-upload-session URL from the file 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 to extend the current file upload session. For example, if the client wants to extend session for another hour, extend-for would be 3600. Upon successful extension, the server will respond with the same file upload session creation response body that they got when they initially created the publishing session, except with any changes to status or expires-at reflected.

If the server refuses to extend the session for the requested number of seconds, it MUST still return a success response, and the expires-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 server MAY implement an arbitrary number of server specific mechanisms and is responsible for documenting their usage.

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

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

Server specific implementations MUST use vnd as their prefix. The operator identifier SHOULD clearly identify the server operator, be unique from other well known indexes, and contain only alphanumeric characters [a-z0-9]. The implementation identifier SHOULD concisely describe the underlying implementation and contain only alphanumeric characters [a-z0-9] and -.

When server operators need to make breaking changes to their upload mechanisms, they SHOULD 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 maintaining backward compatibility with existing clients.

For example:

If a server intends to precisely match the behavior of another server’s implementation, it MAY respond with that implementation’s file upload mechanism name.