Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Networks API

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

GET/networks

List the team's shared networks

Needs servers:read. Each network lives on one server and lists the services attached to it.

ParameterInTypeDescription
serverIdquerystring (uuid)Only the networks on this server
Response 200 · OK · application/json
ListNetworksOutputBody
  • NetworkView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/networks

Create a shared network

Needs servers:write. A shared network spans one server: services of any project of the team that run on it attach explicitly and are reachable by <service>.<env>.<project>. 409 network_name_taken, 422 server_not_found.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
Request body · application/json · required
CreateNetworkInputBody
  • namestringrequired
    Unique per team; letters, digits, spaces, '.', '_' and '-'
  • serverIdstringrequired
    The server the network lives on; only services on this server can attach
Response 201 · Created · application/json
NetworkView
  • createdAtstring (date-time)required
  • dockerNamestringrequired
  • idstringrequired
  • namestringrequired
  • serverIdstringrequired
  • serverNamestringrequired
  • AttachedService[] | nullrequired
    Services attached (staged or deployed); services of projects the token cannot see are left out
Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflictnetwork_name_taken
  • 422Unprocessable Entityserver_not_found
  • 500Internal Server Error

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

GET/networks/{networkId}

Get a shared network

ParameterInTypeDescription
networkIdrequiredpathstring
Response 200 · OK · application/json
NetworkView
  • createdAtstring (date-time)required
  • dockerNamestringrequired
  • idstringrequired
  • namestringrequired
  • serverIdstringrequired
  • serverNamestringrequired
  • AttachedService[] | nullrequired
    Services attached (staged or deployed); services of projects the token cannot see are left out
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

DELETE/networks/{networkId}

Delete a shared network

Needs servers:write. 409 network_in_use while a service is attached.

ParameterInTypeDescription
networkIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflictnetwork_in_use
  • 422Unprocessable Entity
  • 500Internal Server Error

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

PUT/services/{serviceId}/networks/{networkId}

Attach a service to a shared network (staged)

Needs deployments:write. Advances the service generation; the next deployment joins the network. 422 network_wrong_server when the service is on another server than the network, 422 egress_blocked while the service blocks outbound internet.

ParameterInTypeDescription
serviceIdrequiredpathstring
networkIdrequiredpathstring
Response 200 · OK · application/json
NetworkRef
  • aliasstringrequired
  • idstringrequired
  • namestringrequired
  • serverIdstringrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entitynetwork_wrong_serveregress_blocked
  • 500Internal Server Error

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

DELETE/services/{serviceId}/networks/{networkId}

Detach a service from a shared network (staged)

Needs deployments:write. Advances the service generation; the next deployment leaves the network.

ParameterInTypeDescription
serviceIdrequiredpathstring
networkIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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