Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Routes API

5 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

POST/environments/{environmentId}/routes

Create a route service (staged until deployed)

A route service has no container: it publishes an external upstream (http), or exposes a tcp/udp port of a server (optionally for a managed service). Needs projects:write and proxy:write. The server is required. 422 codes: invalid_config, invalid_listen_port, upstream_denied (the server's upstream policy), invalid_upstream, agent_too_old. 409 port_in_use when another route holds the listen port, domain_conflict for a taken hostname.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
environmentIdrequiredpathstring
Request body · application/json · required
CreateRouteInputBody
  • allowCidrsstring[]
    tcp routes: client networks allowed; UDP cannot be restricted
  • denyCidrsstring[]
    tcp routes: client networks refused first, even when allowCidrs admits them; UDP cannot be restricted
  • DomainInput[] | null
    Hostnames of an http route (staged; refine each with PATCH /domains/{id})
  • healthPathstring
    Enables a proxy health check on this path
  • insecureSkipVerifyboolean
    https upstreams: do not verify the upstream certificate
  • listenPortinteger (int64)
    tcp/udp routes: host port on the server (1024-65535)
  • namestringrequired
  • openToInternetboolean
    tcp/udp routes: required when allowCidrs is empty
  • passHostboolean
    false rewrites the Host header to the upstream's (default true)
  • protocolenum: http | tcp | udprequired
  • proxyProtocolenum: 0 | 1 | 2
    tcp routes: PROXY protocol version sent to the upstream
  • schemeenum: http | https
    http routes: scheme used towards the upstream
  • serverIdstringrequired
    The server that publishes the route (required)
  • serverNamestring
    https upstreams: TLS server name
  • UpstreamInput[]
    1-20 upstreams
  • verifySkipboolean
    Skip the post-deploy HTTP verification (upstreams that legitimately answer 5xx)
Response 201 · Created · application/json
ServiceView
  • appliedGenerationinteger (int64)required
  • Configrequired
  • createdAtstring (date-time)required
  • currentDeploymentIdstringrequired
  • ReleaseRefrequired
  • desiredStateenum: running | stoppedrequired
  • DomainView[] | nullrequired
  • environmentIdstringrequired
  • generationinteger (int64)required
  • GitRefrequired
  • gitTokenSetbooleanrequired
  • hasStagedChangesbooleanrequired
  • idstringrequired
  • kindenum: app | worker | database | route | stackrequired
  • DeploymentRefrequired
  • MaintenanceViewrequired
  • namestringrequired
  • NetworkRef[] | nullrequired
  • ObservedViewrequired
  • observedAtstring (date-time) | nullrequired
  • PendingChangeCountsrequired
  • privateHoststringrequired
  • projectIdstringrequired
  • registryAuthSetbooleanrequired
  • ScalingViewrequired
  • ServerRefrequired
  • serverIdstringrequired
  • slugstringrequired
  • sourceTypeenum: image | git | external | composerequired
  • stagedKindstring | nullrequired
    new | edited | null
  • stalebooleanrequired
  • TailnetViewrequired
  • updatedAtstring (date-time)required
  • VolumeRef[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictport_in_use
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/routes/{routeId}

Get a route service

ParameterInTypeDescription
routeIdrequiredpathstring
Response 200 · OK · application/json
ServiceView
  • appliedGenerationinteger (int64)required
  • Configrequired
  • createdAtstring (date-time)required
  • currentDeploymentIdstringrequired
  • ReleaseRefrequired
  • desiredStateenum: running | stoppedrequired
  • DomainView[] | nullrequired
  • environmentIdstringrequired
  • generationinteger (int64)required
  • GitRefrequired
  • gitTokenSetbooleanrequired
  • hasStagedChangesbooleanrequired
  • idstringrequired
  • kindenum: app | worker | database | route | stackrequired
  • DeploymentRefrequired
  • MaintenanceViewrequired
  • namestringrequired
  • NetworkRef[] | nullrequired
  • ObservedViewrequired
  • observedAtstring (date-time) | nullrequired
  • PendingChangeCountsrequired
  • privateHoststringrequired
  • projectIdstringrequired
  • registryAuthSetbooleanrequired
  • ScalingViewrequired
  • ServerRefrequired
  • serverIdstringrequired
  • slugstringrequired
  • sourceTypeenum: image | git | external | composerequired
  • stagedKindstring | nullrequired
    new | edited | null
  • stalebooleanrequired
  • TailnetViewrequired
  • updatedAtstring (date-time)required
  • VolumeRef[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PATCH/routes/{routeId}

Update a route service (staged until deployed)

Requires If-Match: "<generation>". The protocol and server cannot be changed. Same 4xx codes as create; 412 generation_conflict for a stale generation.

ParameterInTypeDescription
routeIdrequiredpathstring
If-MatchheaderstringThe ETag (generation) from the last GET, e.g. "3". Required.
Request body · application/json · required
UpdateRouteInputBody
  • allowCidrsstring[]
    tcp routes: client networks allowed; UDP cannot be restricted
  • denyCidrsstring[]
    tcp routes: client networks refused first, even when allowCidrs admits them; UDP cannot be restricted
  • healthPathstring
    Enables a proxy health check on this path
  • insecureSkipVerifyboolean
    https upstreams: do not verify the upstream certificate
  • listenPortinteger (int64)
    tcp/udp routes: host port on the server (1024-65535)
  • namestring
  • openToInternetboolean
    tcp/udp routes: required when allowCidrs is empty
  • passHostboolean
    false rewrites the Host header to the upstream's (default true)
  • proxyProtocolenum: 0 | 1 | 2
    tcp routes: PROXY protocol version sent to the upstream
  • schemeenum: http | https
    http routes: scheme used towards the upstream
  • serverNamestring
    https upstreams: TLS server name
  • UpstreamInput[]
    1-20 upstreams
  • verifySkipboolean
    Skip the post-deploy HTTP verification (upstreams that legitimately answer 5xx)
Response 200 · OK · application/json
ServiceView
  • appliedGenerationinteger (int64)required
  • Configrequired
  • createdAtstring (date-time)required
  • currentDeploymentIdstringrequired
  • ReleaseRefrequired
  • desiredStateenum: running | stoppedrequired
  • DomainView[] | nullrequired
  • environmentIdstringrequired
  • generationinteger (int64)required
  • GitRefrequired
  • gitTokenSetbooleanrequired
  • hasStagedChangesbooleanrequired
  • idstringrequired
  • kindenum: app | worker | database | route | stackrequired
  • DeploymentRefrequired
  • MaintenanceViewrequired
  • namestringrequired
  • NetworkRef[] | nullrequired
  • ObservedViewrequired
  • observedAtstring (date-time) | nullrequired
  • PendingChangeCountsrequired
  • privateHoststringrequired
  • projectIdstringrequired
  • registryAuthSetbooleanrequired
  • ScalingViewrequired
  • ServerRefrequired
  • serverIdstringrequired
  • slugstringrequired
  • sourceTypeenum: image | git | external | composerequired
  • stagedKindstring | nullrequired
    new | edited | null
  • stalebooleanrequired
  • TailnetViewrequired
  • updatedAtstring (date-time)required
  • VolumeRef[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 412Precondition Failedgeneration_conflict
  • 422Unprocessable Entity
  • 428Precondition Required
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/routes/{routeId}

Delete a route service

Frees the listen port and removes the route from its server's table (a sync is queued atomically). DELETE /services/{id} does the same.

ParameterInTypeDescription
routeIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/servers/{serverId}/ports

List the tcp/udp ports route services hold on a server

Includes staged (not yet deployed) routes. Holder names of projects the caller cannot see are omitted.

ParameterInTypeDescription
serverIdrequiredpathstring
Response 200 · OK · application/json
PortsOutputBody
  • PortView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.