ngrok Agent API - ngrok documentation

If you want to programmatically control the ngrok agent, the Agent SDKs are usually a more flexible and powerful choice.

Overview

The ngrok agent exposes an HTTP API that enables programmatic access of:

Collect status and metrics information
Collect and replay captured requests
Start and stop endpoints dynamically

Base URL and Authentication


Base URL	`http://127.0.0.1:4040/api`
Authentication	None

The ngrok agent API is exposed as part of ngrok’s local web inspection interface. Because it is served on a local interface, the API has no authentication. The Base URL will change if you override web_addr in your configuration file.

Access the root API resource of a running ngrok agent

curl http://localhost:4040/api/

Supported Content Types

Request parameters must be encoded to the API using application/json. Ensure that your client sets the request’s Content-Type header appropriately. All responses returned by the API are application/json.

Versioning and API Stability

The ngrok agent API guarantees that breaking changes to the API will never be made unless the caller explicitly opts in to a newer version. The mechanism by which a caller opts into a new version of the API will be determined in the future when it becomes necessary. Examples of non-breaking changes to the API that will not be opt-in include the following.

The addition of new resources
The addition of new methods to existing resources
The addition of new fields on existing resource representations
Bug fixes which change the API to match documented behavior

The ngrok agent API accessible at http://localhost:4040/api supports only the v2 agent configuration format. If you are using or planning to use configuration version 3, refer to the Agent Config Version 3 documentation for guidance.

List Tunnels

Returns a list of running tunnels with status and metrics information.

Request

GET/api/tunnels

Response

Parameters


`tunnels`	list of all running tunnels. See the 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. The request body parameters are the same as those you would use to define the tunnel in the configuration file.

Request

POST/api/tunnels

Parameters

Parameter names and behaviors are identical to those those defined in the configuration file. Use the tunnel definitions section as a reference for configuration parameters and their behaviors.

Example request body

{
    "addr": "22",
    "proto": "tcp",
    "name": "ssh"
}

Response

201 status code with a response body describing the started tunnel. See the Tunnel detail resource for docs on the parameters of the response object

Example Response

{
    "name": "",
    "uri": "/api/tunnels/",
    "public_url": "tcp://0.tcp.ngrok.io:53476",
    "proto": "tcp",
    "config": {
        "addr": "localhost:22",
        "inspect": false
    },
    "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
        }
    }
}

Tunnel detail

Get status and metrics about the named running tunnel

Request

GET/api/tunnels/:name

Response

Example Response

{
    "name": "command_line",
    "uri": "/api/tunnels/command_line",
    "public_url": "https://ac294125.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
        }
    }
}

Stop tunnel

Stop a running tunnel

Request

DELETE/api/tunnels/:name

Response

204 status code with an empty body

List Captured Requests

Returns a list of all HTTP requests captured for inspection. This will only return requests that are still in memory (ngrok evicts captured requests when their memory usage exceeds inspect_db_size)

Request

GET/api/requests/http

Query Parameters


`limit`	maximum number of requests to return
`tunnel_name`	filter requests only for the given tunnel name

Example Request

curl http://localhost:4040/api/requests/http?limit=50

Response


`requests`	list of captured requests. See the Captured Request Detail resource for docs on the request objects

Example Response

{
    "uri": "/api/requests/http",
    "requests": [
        {
            "uri": "/api/requests/http/548fb5c700000002",
            "id": "548fb5c700000002",
            "tunnel_name": "command_line (http)",
            "remote_addr": "192.168.100.25",
            "start": "2014-12-15T20:32:07-08:00",
            "duration": 3893202,
            "request": {
                "method": "GET",
                "proto": "HTTP/1.1",
                "headers": {
                    "Accept": [
                        "*/*"
                    ],
                    "Accept-Encoding": [
                        "gzip, deflate, sdch"
                    ],
                    "Accept-Language": [
                        "en-US,en;q=0.8"
                    ],
                    "Connection": [
                        "keep-alive"
                    ],
                    "User-Agent": [
                        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36"
                    ],
                    "X-Original-Host": [
                        "c159663f.ngrok.app"
                    ]
                },
                "uri": "/favicon.ico",
                "raw": "<BASE64 ENCODED BYTES>"
            },
            "response": {
                "status": "502 Bad Gateway",
                "status_code": 502,
                "proto": "HTTP/1.1",
                "headers": {
                    "Content-Length": [
                        "1716"
                    ]
                },
                "raw": "<BASE64 ENCODED BYTES>"
            }
        }
    ]
}

