From 30c9f1a850df67b9e74a1235ff3a4193eef64d35 Mon Sep 17 00:00:00 2001 From: Shaquil Hansford Date: Tue, 10 Feb 2026 10:26:32 -0500 Subject: [PATCH 1/5] Restructure Secure Tunnels IA wip --- agent/api.mdx | 2 +- agent/index.mdx | 4 +-- agent/upgrade-v2-v3.mdx | 2 +- agent/web-inspection-interface.mdx | 2 +- docs.json | 55 +++++++++++++----------------- 5 files changed, 28 insertions(+), 37 deletions(-) diff --git a/agent/api.mdx b/agent/api.mdx index b8a1c330ac..8410dbfddc 100644 --- a/agent/api.mdx +++ b/agent/api.mdx @@ -1,6 +1,6 @@ --- title: ngrok Agent API -sidebarTitle: API +sidebarTitle: Agent API description: The ngrok agent exposes an HTTP API for collecting metrics and managing endpoints. --- diff --git a/agent/index.mdx b/agent/index.mdx index 4692d891ea..773ba74269 100644 --- a/agent/index.mdx +++ b/agent/index.mdx @@ -1,6 +1,6 @@ --- -title: ngrok Agent -sidebarTitle: ngrok Agent +title: ngrok Agent CLI Overview +sidebarTitle: Overview description: The ngrok agent is a lightweight command-line program that forwards traffic from endpoints it creates on the ngrok cloud service to your upstream application services. --- diff --git a/agent/upgrade-v2-v3.mdx b/agent/upgrade-v2-v3.mdx index 12e0a1a600..3bce8bcb57 100644 --- a/agent/upgrade-v2-v3.mdx +++ b/agent/upgrade-v2-v3.mdx @@ -1,6 +1,6 @@ --- title: Upgrade to ngrok Agent v3 -sidebarTitle: Upgrade to v3 +sidebarTitle: Upgrading Your Agent Config to v3 description: Learn the best way to upgrade from ngrok agent v2 to v3. --- diff --git a/agent/web-inspection-interface.mdx b/agent/web-inspection-interface.mdx index 684e6d7d19..ad72aee7d0 100644 --- a/agent/web-inspection-interface.mdx +++ b/agent/web-inspection-interface.mdx @@ -1,6 +1,6 @@ --- title: ngrok Agent Web Inspection Interface -sidebarTitle: Web Inspection Interface +sidebarTitle: Observe Agent Traffic description: Learn how to use the ngrok agent's web inspection interface at localhost:4040 to view HTTP requests and responses in real-time. --- diff --git a/docs.json b/docs.json index 39d851ed9d..6a296ac23c 100644 --- a/docs.json +++ b/docs.json @@ -519,52 +519,50 @@ "item": "Secure Tunnels", "pages": [ "agent/overview", - "agent/index", - "agent/upgrade-v2-v3", + "agent/api", "agent/version-support-policy", { - "group": "Observing Agent Traffic", - "pages": [ - "agent/web-inspection-interface" - ] - }, - { - "group": "CLI", + "group": "Agent CLI", "pages": [ + "agent/index", "agent/cli", "agent/cli-api", - "agent/diagnose" - ] - }, - { + "agent/diagnose", + { "group": "CLI Configuration File", "pages": [ "agent/config/index", "agent/config/v3", "agent/config/v2" ] + } + ] }, + { - "group": "Reference", + "group": "Agent SDKs", "pages": [ - "agent/api", - { - "group": "Agent SDKs", - "pages": [ - "agent-sdks/index", - "getting-started/javascript", - "getting-started/go", - "getting-started/python", - "getting-started/rust" - ] - } + "agent-sdks/index", + "getting-started/javascript", + "getting-started/go", + "getting-started/python", + "getting-started/rust" ] }, { "group": "Guides", "pages": [ + "agent/upgrade-v2-v3", + { + "group": "Agent TLS Termination", + "pages": [ + "agent/agent-tls-termination", + "agent/agent-mutual-tls-termination" + ] + }, "agent/ssh-reverse-tunnel-agent", "agent/connect-url", + "agent/web-inspection-interface", { "group": "Docker", "pages": [ @@ -574,13 +572,6 @@ ] } ] - }, - { - "group": "Agent TLS Termination", - "pages": [ - "agent/agent-tls-termination", - "agent/agent-mutual-tls-termination" - ] } ] }, From e774e2e06557afdec7c92e66db11b8bacd40af1c Mon Sep 17 00:00:00 2001 From: Shaquil Hansford Date: Tue, 10 Feb 2026 10:40:24 -0500 Subject: [PATCH 2/5] Move deprecated api content down --- agent/api.mdx | 126 +++++++++++++++++++++++++------------------------- 1 file changed, 63 insertions(+), 63 deletions(-) diff --git a/agent/api.mdx b/agent/api.mdx index 8410dbfddc..7c109ba0bc 100644 --- a/agent/api.mdx +++ b/agent/api.mdx @@ -52,69 +52,6 @@ Examples of non-breaking changes to the API that will not be opt-in include: - The addition of new fields on existing resource representations - Bug fixes that change the API to match documented behavior -## List tunnels - - - -This API is deprecated. Use the [list endpoints API](#list-endpoints) instead. - - - -Returns a list of running tunnels with status and metrics information. - -### Request - -`GET/api/tunnels` - -### Parameters - -| | | -| --------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `tunnels` | List of all running tunnels. See the [Tunnel detail](#tunnel-detail) resource for docs on the parameters of each tunnel object. | - -### Example response - -``` -{ - "tunnels": [ - { - "name": "command_line", - "uri": "/api/tunnels/command_line", - "public_url": "https://d95211d2.ngrok.app", - "proto": "https", - "config": { - "addr": "localhost:80", - "inspect": true - }, - "metrics": { - "conns": { - "count": 0, - "gauge": 0, - "rate1": 0, - "rate5": 0, - "rate15": 0, - "p50": 0, - "p90": 0, - "p95": 0, - "p99": 0 - }, - "http": { - "count": 0, - "rate1": 0, - "rate5": 0, - "rate15": 0, - "p50": 0, - "p90": 0, - "p95": 0, - "p99": 0 - } - } - } - ], - "uri": "/api/tunnels" -} -``` - ## Start tunnel Dynamically starts a new tunnel on the ngrok agent. @@ -617,3 +554,66 @@ curl http://localhost:4040/api/status "uri": "/api/status" } ``` + +## List tunnels (Deprecated) + + + +This API is deprecated. Use the [list endpoints API](#list-endpoints) instead. + + + +Returns a list of running tunnels with status and metrics information. + +### Request + +`GET/api/tunnels` + +### Parameters + +| | | +| --------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `tunnels` | List of all running tunnels. See the [Tunnel detail](#tunnel-detail) resource for docs on the parameters of each tunnel object. | + +### Example response + +``` +{ + "tunnels": [ + { + "name": "command_line", + "uri": "/api/tunnels/command_line", + "public_url": "https://d95211d2.ngrok.app", + "proto": "https", + "config": { + "addr": "localhost:80", + "inspect": true + }, + "metrics": { + "conns": { + "count": 0, + "gauge": 0, + "rate1": 0, + "rate5": 0, + "rate15": 0, + "p50": 0, + "p90": 0, + "p95": 0, + "p99": 0 + }, + "http": { + "count": 0, + "rate1": 0, + "rate5": 0, + "rate15": 0, + "p50": 0, + "p90": 0, + "p95": 0, + "p99": 0 + } + } + } + ], + "uri": "/api/tunnels" +} +``` From 3ce6636ba117cc2eb9d39be15bac0e1279dcfe30 Mon Sep 17 00:00:00 2001 From: Shaquil Hansford Date: Tue, 10 Feb 2026 10:44:22 -0500 Subject: [PATCH 3/5] Reorder agent api docs --- agent/api.mdx | 4 ++-- docs.json | 7 ++++++- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/agent/api.mdx b/agent/api.mdx index 7c109ba0bc..0818471daf 100644 --- a/agent/api.mdx +++ b/agent/api.mdx @@ -1,6 +1,6 @@ --- -title: ngrok Agent API -sidebarTitle: Agent API +title: ngrok Agent API Reference +sidebarTitle: Reference description: The ngrok agent exposes an HTTP API for collecting metrics and managing endpoints. --- diff --git a/docs.json b/docs.json index 6a296ac23c..028f21cb7a 100644 --- a/docs.json +++ b/docs.json @@ -519,7 +519,6 @@ "item": "Secure Tunnels", "pages": [ "agent/overview", - "agent/api", "agent/version-support-policy", { "group": "Agent CLI", @@ -549,6 +548,12 @@ "getting-started/rust" ] }, + { + "group": "Agent API", + "pages": [ + "agent/api" + ] + }, { "group": "Guides", "pages": [ From 888535ed1d80184aae91fdabce88a4f6ee400907 Mon Sep 17 00:00:00 2001 From: Shaquil Hansford Date: Tue, 10 Feb 2026 10:54:05 -0500 Subject: [PATCH 4/5] Move more stufff around --- .vale/styles/StyleRules/Headings.yml | 1 + agent/api.mdx | 6 ++++-- agent/overview.mdx | 2 +- docs.json | 6 +++--- 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/.vale/styles/StyleRules/Headings.yml b/.vale/styles/StyleRules/Headings.yml index 571c56fd9b..da2b9cbd84 100644 --- a/.vale/styles/StyleRules/Headings.yml +++ b/.vale/styles/StyleRules/Headings.yml @@ -56,6 +56,7 @@ exceptions: - Curity - DCR-based - DDoS + - Deprecated - Descope - Dev domains - DNS diff --git a/agent/api.mdx b/agent/api.mdx index 0818471daf..8ae6c929ea 100644 --- a/agent/api.mdx +++ b/agent/api.mdx @@ -4,7 +4,9 @@ sidebarTitle: Reference description: The ngrok agent exposes an HTTP API for collecting metrics and managing endpoints. --- -## Overview + + You can also interact with the agent API [via the CLI](/agent/cli-api). + The ngrok agent exposes an HTTP API that enables you to: @@ -14,7 +16,7 @@ The ngrok agent exposes an HTTP API that enables you to: -If you need to programmatically control the ngrok agent, consider using one of the [Agent SDKs](/agent-sdks/) instead of the API. +To programmatically control the ngrok agent, prefer an [Agent SDK](/agent-sdks/) over the API. diff --git a/agent/overview.mdx b/agent/overview.mdx index 5720c71357..b74c6349a2 100644 --- a/agent/overview.mdx +++ b/agent/overview.mdx @@ -1,5 +1,5 @@ --- -title: Secure Tunnels Overview +title: ngrok Agent Overview sidebarTitle: Overview description: Learn about ngrok's secure tunnel agent for exposing local services, connecting devices, and creating secure remote access. --- diff --git a/docs.json b/docs.json index 028f21cb7a..91c6006c51 100644 --- a/docs.json +++ b/docs.json @@ -516,7 +516,7 @@ ] }, { - "item": "Secure Tunnels", + "item": "The ngrok Agent", "pages": [ "agent/overview", "agent/version-support-policy", @@ -526,7 +526,6 @@ "agent/index", "agent/cli", "agent/cli-api", - "agent/diagnose", { "group": "CLI Configuration File", "pages": [ @@ -534,7 +533,8 @@ "agent/config/v3", "agent/config/v2" ] - } + }, + "agent/diagnose" ] }, From 237a180a3dc68420e3b86c9f2444aa7e9a7a7fe1 Mon Sep 17 00:00:00 2001 From: Shaquil Hansford Date: Thu, 19 Feb 2026 13:42:07 -0500 Subject: [PATCH 5/5] Update docs.json --- docs.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs.json b/docs.json index 91c6006c51..049506cc41 100644 --- a/docs.json +++ b/docs.json @@ -555,16 +555,16 @@ ] }, { - "group": "Guides", - "pages": [ - "agent/upgrade-v2-v3", - { "group": "Agent TLS Termination", "pages": [ "agent/agent-tls-termination", "agent/agent-mutual-tls-termination" ] }, + { + "group": "Guides", + "pages": [ + "agent/upgrade-v2-v3", "agent/ssh-reverse-tunnel-agent", "agent/connect-url", "agent/web-inspection-interface",