Skip to content

Restructure Secure Tunnels IA #1951

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
S3Prototype wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Restructure Secure Tunnels IA #1951

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
30c9f1a
Restructure Secure Tunnels IA
S3Prototype Feb 10, 2026
e774e2e
Move deprecated api content down
S3Prototype Feb 10, 2026
3ce6636
Reorder agent api docs
S3Prototype Feb 10, 2026
888535e
Move more stufff around
S3Prototype Feb 10, 2026
237a180
Update docs.json
S3Prototype Feb 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .vale/styles/StyleRules/Headings.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ exceptions:
- Curity
- DCR-based
- DDoS
- Deprecated
- Descope
- Dev domains
- DNS
Expand Down
136 changes: 69 additions & 67 deletions agent/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
---
title: ngrok Agent API
sidebarTitle: API
title: ngrok Agent API Reference
sidebarTitle: Reference
description: The ngrok agent exposes an HTTP API for collecting metrics and managing endpoints.
---

## Overview
<Info>
You can also interact with the agent API [via the CLI](/agent/cli-api).
</Info>

The ngrok agent exposes an HTTP API that enables you to:

Expand All @@ -14,7 +16,7 @@ The ngrok agent exposes an HTTP API that enables you to:

<Tip>

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.

</Tip>

Expand Down Expand Up @@ -52,69 +54,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

<Warning>

This API is deprecated. Use the [list endpoints API](#list-endpoints) instead.

</Warning>

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.
Expand Down Expand Up @@ -617,3 +556,66 @@ curl http://localhost:4040/api/status
"uri": "/api/status"
}
```

## List tunnels (Deprecated)

<Warning>

This API is deprecated. Use the [list endpoints API](#list-endpoints) instead.

</Warning>

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"
}
```
4 changes: 2 additions & 2 deletions agent/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
---

Expand Down
2 changes: 1 addition & 1 deletion agent/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
---
Expand Down
2 changes: 1 addition & 1 deletion agent/upgrade-v2-v3.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
---

Expand Down
2 changes: 1 addition & 1 deletion agent/web-inspection-interface.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
---

Expand Down
60 changes: 28 additions & 32 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -516,55 +516,58 @@
]
},
{
"item": "Secure Tunnels",
"item": "The ngrok Agent",
"pages": [
"agent/overview",
"agent/index",
"agent/upgrade-v2-v3",
"agent/version-support-policy",
{
"group": "Observing Agent Traffic",
"group": "Agent CLI",
"pages": [
"agent/index",
"agent/cli",
"agent/cli-api",
{
"group": "CLI Configuration File",
"pages": [
"agent/web-inspection-interface"
"agent/config/index",
"agent/config/v3",
"agent/config/v2"
]
},
"agent/diagnose"
]
},

{
"group": "CLI",
"group": "Agent SDKs",
"pages": [
"agent/cli",
"agent/cli-api",
"agent/diagnose"
"agent-sdks/index",
"getting-started/javascript",
"getting-started/go",
"getting-started/python",
"getting-started/rust"
]
},
{
"group": "CLI Configuration File",
"group": "Agent API",
"pages": [
"agent/config/index",
"agent/config/v3",
"agent/config/v2"
"agent/api"
]
},
{
"group": "Reference",
"group": "Agent TLS Termination",
"pages": [
"agent/api",
{
"group": "Agent SDKs",
"pages": [
"agent-sdks/index",
"getting-started/javascript",
"getting-started/go",
"getting-started/python",
"getting-started/rust"
]
}
"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",
{
"group": "Docker",
"pages": [
Expand All @@ -574,13 +577,6 @@
]
}
]
},
{
"group": "Agent TLS Termination",
"pages": [
"agent/agent-tls-termination",
"agent/agent-mutual-tls-termination"
]
}
]
},
Expand Down