diff --git a/doc/api/errors.md b/doc/api/errors.md
index e0ec3957764914..1a45bbe6e0d2ec 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -821,6 +821,16 @@ that.
Occurs with multiple attempts to shutdown an HTTP/2 session.
+
+### ERR_HTTP2_ALTSVC_INVALID_ORIGIN
+
+HTTP/2 ALTSVC frames require a valid origin.
+
+
+### ERR_HTTP2_ALTSVC_LENGTH
+
+HTTP/2 ALTSVC frames are limited to a maximum of 16,382 payload bytes.
+
### ERR_HTTP2_CONNECT_AUTHORITY
diff --git a/doc/api/http2.md b/doc/api/http2.md
index d19f395e856e87..e9b06a427c21e4 100644
--- a/doc/api/http2.md
+++ b/doc/api/http2.md
@@ -558,11 +558,103 @@ added: REPLACEME
Calls [`unref()`][`net.Socket.prototype.unref`] on this `Http2Session`
instance's underlying [`net.Socket`].
+### Class: ServerHttp2Session
+
+
+#### serverhttp2session.altsvc(alt, originOrStream)
+
+
+* `alt` {string} A description of the alternative service configuration as
+ defined by [RFC 7838][].
+* `originOrStream` {number|string|URL|Object} Either a URL string specifying
+ the origin (or an Object with an `origin` property) or the numeric identifier
+ of an active `Http2Stream` as given by the `http2stream.id` property.
+
+Submits an `ALTSVC` frame (as defined by [RFC 7838][]) to the connected client.
+
+```js
+const http2 = require('http2');
+
+const server = http2.createServer();
+server.on('session', (session) => {
+ // Set altsvc for origin https://example.org:80
+ session.altsvc('h2=":8000"', 'https://example.org:80');
+});
+
+server.on('stream', (stream) => {
+ // Set altsvc for a specific stream
+ stream.session.altsvc('h2=":8000"', stream.id);
+});
+```
+
+Sending an `ALTSVC` frame with a specific stream ID indicates that the alternate
+service is associated with the origin of the given `Http2Stream`.
+
+The `alt` and origin string *must* contain only ASCII bytes and are
+strictly interpreted as a sequence of ASCII bytes. The special value `'clear'`
+may be passed to clear any previously set alternative service for a given
+domain.
+
+When a string is passed for the `originOrStream` argument, it will be parsed as
+a URL and the origin will be derived. For insetance, the origin for the
+HTTP URL `'https://example.org/foo/bar'` is the ASCII string
+`'https://example.org'`. An error will be thrown if either the given string
+cannot be parsed as a URL or if a valid origin cannot be derived.
+
+A `URL` object, or any object with an `origin` property, may be passed as
+`originOrStream`, in which case the value of the `origin` property will be
+used. The value of the `origin` property *must* be a properly serialized
+ASCII origin.
+
+#### Specifying alternative services
+
+The format of the `alt` parameter is strictly defined by [RFC 7838][] as an
+ASCII string containing a comma-delimited list of "alternative" protocols
+associated with a specific host and port.
+
+For example, the value `'h2="example.org:81"'` indicates that the HTTP/2
+protocol is available on the host `'example.org'` on TCP/IP port 81. The
+host and port *must* be contained within the quote (`"`) characters.
+
+Multiple alternatives may be specified, for instance: `'h2="example.org:81",
+h2=":82"'`
+
+The protocol identifier (`'h2'` in the examples) may be any valid
+[ALPN Protocol ID][].
+
+The syntax of these values is not validated by the Node.js implementation and
+are passed through as provided by the user or received from the peer.
+
### Class: ClientHttp2Session
+#### Event: 'altsvc'
+
+
+The `'altsvc'` event is emitted whenever an `ALTSVC` frame is received by
+the client. The event is emitted with the `ALTSVC` value, origin, and stream
+ID, if any. If no `origin` is provided in the `ALTSVC` frame, `origin` will
+be an empty string.
+
+```js
+const http2 = require('http2');
+const client = http2.connect('https://example.org');
+
+client.on('altsvc', (alt, origin, stream) => {
+ console.log(alt);
+ console.log(origin);
+ console.log(stream);
+});
+```
+
#### clienthttp2session.request(headers[, options])