Get Endpoint
Fetch a single endpoint by its UUID: identifiers, public URL, what it serves, protocol, status, mTLS mode, capture switch, ephemeral flag, pause markers and timestamps.
Visibility rules: you see the endpoints of your active account — another account's uuid returns 404, the same status as an unknown uuid, so it reveals nothing. Admins can fetch any endpoint.
Path parameters
uuid string (uuid) Req
The endpoint's
uuid — from a list response or the create response.Response (200 OK)
uuid string (uuid)
The endpoint's public id. Used in every other endpoint URL.
user_uuid string (uuid)?
The user who created the endpoint. Omitted when the endpoint has no creating user (endpoints belong to the account; one born from an agent session or moved between accounts has none).
domain_uuid string (uuid)?
The
uuid of the domain anchoring this endpoint. Omitted when the endpoint has no domain row.subdomain string
Subdomain part of the public URL.
"@" means the root of the domain.hostname string
The endpoint's public FQDN (e.g.
myapp.ngris.io). Built from subdomain + the linked domain's name (or the platform default when there is no domain_uuid); "@" resolves to the bare domain. Prefer this field when referring to the endpoint.public_url string
Same value as
hostname — the bare FQDN with no scheme. A single endpoint can serve HTTP, TCP, UDP and QUIC at once, so the platform does not prefix https://. For HTTP/unified endpoints, build a browser URL as https://<public_url>.serving_mode string
What answers on this hostname:
agent (a tunnel to your agent — the default), agentless (the linked application's static deploy, served by the platform) or managed (the linked application's backend running on the platform).application_uuid string (uuid)?
The application this endpoint serves. Omitted for
agent endpoints.protocol string
Always
unified for endpoints created now — endpoints are protocol-agnostic (one hostname serves HTTP/TCP/UDP/QUIC; the protocol is chosen per tunnel). Legacy rows may still show http/tcp/udp. Read-only; not accepted on create.is_custom boolean
Whether the subdomain was user-chosen vs auto-generated.
status string
The stored status:
active (an agent is serving it) | inactive | pending_dns (the DNS record on your domain is still being created) | dns_failed (DNS provisioning failed; see dns_last_error). GET /v1/endpoints reports the live state instead.mtls_mode string
capture_enabled boolean
Whether requests to this endpoint are recorded in the traffic logs.
true by default; when false the edge still serves the endpoint but writes no log rows for it.capture_level string?
full | metadata | off — an advisory, finer-grained capture hint; capture_enabled is what decides. Omitted when unset.ephemeral boolean
true for auto-created endpoints (e.g. via ngris.connect()) that the janitor will reap when idle. Promote to make it permanent.last_active_at datetime?
Last time an agent connected. Only tracked for ephemerals; omitted when unset.
dedicated_tcp_port, dedicated_udp_port int?
Assigned dedicated ports. Omitted when the endpoint has none. Configure via PUT /v1/endpoints/{uuid}/ports.
dedicated_ip_assignment_uuid, dedicated_ip_group_uuid string (uuid)?
The dedicated IP (or per-region dedicated IP group) the endpoint is attached to. Attaching one clears the other; both omitted = the shared IP.
dns_attempts int
How many times the platform has tried to create the endpoint's DNS record on your domain.
0 when the domain needs no per-endpoint record.dns_last_error, dns_updated_at string?, datetime?
The last DNS provisioning error and when DNS provisioning last ran. Omitted when unset.
quota_paused_at datetime?
Set while the endpoint is paused because the account is over its plan's endpoint limit: it is not served, but nothing is deleted, and it resumes on its own once the account has room. Omitted when not paused.
domain_quota_paused, dedicated_tcp_paused, dedicated_udp_paused boolean?
Present and
true only while the endpoint's custom domain, or that dedicated port, is paused over the plan's limit (the port number stays assigned).admin_suspended boolean
Present and
true only when the ngris team has suspended this endpoint, usually after an abuse report. It is not served: visitors get 503 and agents can't register it. It stays until the team lifts it, so contact support. You can still delete it, like any endpoint. This is different from an over-quota pause, which resumes on its own once the account has room.created_at, updated_at datetime
RFC 3339 UTC timestamps.
The list adds per-endpoint summaries this response doesn't carry (traffic in the last 24 hours, auth and traffic-rule flags, certificate and tunnel details) — see GET /v1/endpoints.
Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.
Errors
401 Unauthorized
Missing auth.
404 Not Found
No such endpoint in your active account — an unknown uuid, another account's uuid and anything that isn't a uuid all read the same.
Request
curl "https://api.ngris.com/v1/endpoints/019bb1e4-e785-77d2-9966-c3cff31d0a0e" \
-H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
ep = client.endpoints.get("<endpoint_uuid>")
print(ep.public_url, ep.status, ep.protocol)
Response — 200 OK
{
"uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e",
"user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134",
"domain_uuid": "019bd08f-98db-71b2-8e54-f518d319f111",
"subdomain": "myapp",
"hostname": "myapp.ngris.io",
"public_url": "myapp.ngris.io",
"serving_mode": "agent",
"protocol": "unified",
"is_custom": false,
"status": "active",
"mtls_mode": "disabled",
"capture_enabled": true,
"ephemeral": false,
"dns_attempts": 0,
"created_at": "2026-04-29T12:34:56Z",
"updated_at": "2026-04-29T12:34:56Z"
}
Was this helpful?