The ngrok agent exposes an HTTP API that grants programmatic access to:
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.
curl http://localhost:4040/api/
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
.
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.
Returns a list of running tunnels with status and metrics information.
tunnels |
list of all running tunnels. See the Tunnel detail resource for docs on the parameters of each tunnel object |
---|
{
"tunnels": [
{
"name": "command_line",
"uri": "/api/tunnels/command_line",
"public_url": "https://d95211d2.ngrok.io",
"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"
}
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.
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.
{
"addr": "22",
"proto": "tcp",
"name": "ssh"
}
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
{
"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
}
}
}
Get status and metrics about the named running tunnel
{
"name": "command_line",
"uri": "/api/tunnels/command_line",
"public_url": "https://ac294125.ngrok.io",
"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 a running tunnel
204 status code with an empty body
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
)
limit |
maximum number of requests to return |
---|---|
tunnel_name |
filter requests only for the given tunnel name |
curl http://localhost:4040/api/requests/http?limit=50
requests |
list of captured requests. See the Captured Request Detail resource for docs on the request objects |
---|
{
"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.io"
]
},
"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>",
}
},
...
]
}
Replays a request against the local endpoint of a tunnel
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 |
curl -H "Content-Type: application/json" -d '{"id": "548fb5c700000002"}' http://localhost:4040/api/requests/http
204 status code with an empty body
Deletes all captured requests
204 status code with no response body
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.
{
"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.io"
]
},
"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>",
}
}