Endpoints

Create Endpoint

Create an endpoint, currently available only for cloud endpoints

Request

POST /endpoints

Example Request

curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"bindings":["public"],"description":"sample cloud endpoint","metadata":"{\"environment\": \"staging\"}","traffic_policy":"{\"on_http_request\":[{\"actions\":[{\"type\":\"deny\",\"config\":{\"status_code\":404}}]}]}","type":"cloud","url":"https://endpoint-example2.com:443"}' \
https://api.ngrok.com/endpoints

Parameters

Name	Type	Description
url	string	the url of the endpoint
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)
traffic_policy	string	The traffic policy attached to this endpoint
description	string	user-supplied description of the associated tunnel
metadata	string	user-supplied metadata of the associated tunnel or edge object
bindings	List<string>	the bindings associated with this endpoint

Response

Returns a 201 response on success

Example Response

{
	"bindings": ["public"],
	"created_at": "2024-10-17T20:26:43Z",
	"description": "sample cloud endpoint",
	"domain": {
		"id": "rd_2na2K4obUiVgxjyGhELNXZRomOt",
		"uri": "https://api.ngrok.com/reserved_domains/rd_2na2K4obUiVgxjyGhELNXZRomOt"
	},
	"hostport": "endpoint-example2.com:443",
	"id": "ep_2na2KihUjFYIhLR6demIzdJsxTH",
	"metadata": "{\"environment\": \"staging\"}",
	"proto": "https",
	"public_url": "https://endpoint-example2.com",
	"traffic_policy": "{\"on_http_request\":[{\"actions\":[{\"type\":\"deny\",\"config\":{\"status_code\":404}}]}]}",
	"type": "cloud",
	"updated_at": "2024-10-17T20:26:43Z",
	"uri": "https://api.ngrok.com/endpoints/ep_2na2KihUjFYIhLR6demIzdJsxTH",
	"url": "https://endpoint-example2.com"
}

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	Ref	The ID of the owner (bot or user) that owns this endpoint
principal_id	Ref	TODO: deprecate me!
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
uri	string	URI of the clep API resource
name	string	user supplied name for the endpoint

Ref fields

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

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": [
		{
			"bindings": ["public"],
			"created_at": "2024-10-17T20:26:41Z",
			"hostport": "e3c98b29d802.ngrok.paid:443",
			"id": "ep_2na2KRmwQ3xUTK7fsBf4gPPtWhu",
			"name": "command_line",
			"principal": {
				"id": "usr_2na2I2d8Ao6a5681xuYxdgYUSB3",
				"uri": ""
			},
			"proto": "https",
			"public_url": "https://e3c98b29d802.ngrok.paid",
			"tunnel": {
				"id": "tn_2na2KRmwQ3xUTK7fsBf4gPPtWhu",
				"uri": "https://api.ngrok.com/tunnels/tn_2na2KRmwQ3xUTK7fsBf4gPPtWhu"
			},
			"tunnel_session": {
				"id": "ts_2na2KPli9fvvUbVYYCIjWPE8zWg",
				"uri": "https://api.ngrok.com/tunnel_sessions/ts_2na2KPli9fvvUbVYYCIjWPE8zWg"
			},
			"type": "ephemeral",
			"updated_at": "2024-10-17T20:26:41Z",
			"upstream_url": "http://localhost:80",
			"url": "https://e3c98b29d802.ngrok.paid"
		},
		{
			"bindings": ["public"],
			"created_at": "2024-10-17T20:26:39Z",
			"domain": {
				"id": "rd_2na2K4obUiVgxjyGhELNXZRomOt",
				"uri": "https://api.ngrok.com/reserved_domains/rd_2na2K4obUiVgxjyGhELNXZRomOt"
			},
			"edge": {
				"id": "edgtls_2na2K2SHqq1jVXErSG2EhkglPNe",
				"uri": "https://api.ngrok.com/edges/tls/edgtls_2na2K2SHqq1jVXErSG2EhkglPNe"
			},
			"hostport": "endpoint-example2.com:443",
			"id": "ep_2na2KDE8CTY0AZG8vME1nBU7Eed",
			"proto": "tls",
			"public_url": "tls://endpoint-example2.com",
			"type": "edge",
			"updated_at": "2024-10-17T20:26:39Z"
		}
	],
	"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	Ref	The ID of the owner (bot or user) that owns this endpoint
