Upgrade

The HTTP Upgrade header requests a switch from the current protocol to a different one on the same connection.

Table of Contents

Usage
Values
Example
Takeaway
See also

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 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 signal intermediaries to forward the upgrade request rather than consuming the connection themselves.

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.

Note

The Upgrade header applies to HTTP/1.1 only. HTTP/2 and HTTP/3 use ALPN (Application-Layer Protocol Negotiation) during the TLS handshake for protocol selection.

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. 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
Connection: upgrade

Takeaway

The Upgrade header enables protocol switching on an existing HTTP/1.1 Connection, most commonly used for WebSocket upgrades and cleartext HTTP/2 negotiation.