Endpoint Candidates Applications

Endpoint Candidates

GET /v1/applications/{uuid}/endpoint-candidates

Lists the endpoints in your account that this application could use instead of a new one. free holds the ones you can attach now. not_free holds the others, each with the reason it can't be attached yet. Endpoints that already serve this app aren't listed, and neither are per-device endpoints.

An endpoint is free when it is a tunnel endpoint with no agent connected, doesn't serve an app, isn't paused over your plan's limits or suspended, and has no dedicated IP, no dedicated TCP or UDP port and no routing rules. Attaching a free endpoint doesn't add to your endpoint count.

Requires the caller's account to have Endpoints read permission and the plan's application hosting. In the dashboard: the app's Domains tab, Add endpoint → Use an existing endpoint (see Use an endpoint you already have).

Path parameters

uuid string (uuid) Req

The application.

Response (200 OK)

Both lists are always present ([] when empty), newest endpoint first.

free array

The endpoints you can attach: uuid, hostname, created_at.

not_free array

The others, with the same fields plus reason (the first reason that applies), reasons (every reason that applies) and, for an endpoint that serves another app, application_uuid and application_name.

Reasons

serves_app

It serves another app, named in application_name. Detach it from that app first.

agent_online

An agent is connected to it. Stop the agent first.

suspended

The ngris team suspended it. Contact support.

paused

It, or its custom domain, is paused over your plan's limits. Make room on your plan or upgrade.

dedicated_ip

It uses a dedicated IP. Detach the IP first.

dedicated_port

It uses a dedicated TCP or UDP port. Release the port first.

routing_rules

It has routing rules. Remove them first.

Errors

403

Your role lacks Endpoints read, or the plan has no application hosting.

404

application not found: no such app in the active account (another account's reads the same).

Request
curl "https://api.ngris.com/v1/applications/019be838-d261-7d9b-9499-71995a3a91c6/endpoint-candidates" \
  -H "X-API-KEY: <your_api_key>"

Response — 200 OK
{
  "free": [
    {
      "uuid": "019c0a41-5b2e-7f3a-8c1d-4e6f7a8b9c0d",
      "hostname": "shop.example.com",
      "created_at": "2026-10-28T08:15:00Z"
    }
  ],
  "not_free": [
    {
      "uuid": "019c0b17-2a9d-7e44-b0c3-9d8e7f6a5b4c",
      "hostname": "api.example.com",
      "created_at": "2026-10-20T11:02:00Z",
      "reason": "agent_online",
      "reasons": ["agent_online", "routing_rules"]
    },
    {
      "uuid": "019c0c55-7e81-7a2f-9b6d-1c2d3e4f5a6b",
      "hostname": "blog.example.com",
      "created_at": "2026-09-30T16:40:00Z",
      "reason": "serves_app",
      "reasons": ["serves_app"],
      "application_uuid": "019bf3a0-11c2-7d5e-8f90-a1b2c3d4e5f6",
      "application_name": "blog"
    }
  ]
}

Was this helpful?

PreviousSet Primary Endpoint NextAttach an Endpoint

On this page

Endpoint Candidates

Was this helpful?