principal_id	Ref	TODO: deprecate me!
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
uri	string	URI of the clep API resource
name	string	user supplied name for the 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_2na2KihUjFYIhLR6demIzdJsxTH

Response

Returns a 200 response on success

Example Response

{
	"bindings": ["public"],
	"created_at": "2024-10-17T20:26:44Z",
	"description": "sample cloud endpoint",
	"domain": {
		"id": "rd_2na2K4obUiVgxjyGhELNXZRomOt",
		"uri": "https://api.ngrok.com/reserved_domains/rd_2na2K4obUiVgxjyGhELNXZRomOt"
	},
	"edge": {
		"id": "edgtls_2na2K2SHqq1jVXErSG2EhkglPNe",
		"uri": "https://api.ngrok.com/edges/tls/edgtls_2na2K2SHqq1jVXErSG2EhkglPNe"
	},
	"hostport": "endpoint-example2.com:443",
	"id": "ep_2na2KihUjFYIhLR6demIzdJsxTH",
	"proto": "https",
	"public_url": "https://endpoint-example2.com",
	"type": "cloud",
	"updated_at": "2024-10-17T20:26:44Z",
	"uri": "https://api.ngrok.com/endpoints/ep_2na2KihUjFYIhLR6demIzdJsxTH",
	"url": "https://endpoint-example2.com"
}

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	Ref	The ID of the owner (bot or user) that owns this endpoint
principal_id	Ref	TODO: deprecate me!
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
uri	string	URI of the clep API resource
name	string	user supplied name for the endpoint

Ref fields

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

Update Endpoint

Update an Endpoint by ID, currently available only for cloud endpoints

Request

PATCH /endpoints/{id}

Example Request

curl \
-X PATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"Sample Cloud Endpoint"}' \
https://api.ngrok.com/endpoints/ep_2na2KihUjFYIhLR6demIzdJsxTH

Parameters

Name	Type	Description
id	string	unique endpoint resource identifier
url	string	the url of the endpoint
traffic_policy	string	The traffic policy attached to this endpoint
description	string	user-supplied description of the associated tunnel
metadata	string	user-supplied metadata of the associated tunnel or edge object
bindings	List<string>	the bindings associated with this endpoint

Response

Returns a 200 response on success

Example Response

{
	"bindings": ["public"],
	"created_at": "2024-10-17T20:26:43Z",
	"description": "Sample Cloud Endpoint",
	"domain": {
		"id": "rd_2na2K4obUiVgxjyGhELNXZRomOt",
		"uri": "https://api.ngrok.com/reserved_domains/rd_2na2K4obUiVgxjyGhELNXZRomOt"
	},
	"hostport": "endpoint-example2.com:443",
	"id": "ep_2na2KihUjFYIhLR6demIzdJsxTH",
	"metadata": "{\"environment\": \"staging\"}",
	"proto": "https",
	"public_url": "https://endpoint-example2.com",
	"traffic_policy": "{\"on_http_request\":[{\"actions\":[{\"type\":\"deny\",\"config\":{\"status_code\":404}}]}]}",
	"type": "cloud",
	"updated_at": "2024-10-17T20:26:43Z",
	"uri": "https://api.ngrok.com/endpoints/ep_2na2KihUjFYIhLR6demIzdJsxTH",
	"url": "https://endpoint-example2.com"
}

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	Ref	The ID of the owner (bot or user) that owns this endpoint
principal_id	Ref	TODO: deprecate me!
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
uri	string	URI of the clep API resource
name	string	user supplied name for the endpoint

Ref fields

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

Delete Endpoint

Delete an Endpoint by ID, currently available only for cloud endpoints

Request

DELETE /endpoints/{id}

Example Request

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

Response

Returns a 204 response with no body on success