Replay Captured Request

Replays a request against the local endpoint of a tunnel

Request

POST/api/requests/http

Parameters


`id`	id of request to replay
`tunnel_name`	name of the tunnel to play the request against. If unspecified, the request is played against the same tunnel it was recorded on

Example Request

curl -H "Content-Type: application/json" -d '{"id": "548fb5c700000002"}' http://localhost:4040/api/requests/http

Response

204 status code with an empty body

Delete Captured Requests

Deletes all captured requests

Request

DELETE/api/requests/http

Response

204 status code with no response body

Captured Request Detail

Returns metadata and raw bytes of a captured request. The raw data is base64-encoded in the JSON response. The response value maybe null if the local server has not yet responded to a request.

Request

GET/api/requests/http/:request_id

Response

Example Response

{
    "uri": "/api/requests/http/548fb5c700000002",
    "id": "548fb5c700000002",
    "tunnel_name": "command_line (http)",
    "remote_addr": "192.168.100.25",
    "start": "2014-12-15T20:32:07-08:00",
    "duration": 3893202,
    "request": {
        "method": "GET",
        "proto": "HTTP/1.1",
        "headers": {
            "Accept": [
                "*/*"
            ],
            "Accept-Encoding": [
                "gzip, deflate, sdch"
            ],
            "Accept-Language": [
                "en-US,en;q=0.8"
            ],
            "Connection": [
                "keep-alive"
            ],
            "User-Agent": [
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36"
            ],
            "X-Original-Host": [
                "c159663f.ngrok.app"
            ]
        },
        "uri": "/favicon.ico",
        "raw": "<BASE64 ENCODED BYTES>"
    },
    "response": {
        "status": "502 Bad Gateway",
        "status_code": 502,
        "proto": "HTTP/1.1",
        "headers": {
            "Content-Length": [
                "1716"
            ]
        },
        "raw": "<BASE64 ENCODED BYTES>"
    }
}

Agent Status

Get status and metrics about the running agent

Request

GET /api/status

Example Request

curl http://localhost:4040/api/status

Response

200 status code with a json response describing the status of the agent

Example Response

{
    "status": "online",
    "agent_version": "3.9.0",
    "session": {
        "legs": [
            {
                "region": "au",
                "latency": "87ms"
            }
        ]
    },
    "uri": "/api/status"
}

CLI

Configuration file

Agent TLS Termination

​Overview

​Base URL and Authentication

​Access the root API resource of a running ngrok agent

​Supported Content Types

​Versioning and API Stability

​List Tunnels

​Request

​Response

​Parameters

​Example Response

​Start tunnel

​Request

​Parameters

​Example request body

​Response

​Example Response

​Tunnel detail

​Request

​Response

​Example Response

​Stop tunnel

​Request

​Response

​List Captured Requests

​Request

​Query Parameters

​Example Request

​Response

​Example Response

​Replay Captured Request

​Request

​Parameters

​Example Request

​Response

​Delete Captured Requests

​Request

​Response

​Captured Request Detail

​Request

​Response

​Example Response

​Agent Status

​Request

​Example Request

​Response

​Example Response

Overview

Base URL and Authentication

Access the root API resource of a running ngrok agent

Supported Content Types

Versioning and API Stability

List Tunnels

Request

Response

Parameters

Example Response

Start tunnel

Request

Parameters

Example request body

Response

Example Response

Tunnel detail

Request

Response

Example Response

Stop tunnel

Request

Response

List Captured Requests

Request

Query Parameters

Example Request

Response

Example Response

Replay Captured Request

Request

Parameters

Example Request

Response

Delete Captured Requests

Request

Response

Captured Request Detail

Request

Response

Example Response

Agent Status

Request

Example Request

Response

Example Response