Create Endpoints

Create Endpoint

POST /v1/endpoints

Provision a new endpoint — the routing entry that connects a public URL to an agent. The endpoint persists across agent reconnects; tunnels are the live connections that come and go on top of it.

Endpoints are protocol-agnostic — one endpoint serves HTTP, TCP, UDP and QUIC at once. The protocol is chosen per tunnel by the agent (ngris http|tcp|udp), not at endpoint create, so there is no protocol field. Endpoints are also region-less — region is a property of the serving tunnel/agent (GeoDNS steers public traffic to the nearest region), so there is no region field; the plan's allowed_regions entitlement is enforced when a tunnel connects, not at create. Before creating, the server checks that the user has remaining endpoint quota on their plan and (for custom subdomains and root @ endpoints) that the user owns the target domain. Per-protocol plan entitlements are enforced when a tunnel of that protocol connects.

Request body

subdomain string

Optional. Only honoured when is_custom: true and you own the target domain — otherwise the platform auto-generates a memorable word-word-word identifier. Pass "@" to claim the root of the domain (admin or strict domain owner only).

is_custom boolean

Set to true to use the supplied subdomain. Requires the custom-subdomains entitlement on your plan and ownership of the target domain. Silently downgraded to false if either prerequisite isn't met.

domain_id int64

ID of a domain registered to your account (/domains). Omit to use the plan's configured default system domain (e.g. ngris.io).

Response (201 Created)

id int64

Internal numeric ID. Prefer the uuid for API references.

uuid string

Stable identifier used in every other endpoint URL (/endpoints/{uuid}).

subdomain string

Final subdomain (auto-generated if you didn't pass one).

hostname string

The endpoint's public FQDN (e.g. myapp.example.com). Share this with the agent and clients.

public_url string

Same value as hostname — the bare FQDN with no scheme, because the endpoint may serve HTTP/TCP/UDP/QUIC. For HTTP/unified endpoints, build a browser URL as https://<public_url>.

protocol string

Always unified — endpoints are protocol-agnostic.

is_custom boolean

Whether the final subdomain is user-chosen. May be false even if you requested true (entitlement or ownership check failed).

domain_id int64 | null

Domain the endpoint is anchored to, or null for the platform default.

status string

active | provisioning | error. New endpoints come up active immediately for HTTP; some protocols (TCP/UDP with dedicated ports) start provisioning.

mtls_mode string

mTLS state (disabled, optional, required). Always disabled at creation; configure via PUT /v1/endpoints/{id}/mtls.

created_at datetime

RFC 3339 UTC timestamp.

Errors

400 Bad Request

Invalid JSON, unknown fields (strict decoding; stale protocol/region fields are accepted-but-ignored), or invalid subdomain format.

401 Unauthorized

Missing or invalid API key.

403 Forbidden

Endpoint quota reached, root @ endpoint without strict ownership, or organization endpoint limit hit. (Per-protocol and per-region plan entitlements are enforced when a tunnel connects, not at endpoint create.)

404 Not Found

domain_id doesn't exist or the user can't use it.

500

Database / plan-lookup error. The transaction is rolled back; safe to retry.

Request
curl -X POST "https://api.ngris.com/v1/endpoints" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "myapp",
    "is_custom": true,
    "domain_id": 42
  }'

Python
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
ep = client.endpoints.create({
    "subdomain": "myapp",
    "is_custom": True,
    "domain_id": 42,
})
print(ep.hostname)  # myapp.example.com  (public_url is the same bare FQDN, no scheme)

Response — 201 Created
{
  "id": 184,
  "uuid": "9f1a3c00-5b7f-4f12-8c46-2c7dab5f1234",
  "subdomain": "myapp",
  "hostname": "myapp.example.com",
  "public_url": "myapp.example.com",
  "protocol": "unified",
  "is_custom": true,
  "domain_id": 42,
  "status": "active",
  "mtls_mode": "disabled",
  "ephemeral": false,
  "created_at": "2026-04-29T12:34:56Z",
  "updated_at": "2026-04-29T12:34:56Z"
}

PreviousGet Endpoint NextDelete Endpoint

On this page

Create Endpoint