Endpoints

List Endpoints

List all active endpoints on the account

Request

GET /endpoints

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/endpoints

Response

Returns a 200 response on success

Example Response

{
	"endpoints": [
		{
			"created_at": "2024-09-10T19:55:17Z",
			"hostport": "8a0b154f56c0.ngrok.paid:443",
			"id": "ep_2ltSwSy6Nm2Lcd79ZQ9c7BeeDkQ",
			"principal_id": {
				"id": "usr_2ltStws6MiusgDndbKs6Fb0CCpV",
				"uri": ""
			},
			"proto": "https",
			"public_url": "https://8a0b154f56c0.ngrok.paid",
			"tunnel": {
				"id": "tn_2ltSwSy6Nm2Lcd79ZQ9c7BeeDkQ",
				"uri": "https://api.ngrok.com/tunnels/tn_2ltSwSy6Nm2Lcd79ZQ9c7BeeDkQ"
			},
			"tunnel_session": {
				"id": "ts_2ltSwPuLx2p9UeRQh2skkV2RM49",
				"uri": "https://api.ngrok.com/tunnel_sessions/ts_2ltSwPuLx2p9UeRQh2skkV2RM49"
			},
			"type": "ephemeral",
			"updated_at": "2024-09-10T19:55:17Z",
			"upstream_url": "http://localhost:80",
			"url": "https://8a0b154f56c0.ngrok.paid"
		},
		{
			"created_at": "2024-09-10T19:55:14Z",
			"domain": {
				"id": "rd_2ltSw8dWZkIcBb2YkhDUDZQxV2q",
				"uri": "https://api.ngrok.com/reserved_domains/rd_2ltSw8dWZkIcBb2YkhDUDZQxV2q"
			},
			"edge": {
				"id": "edgtls_2ltSw6Y7SttlrgUG5N4fMeNOla5",
				"uri": "https://api.ngrok.com/edges/tls/edgtls_2ltSw6Y7SttlrgUG5N4fMeNOla5"
			},
			"hostport": "endpoint-example2.com:443",
			"id": "ep_2ltSw2LYy38FNnx1azGIs71UgoB",
			"proto": "tls",
			"public_url": "tls://endpoint-example2.com",
			"type": "edge",
			"updated_at": "2024-09-10T19:55:14Z"
		}
	],
	"next_page_uri": null,
	"uri": "https://api.ngrok.com/endpoints"
}

Fields

Name	Type	Description
endpoints	Endpoint	the list of all active endpoints on this account
uri	string	URI of the endpoints list API resource
next_page_uri	string	URI of the next page, or null if there is no next page

Endpoint fields

Name	Type	Description
id	string	unique endpoint resource identifier
region	string	identifier of the region this endpoint belongs to
created_at	string	timestamp when the endpoint was created in RFC 3339 format
updated_at	string	timestamp when the endpoint was updated in RFC 3339 format
public_url	string	URL of the hostport served by this endpoint
proto	string	protocol served by this endpoint. one of http, https, tcp, or tls
scheme	string
hostport	string	hostport served by this endpoint (hostname:port) -> soon to be deprecated
host	string
port	int64
type	string	whether the endpoint is ephemeral (served directly by an agent-initiated tunnel) or edge (served by an edge) or cloud (represents a cloud endpoint)
metadata	string	user-supplied metadata of the associated tunnel or edge object
description	string	user-supplied description of the associated tunnel
domain	Ref	the domain reserved for this endpoint
tcp_addr	Ref	the address reserved for this endpoint
tunnel	Ref	the tunnel serving requests to this endpoint, if this is an ephemeral endpoint
edge	Ref	the edge serving requests to this endpoint, if this is an edge endpoint
upstream_url	string	the local address the tunnel forwards to
upstream_proto	string	the protocol the agent uses to forward with
url	string	the url of the endpoint
principal_id	Ref	The ID of the owner (bot or user) that owns this endpoint
traffic_policy	string	The traffic policy attached to this endpoint
bindings	List<string>	the bindings associated with this endpoint
tunnel_session	Ref	The tunnel session of the agent for this endpoint

Ref fields

Name	Type	Description
id	string	a resource identifier
uri	string	a uri for locating a resource

Get Endpoint

Get the status of an endpoint by ID

Request

GET /endpoints/{id}

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/endpoints/ep_2ltSwSy6Nm2Lcd79ZQ9c7BeeDkQ

Response

Returns a 200 response on success

Example Response

{
	"created_at": "2024-09-10T19:55:17Z",
	"hostport": "8a0b154f56c0.ngrok.paid:443",
	"id": "ep_2ltSwSy6Nm2Lcd79ZQ9c7BeeDkQ",
	"principal_id": {
		"id": "usr_2ltStws6MiusgDndbKs6Fb0CCpV",
		"uri": ""
	},
	"proto": "https",
	"public_url": "https://8a0b154f56c0.ngrok.paid",
	"tunnel": {
		"id": "tn_2ltSwSy6Nm2Lcd79ZQ9c7BeeDkQ",
		"uri": "https://api.ngrok.com/tunnels/tn_2ltSwSy6Nm2Lcd79ZQ9c7BeeDkQ"
	},
	"tunnel_session": {
		"id": "ts_2ltSwPuLx2p9UeRQh2skkV2RM49",
		"uri": "https://api.ngrok.com/tunnel_sessions/ts_2ltSwPuLx2p9UeRQh2skkV2RM49"
	},
	"type": "ephemeral",
	"updated_at": "2024-09-10T19:55:17Z",
	"upstream_url": "http://localhost:80",
	"url": "https://8a0b154f56c0.ngrok.paid"
}

Fields

Name	Type	Description
id	string	unique endpoint resource identifier
region	string	identifier of the region this endpoint belongs to
created_at	string	timestamp when the endpoint was created in RFC 3339 format
updated_at	string	timestamp when the endpoint was updated in RFC 3339 format
public_url	string	URL of the hostport served by this endpoint
proto	string	protocol served by this endpoint. one of http, https, tcp, or tls
scheme	string
hostport	string	hostport served by this endpoint (hostname:port) -> soon to be deprecated
host	string
port	int64
type	string	whether the endpoint is ephemeral (served directly by an agent-initiated tunnel) or edge (served by an edge) or cloud (represents a cloud endpoint)
metadata	string	user-supplied metadata of the associated tunnel or edge object
description	string	user-supplied description of the associated tunnel
domain	Ref	the domain reserved for this endpoint
tcp_addr	Ref	the address reserved for this endpoint
tunnel	Ref	the tunnel serving requests to this endpoint, if this is an ephemeral endpoint
edge	Ref	the edge serving requests to this endpoint, if this is an edge endpoint
upstream_url	string	the local address the tunnel forwards to
upstream_proto	string	the protocol the agent uses to forward with
url	string	the url of the endpoint
principal_id	Ref	The ID of the owner (bot or user) that owns this endpoint
traffic_policy	string	The traffic policy attached to this endpoint
bindings	List<string>	the bindings associated with this endpoint
tunnel_session	Ref	The tunnel session of the agent for this endpoint

Ref fields

Name	Type	Description
id	string	a resource identifier
uri	string	a uri for locating a resource