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