diff --git a/docs/api.md b/docs/api.md
index 4ad2839b..a0c24311 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -73,7 +73,9 @@ all keys except for `url` are optional. value options are separated by `/`.
 | `url`             | `string`  | source URL                                                      | *required* |
 | `audioBitrate`    | `string`  | `320 / 256 / 128 / 96 / 64 / 8` (kbps)                          | `128`      |
 | `audioFormat`     | `string`  | `best / mp3 / ogg / wav / opus`                                 | `mp3`      |
-| `downloadMode`    | `string`  | `auto / audio / mute`                                           | `auto`     |
+| `downloadMode`    | `string`  | `auto / audio / mute / captions`                                | `auto`     |
+| `captionFormat`   | `string`  | `txt / vtt / srt / md`                                          | `txt`      |
+| `captionLanguage` | `string`  | any valid ISO 639-1 language code                               | *none*     |
 | `filenameStyle`   | `string`  | `classic / pretty / basic / nerdy`                              | `basic`    |
 | `videoQuality`    | `string`  | `max / 4320 / 2160 / 1440 / 1080 / 720 / 480 / 360 / 240 / 144` | `1080`     |
 | `disableMetadata` | `boolean` | title, artist, and other info will not be added to the file     | `false`    |
@@ -93,6 +95,36 @@ all keys except for `url` are optional. value options are separated by `/`.
 | `youtubeBetterAudio`    | `boolean` | prefer higher quality youtube audio if possible   | `false` |
 | `youtubeHLS`            | `boolean` | use HLS formats when downloading from youtube     | `false` |
 
+#### standalone youtube captions
+
+set `downloadMode` to `captions` to download a caption or transcript file without
+downloading video or audio. this mode currently supports youtube links.
+
+`captionLanguage` selects the caption language, falling back to `subtitleLang` when
+omitted. if both are omitted, cobalt prefers the first manually provided track and
+falls back to an automatic caption track. when a language is provided, cobalt matches
+the full language code first and then its base language. manually provided captions
+take priority over automatic captions.
+
+`txt` and `md` produce readable transcripts without timestamps. `vtt` preserves the
+original webvtt cues, while `srt` converts those cues to the subrip format.
+
+example request:
+
+```json
+{
+    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+    "downloadMode": "captions",
+    "captionFormat": "txt",
+    "subtitleLang": "en"
+}
+```
+
+the response is a regular [`tunnel`](#tunnelredirect-response) whose filename uses
+the selected extension. caption tunnels use the same expiry and signature checks as
+media tunnels. caption responses also include a `text` tunnel for copying a plain,
+untimed transcript. for `txt` requests, `url` and `text` are the same.
+
 ### response
 body type: `application/json`
 
@@ -109,6 +141,7 @@ the response will always be a JSON object containing the `status` key, which is
 | `status`     | `string` | `tunnel / redirect`                                        |
 | `url`        | `string` | url for the cobalt tunnel, or redirect to an external link |
 | `filename`   | `string` | cobalt-generated filename for the file being downloaded    |
+| `text`       | `string` | plain-text transcript tunnel for caption responses (optional) |
 
 ### local processing response
 | key          | type       | value                                                         |
@@ -186,6 +219,7 @@ all keys in this table are optional.
 |:-------------|:---------|:----------------------------------------------------------------------------|
 | `service`    | `string` | origin service (optional)                                                   |
 | `limit`      | `number` | the maximum downloadable video duration or the rate limit window (optional) |
+| `languages`  | `string[]` | available caption languages when the requested language is missing (optional) |
 
 ## POST `/session`
 used for generating JWT tokens, if enabled. currently, cobalt only supports