square · jameswald · Feb 25, 2026 · Feb 25, 2026 · jameswald · Feb 25, 2026
diff --git a/.gitignore b/.gitignore
@@ -31,7 +31,7 @@ obj
 .DS_Store
 
 # Special Mkdocs files
-docs/4.x
+docs/5.x
 docs/changelog.md
 docs/contributing.md
 docs/index.md

diff --git a/docs/features/caching.md b/docs/features/caching.md
@@ -2,7 +2,7 @@ Caching
 =======
 
 OkHttp implements an optional, off by default, Cache. OkHttp aims for RFC correct and
-pragmatic caching behaviour, following common real-world browser like Firefox/Chrome and 
+pragmatic caching behaviour, following common real-world browser like Firefox/Chrome and
 server behaviour when ambiguous.
 
 # Basic Usage
@@ -17,7 +17,7 @@ server behaviour when ambiguous.
       .build()
 ```
 
-## EventListener events 
+## EventListener events
 
 Cache Events are exposed via the EventListener API.  Typical scenarios are below.
 
@@ -26,34 +26,34 @@ Cache Events are exposed via the EventListener API.  Typical scenarios are below
 In the ideal scenario the cache can fulfill the request without any conditional call to the network.
 This will skip the normal events such as DNS, connecting to the network, and downloading the response body.
 
-As recommended by the HTTP RFC the max age of a document is defaulted to 10% of the 
-document's age at the time it was served based on "Last-Modified". Default expiration dates aren't used for URIs 
+As recommended by the HTTP RFC the max age of a document is defaulted to 10% of the
+document's age at the time it was served based on "Last-Modified". Default expiration dates aren't used for URIs
 containing a query.
 
  - CallStart
  - **CacheHit**
  - CallEnd
- 
+
 ### Cache Miss
 
 Under a cache miss the normal request events are seen but an additional event shows the presence of the cache.
-Cache Miss will be typical if the item has not been read from the network, is uncacheable, or is past it's 
+Cache Miss will be typical if the item has not been read from the network, is uncacheable, or is past it's
 lifetime based on Response cache headers.
 
- - CallStart 
+ - CallStart
  - **CacheMiss**
  - ProxySelectStart
  - ... Standard Events ...
  - CallEnd
-        
+
 ### Conditional Cache Hit
- 
+
 When cache flags require checking the cache results are still valid an early cacheConditionalHit event is
 received followed by a cache hit or miss.  Critically in the cache hit scenario the server won’t send the response body.
 
 The response will have non-null `cacheResponse` and `networkResponse`. The cacheResponse will be used as the top level
 response only if the response code is HTTP/1.1 304 Not Modified.
- 
+
  - CallStart
  - **CacheConditionalHit**
  - ConnectionAcquired
@@ -62,7 +62,7 @@ response only if the response code is HTTP/1.1 304 Not Modified.
  - **CacheHit**
  - ConnectionReleased
  - CallEnd
- 
+
 ## Cache directory
 
 The cache directory must be exclusively owned by a single instance.
@@ -73,7 +73,7 @@ which is designed to persist between app restarts.
 ```kotlin
 cache.delete()
 ```
- 
+
 ## Pruning the Cache
 
 Pruning the entire Cache to clear space temporarily can be done using evictAll.
@@ -102,4 +102,4 @@ Make sure you are reading responses fully as unless they are read fully, cancell
 
 ### Overriding normal cache behaviour
 
-See Cache documentation. https://square.github.io/okhttp/4.x/okhttp/okhttp3/-cache/
+See [`Cache`](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-cache/) documentation.
diff --git a/docs/features/calls.md b/docs/features/calls.md
@@ -2,11 +2,11 @@
 
 The HTTP client’s job is to accept your request and produce its response. This is simple in theory but it gets tricky in practice.
 
-## [Requests](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-request/)
+## [Requests](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-request/)
 
 Each HTTP request contains a URL, a method (like `GET` or `POST`), and a list of headers. Requests may also contain a body: a data stream of a specific content type.
 
-## [Responses](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-response/)
+## [Responses](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-response/)
 
 The response answers the request with a code (like 200 for success or 404 for not found), headers, and its own optional body.
 
@@ -28,25 +28,25 @@ If a conditional GET was successful, responses from the network and cache are me
 
 When your requested URL has moved, the webserver will return a response code like `302` to indicate the document’s new URL. OkHttp will follow the redirect to retrieve a final response.
 
-If the response issues an authorization challenge, OkHttp will ask the [`Authenticator`](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-authenticator/) (if one is configured) to satisfy the challenge. If the authenticator supplies a credential, the request is retried with that credential included.
+If the response issues an authorization challenge, OkHttp will ask the [`Authenticator`](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-authenticator/) (if one is configured) to satisfy the challenge. If the authenticator supplies a credential, the request is retried with that credential included.
 
 ## Retrying Requests
 
 Sometimes connections fail: either a pooled connection was stale and disconnected, or the webserver itself couldn’t be reached. OkHttp will retry the request with a different route if one is available.
 
-## [Calls](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-call/)
+## [Calls](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-call/)
 
 With rewrites, redirects, follow-ups and retries, your simple request may yield many requests and responses. OkHttp uses `Call` to model the task of satisfying your request through however many intermediate requests and responses are necessary. Typically this isn’t many! But it’s comforting to know that your code will continue to work if your URLs are redirected or if you failover to an alternate IP address.
 
 Calls are executed in one of two ways:
 
  * **Synchronous:** your thread blocks until the response is readable.
- * **Asynchronous:** you enqueue the request on any thread, and get [called back](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-callback/) on another thread when the response is readable.
+ * **Asynchronous:** you enqueue the request on any thread, and get [called back](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-callback/) on another thread when the response is readable.
 
 Calls can be canceled from any thread. This will fail the call if it hasn’t yet completed! Code that is writing the request body or reading the response body will suffer an `IOException` when its call is canceled.
 
 ## Dispatch
 
 For synchronous calls, you bring your own thread and are responsible for managing how many simultaneous requests you make. Too many simultaneous connections wastes resources; too few harms latency.
 
-For asynchronous calls, [`Dispatcher`](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-dispatcher/) implements policy for maximum simultaneous requests. You can set maximums per-webserver (default is 5), and overall (default is 64).
+For asynchronous calls, [`Dispatcher`](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-dispatcher/) implements policy for maximum simultaneous requests. You can set maximums per-webserver (default is 5), and overall (default is 64).
diff --git a/docs/features/connections.md b/docs/features/connections.md
@@ -3,7 +3,7 @@ Connections
 
 Although you provide only the URL, OkHttp plans its connection to your webserver using three types: URL, Address, and Route.
 
-### [URLs](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-http-url/)
+### [URLs](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-http-url/)
 
 URLs (like `https://github.com/square/okhttp`) are fundamental to HTTP and the Internet. In addition to being a universal, decentralized naming scheme for everything on the web, they also specify how to access web resources.
 
