Skip to main content

Overview

The ngrok agent exposes an HTTP API that enables you to:
  • Collect status and metrics information
  • Collect and replay captured requests
  • Start and stop endpoints dynamically
If you need to programmatically control the ngrok agent, consider using one of the Agent SDKs instead of the API.

Base URL and authentication

Base URLhttp://127.0.0.1:4040/api
AuthenticationNone
The ngrok agent API is exposed as part of ngrok’s local web inspection interface. Because it’s 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 addition of new resources
  • The addition of new methods to existing resources
  • The addition of new fields on existing resource representations
  • Bug fixes that change the API to match documented behavior

List tunnels

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

Request

GET/api/tunnels

Parameters

tunnelsList 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 Created 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

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 No Content status code with an empty body.

List endpoints

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

Request

GET/api/endpoints

Response

200 OK status code with a JSON response containing an array of endpoint objects.

Example response

{
  "endpoints": [
    {
      "name": "command_line",
      "uri": "/api/endpoints/command_line",
      "url": "https://871e40f2d4c2.ngrok.paid.lan",
      "upstream": {
        "url": "http://localhost:8000",
        "protocol": "https"
      },
      "inspect": true,
      "traffic_policy": "on_http_request:\n - actions:\n - type: custom-response\n config:\n status_code: 200\n body: Hello, World!\n",
      "pooling_enabled": true
    }
  ]
}

Endpoint detail

Get status and metrics about the named running endpoint.

Request

GET/api/endpoints/:name

Response

200 OK status code with endpoint JSON for success. 404 Not Found if the provided name doesn’t correspond to an endpoint.

Example response

{
  "name": "command_line",
  "uri": "/api/endpoints/command_line",
  "url": "https://871e40f2d4c2.ngrok.paid.lan",
  "upstream": {
    "url": "http://localhost:8000",
    "protocol": "https"
  },
  "inspect": true,
  "traffic_policy": "on_http_request:\n - actions:\n - type: custom-response\n config:\n status_code: 200\n body: Hello, World!\n",
  "pooling_enabled": 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
    }
  }
}

Create endpoint

Dynamically creates a new endpoint on the ngrok agent.

Request

POST/api/endpoints

Response

201 Created on success. 400 Bad Request for malformed payloads.

Example request body

{
  "name": "my_awesome_tunnel",
  "url": "https://iamawesome.ngrok.paid.lan",
  "upstream": {
    "url": "8001"
  },
  "pooling_enabled": true
}

Update endpoint

Updates an existing endpoint or creates a new one if it doesn’t exist.

Request

PUT/api/endpoints/:name

Response

200 OK if an existing endpoint is updated. 201 Created if an endpoint is created. 400 Bad Request for malformed payloads.

Example request body

{
  "name": "command_line",
  "uri": "/api/endpoints/command_line",
  "url": "https://871e40f2d4c2.ngrok.paid.lan",
  "upstream": {
    "url": "http://localhost:8000",
    "protocol": "https"
  },
  "inspect": true,
  "traffic_policy": "on_http_request:\n - actions:\n - type: custom-response\n config:\n status_code: 200\n body: Hello, World!\n",
  "pooling_enabled": true
}

Delete endpoint

Stop a running endpoint.

Request

DELETE/api/endpoints/:name

Response

204 No Content for successful delete. 404 Not Found if trying to delete a nonexistent endpoint.

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

limitMaximum number of requests to return.
tunnel_nameFilter requests only for the given tunnel name.

Example request

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

Response

requestsList 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

idID of request to replay.
tunnel_nameName 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 No Content status code with an empty body.

Delete captured requests

Deletes all captured requests.

Request

DELETE/api/requests/http

Response

204 No Content 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 may be null if the local server hasn’t responded to a request yet.

Request

GET/api/requests/http/:request_id

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 OK 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"
}