Upgrade

Protocol negotiation on an existing connection is handled by the Upgrade request and response header, which proposes switching from the current protocol to a different one on the same connection.

Table of Contents

Usage

The Upgrade header enables protocol negotiation on an existing HTTP/1.1 Connection. A client sends this header to propose switching to a different protocol, and the server either accepts by responding with 101 Switching Protocols or ignores the request and continues with the current protocol.

Common upgrade targets include WebSocket (websocket), TLS (TLS/1.2, TLS/1.3), and, historically, HTTP/2 cleartext (h2c). The WebSocket upgrade is the most widely used form in modern deployments, enabling full-duplex communication between browsers and servers.

The Connection header is required alongside Upgrade. The sender sets Connection: upgrade to mark the field hop-by-hop, so intermediaries strip the field instead of forwarding an upgrade offer meant for the next hop alone. A server switches only to a protocol the client listed, and a server receiving Upgrade in an HTTP/1.0 request ignores the field.

A server also sends Upgrade as part of a 426 Upgrade Required response. This tells the client the server refuses to process the request with the current protocol and lists the required protocol in the Upgrade value.

Values

websocket

Upgrades the connection to the WebSocket protocol for full-duplex communication. The client includes Sec-WebSocket-Key and Sec-WebSocket-Version headers alongside the upgrade request.

h2c

Upgrades the connection to HTTP/2 over cleartext (without TLS). The client includes the HTTP2-Settings header containing base64url-encoded HTTP/2 connection parameters.

TLS/1.2, TLS/1.3

Upgrades an unencrypted HTTP connection to a TLS-secured connection. This mechanism is less common than establishing TLS directly.

Example

A client requests a WebSocket upgrade. The server accepts by responding with 101 Switching Protocols and confirming the new protocol.

GET /chat HTTP/1.1
Host: example.re
Connection: upgrade
Upgrade: websocket
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

A client proposes upgrading to HTTP/2 over cleartext using the deprecated h2c token. The HTTP2-Settings header carries the initial HTTP/2 parameters encoded in base64url format.

GET / HTTP/1.1
Host: example.re
Connection: upgrade, HTTP2-Settings
Upgrade: h2c
HTTP2-Settings: AAMAAABkAAQCAAAAAAIAAAAA

A server requires the client to use a different protocol. The 426 Upgrade Required response includes the Upgrade header listing the acceptable protocol.

HTTP/1.1 426 Upgrade Required
Upgrade: TLS/1.3, HTTP/1.1
Connection: upgrade

The token list runs in descending preference, naming the TLS layer to switch to and the application protocol running above it.

See also

Last updated: August 17, 2026