@@ -14,26 +14,26 @@ URLs are abstract:
 
 They're also concrete: each URL identifies a specific path (like `/square/okhttp`) and query (like `?q=sharks&lang=en`). Each webserver hosts many URLs.
 
-### [Addresses](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-address/)
+### [Addresses](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-address/)
 
 Addresses specify a webserver (like `github.com`) and all of the **static** configuration necessary to connect to that server: the port number, HTTPS settings, and preferred network protocols (like HTTP/2).
 
-URLs that share the same address may also share the same underlying TCP socket connection. Sharing a connection has substantial performance benefits: lower latency, higher throughput (due to [TCP slow start](https://www.igvita.com/2011/10/20/faster-web-vs-tcp-slow-start/)) and conserved battery. OkHttp uses a [ConnectionPool](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-connection-pool/) that automatically reuses HTTP/1.x connections and multiplexes HTTP/2 connections.
+URLs that share the same address may also share the same underlying TCP socket connection. Sharing a connection has substantial performance benefits: lower latency, higher throughput (due to [TCP slow start](https://www.igvita.com/2011/10/20/faster-web-vs-tcp-slow-start/)) and conserved battery. OkHttp uses a [ConnectionPool](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-connection-pool/) that automatically reuses HTTP/1.x connections and multiplexes HTTP/2 connections.
 
-In OkHttp some fields of the address come from the URL (scheme, hostname, port) and the rest come from the [OkHttpClient](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-ok-http-client/).
+In OkHttp some fields of the address come from the URL (scheme, hostname, port) and the rest come from the [OkHttpClient](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http-client/).
 
-### [Routes](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-route/)
+### [Routes](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-route/)
 
 Routes supply the **dynamic** information necessary to actually connect to a webserver. This is the specific IP address to attempt (as discovered by a DNS query), the exact proxy server to use (if a [ProxySelector](https://developer.android.com/reference/java/net/ProxySelector.html) is in use), and which version of TLS to negotiate (for HTTPS connections).
 
 There may be many routes for a single address. For example, a webserver that is hosted in multiple datacenters may yield multiple IP addresses in its DNS response.
 
 In limited situations OkHttp will retry a route if connecting fails:
 
- * When making an HTTPS connection through an HTTP proxy, the proxy may issue an authentication challenge. OkHttp will call the proxy [authenticator](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-authenticator/) and try again.
- * When making TLS connections with multiple [connection specs](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-connection-spec/), these are attempted in sequence until the TLS handshake succeeds.
+ * When making an HTTPS connection through an HTTP proxy, the proxy may issue an authentication challenge. OkHttp will call the proxy [authenticator](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-authenticator/) and try again.
+ * When making TLS connections with multiple [connection specs](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-connection-spec/), these are attempted in sequence until the TLS handshake succeeds.
 
-### [Connections](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-connection/)
+### [Connections](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-connection/)
 
 When you request a URL with OkHttp, here's what it does:
 
@@ -47,7 +47,7 @@ If there's a problem with the connection, OkHttp will select another route and t
 
 Once the response has been received, the connection will be returned to the pool so it can be reused for a future request. Connections are evicted from the pool after a period of inactivity.
 
-### [Fast Fallback](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-ok-http-client/-builder/fast-fallback/)
+### [Fast Fallback](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-ok-http-client/-builder/fast-fallback)
 
 Since version 5.0, `OkHttpClient` supports fast fallback, which is our implementation of Happy Eyeballs [RFC 6555](https://datatracker.ietf.org/doc/html/rfc6555).
 

diff --git a/docs/features/events.md b/docs/features/events.md
@@ -8,7 +8,7 @@ Events allow you to capture metrics on your application’s HTTP calls. Use even
 
 ### EventListener
 
-Subclass [EventListener](https://square.github.io/okhttp/3.x/okhttp/okhttp3/EventListener.html) and override methods for the events you are interested in. In a successful HTTP call with no redirects or retries the sequence of events is described by this flow.
+Subclass [EventListener](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-event-listener/) and override methods for the events you are interested in. In a successful HTTP call with no redirects or retries the sequence of events is described by this flow.
 
 ![Events Diagram](../assets/images/events@2x.png)
 

diff --git a/docs/features/https.md b/docs/features/https.md
@@ -6,9 +6,9 @@ OkHttp attempts to balance two competing concerns:
  * **Connectivity** to as many hosts as possible. That includes advanced hosts that run the latest versions of [boringssl](https://boringssl.googlesource.com/boringssl/) and less out of date hosts running older versions of [OpenSSL](https://www.openssl.org/).
  * **Security** of the connection. This includes verification of the remote webserver with certificates and the privacy of data exchanged with strong ciphers.
 
-When negotiating a connection to an HTTPS server, OkHttp needs to know which [TLS versions](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-tls-version/) and [cipher suites](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-cipher-suite/) to offer. A client that wants to maximize connectivity would include obsolete TLS versions and weak-by-design cipher suites. A strict client that wants to maximize security would be limited to only the latest TLS version and strongest cipher suites.
+When negotiating a connection to an HTTPS server, OkHttp needs to know which [TLS versions](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-tls-version/) and [cipher suites](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-cipher-suite/) to offer. A client that wants to maximize connectivity would include obsolete TLS versions and weak-by-design cipher suites. A strict client that wants to maximize security would be limited to only the latest TLS version and strongest cipher suites.
 
-Specific security vs. connectivity decisions are implemented by [ConnectionSpec](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-connection-spec/). OkHttp includes four built-in connection specs:
+Specific security vs. connectivity decisions are implemented by [ConnectionSpec](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-connection-spec/). OkHttp includes four built-in connection specs:
 
  * `RESTRICTED_TLS` is a secure configuration, intended to meet stricter compliance requirements.
  * `MODERN_TLS` is a secure configuration that connects to modern HTTPS servers.
@@ -68,7 +68,7 @@ and increase connectivity with web servers.
 
 By default, OkHttp trusts the certificate authorities of the host platform. This strategy maximizes connectivity, but it is subject to certificate authority attacks such as the [2011 DigiNotar attack](https://www.computerworld.com/article/2510951/cybercrime-hacking/hackers-spied-on-300-000-iranians-using-fake-google-certificate.html). It also assumes your HTTPS servers’ certificates are signed by a certificate authority.
 
-Use [CertificatePinner](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-certificate-pinner/) to restrict which certificates and certificate authorities are trusted. Certificate pinning increases security, but limits your server team’s abilities to update their TLS certificates. **Do not use certificate pinning without the blessing of your server’s TLS administrator!**
+Use [CertificatePinner](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-certificate-pinner/) to restrict which certificates and certificate authorities are trusted. Certificate pinning increases security, but limits your server team’s abilities to update their TLS certificates. **Do not use certificate pinning without the blessing of your server’s TLS administrator!**
 
 === ":material-language-kotlin: Kotlin"
     ```kotlin

diff --git a/docs/recipes.md b/docs/recipes.md
@@ -641,7 +641,7 @@ Response caching uses HTTP headers for all configuration. You can add request he
       }
     ```
 
-To prevent a response from using the cache, use [`CacheControl.FORCE_NETWORK`](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-cache-control/-f-o-r-c-e_-n-e-t-w-o-r-k/). To prevent it from using the network, use [`CacheControl.FORCE_CACHE`](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-cache-control/-f-o-r-c-e_-c-a-c-h-e/). Be warned: if you use `FORCE_CACHE` and the response requires the network, OkHttp will return a `504 Unsatisfiable Request` response.
+To prevent a response from using the cache, use [`CacheControl.FORCE_NETWORK`](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-cache-control/-companion/-f-o-r-c-e_-n-e-t-w-o-r-k). To prevent it from using the network, use [`CacheControl.FORCE_CACHE`](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-cache-control/-companion/-f-o-r-c-e_-c-a-c-h-e). Be warned: if you use `FORCE_CACHE` and the response requires the network, OkHttp will return a `504 Unsatisfiable Request` response.
 
 
 ### Canceling a Call ([.kt][CancelCallKotlin], [.java][CancelCallJava])

diff --git a/okhttp-tls/README.md b/okhttp-tls/README.md
@@ -228,7 +228,7 @@ Download
 implementation("com.squareup.okhttp3:okhttp-tls:5.3.0")
 ```
 
- [held_certificate]: https://square.github.io/okhttp/4.x/okhttp-tls/okhttp3.tls/-held-certificate/
- [held_certificate_builder]: https://square.github.io/okhttp/4.x/okhttp-tls/okhttp3.tls/-held-certificate/-builder/
- [handshake_certificates]: https://square.github.io/okhttp/4.x/okhttp-tls/okhttp3.tls/-handshake-certificates/
- [handshake_certificates_builder]: https://square.github.io/okhttp/4.x/okhttp-tls/okhttp3.tls/-handshake-certificates/-builder/
+ [held_certificate]: https://square.github.io/okhttp/5.x/okhttp-tls/okhttp3.tls/-held-certificate/
+ [held_certificate_builder]: https://square.github.io/okhttp/5.x/okhttp-tls/okhttp3.tls/-held-certificate/-builder/
+ [handshake_certificates]: https://square.github.io/okhttp/5.x/okhttp-tls/okhttp3.tls/-handshake-certificates/
+ [handshake_certificates_builder]: https://square.github.io/okhttp/5.x/okhttp-tls/okhttp3.tls/-handshake-certificates/-builder/
diff --git a/test_docs.sh b/test_docs.sh
@@ -14,7 +14,7 @@ set -ex
 # Generate the API docs
 ./gradlew dokkaGeneratePublicationHtml -PokhttpDokka=true
 
-mv ./build/dokka/html docs/4.x
+mv ./build/dokka/html docs/5.x
 
 # Copy in special files that GitHub wants in the project root.
 cat README.md | grep -v 'project website' > docs/index.md
-Original file line number
+Diff line change
@@ Expand Up @@
           }
         ```
-    To prevent a response from using the cache, use [`CacheControl.FORCE_NETWORK`](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-cache-control/-f-o-r-c-e_-n-e-t-w-o-r-k/). To prevent it from using the network, use [`CacheControl.FORCE_CACHE`](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-cache-control/-f-o-r-c-e_-c-a-c-h-e/). Be warned: if you use `FORCE_CACHE` and the response requires the network, OkHttp will return a `504 Unsatisfiable Request` response.
+    To prevent a response from using the cache, use [`CacheControl.FORCE_NETWORK`](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-cache-control/-companion/-f-o-r-c-e_-n-e-t-w-o-r-k). To prevent it from using the network, use [`CacheControl.FORCE_CACHE`](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-cache-control/-companion/-f-o-r-c-e_-c-a-c-h-e). Be warned: if you use `FORCE_CACHE` and the response requires the network, OkHttp will return a `504 Unsatisfiable Request` response.
     ### Canceling a Call ([.kt][CancelCallKotlin], [.java][CancelCallJava])
@@ Expand Down @@