Promote Endpoints

Promote Ephemeral Endpoint

POST /v1/endpoints/{id}/promote

Convert an ephemeral endpoint into a permanent one. Ephemeral endpoints are auto-created by ngris.connect(), the agent's ngris http <port> command, and similar one-shot flows; they're tracked by a janitor that reaps them when the agent has been disconnected for a configurable idle window.

Promotion clears the ephemeral flag, the device fingerprint, and the last_active_at tracking, so the row becomes indistinguishable from one created via POST /v1/endpoints. The endpoint now counts against the user's permanent endpoint quota — if you're already at the limit, promotion fails with 403 and you must delete a permanent endpoint first.

The whole operation is wrapped in a transaction with a SELECT ... FOR UPDATE on both the user and endpoint rows, so concurrent create + promote calls can't both push you over the quota.

Path parameters

id string (uuid) Req

Endpoint UUID. Must be ephemeral and owned by the calling user.

Request body

None. Empty {} or no body. The promotion is unconditional — there's nothing to configure.

Response (200 OK)

Returns a minimal confirmation — endpoint_id, uuid, and ephemeral: false. To read the full endpoint after promotion, call GET /v1/endpoints/{id}.

endpoint_id int64

Numeric ID of the promoted endpoint.

uuid string

Endpoint UUID (echo of the path parameter).

ephemeral boolean

Always false after a successful promotion.

Errors

400 Bad Request

Missing or empty UUID in the path.

401 Unauthorized

Missing auth.

403 Forbidden

Permanent endpoint quota reached. Delete a permanent endpoint or upgrade plan, then retry.

404 Not Found

UUID doesn't exist or belongs to another user.

409 Conflict

Endpoint is already permanent. Promotion is a no-op in this case but the server returns 409 to make accidental double-clicks visible.

Request
curl -X POST "https://api.ngris.com/v1/endpoints/9f1a3c00.../promote" \
  -H "X-API-KEY: <your_api_key>"

Python
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
ep = client.endpoints.promote("<endpoint_uuid>")
print(ep.uuid, ep.ephemeral)  # ephemeral=False after promote

Response — 200 OK
{
  "endpoint_id": 184,
  "uuid": "9f1a3c00-5b7f-4f12-8c46-2c7dab5f1234",
  "ephemeral": false
}

Error — quota reached
permanent endpoint limit reached (20). Delete an existing endpoint or upgrade to promote this one.

PreviousDelete Endpoint NextEndpoint Health

On this page

Promote Ephemeral Endpoint