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 URL | http://127.0.0.1:4040/api |
Authentication | None |
web_addr
in your configuration file.
Access the root API resource of a running ngrok agent
Supported content types
Request parameters must be encoded to the API usingapplication/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
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
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
Tunnel detail
Get status and metrics about the named running tunnel.Request
GET/api/tunnels/:name
Example response
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
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
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
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
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 exceedsinspect_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
Response
requests | List of captured requests. See the Captured Request Detail resource for docs on the request objects. |
Example response
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
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. Theresponse
value may be null
if the local server hasn’t responded to a request yet.
Request
GET/api/requests/http/:request_id
Example response
Agent status
Get status and metrics about the running agent.Request
GET /api/status
Example request
Response
200 OK
status code with a JSON response describing the status of the agent.