# Networks API

6 operations under /api/v1. Errors are RFC 9457 problem+json with a stable `code` field. The complete schemas are in https://nebulactrl.com/api/v1/openapi.json.

## GET /networks

List the team's shared networks

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

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `serverId` (query, string (uuid)): Only the networks on this server

Response 200: OK (ListNetworksOutputBody)
  - `items` (NetworkView[] | null, required)
Errors: 401 Unauthorized; 403 Forbidden; 422 Unprocessable Entity; 500 Internal Server Error

## 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`.

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `Idempotency-Key` (header, string): Client-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.

Request body (application/json, required): CreateNetworkInputBody
  - `name` (string, required): Unique per team; letters, digits, spaces, '.', '_' and '-'
  - `serverId` (string, required): The server the network lives on; only services on this server can attach

Response 201: Created (NetworkView)
  - `createdAt` (string (date-time), required)
  - `dockerName` (string, required)
  - `id` (string, required)
  - `name` (string, required)
  - `serverId` (string, required)
  - `serverName` (string, required)
  - `services` (AttachedService[] | null, required): Services attached (staged or deployed); services of projects the token cannot see are left out
Errors: 401 Unauthorized; 403 Forbidden; 409 Conflict (`network_name_taken`); 422 Unprocessable Entity (`server_not_found`); 500 Internal Server Error

## GET /networks/{networkId}

Get a shared network

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `networkId` (path, string, required)

Response 200: OK (NetworkView)
  - `createdAt` (string (date-time), required)
  - `dockerName` (string, required)
  - `id` (string, required)
  - `name` (string, required)
  - `serverId` (string, required)
  - `serverName` (string, required)
  - `services` (AttachedService[] | null, required): Services attached (staged or deployed); services of projects the token cannot see are left out
Errors: 401 Unauthorized; 403 Forbidden; 422 Unprocessable Entity; 500 Internal Server Error

## DELETE /networks/{networkId}

Delete a shared network

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

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `networkId` (path, string, required)

Response 204: No Content
Errors: 401 Unauthorized; 403 Forbidden; 409 Conflict (`network_in_use`); 422 Unprocessable Entity; 500 Internal Server Error

## 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.

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `serviceId` (path, string, required)
- `networkId` (path, string, required)

Response 200: OK (NetworkRef)
  - `alias` (string, required)
  - `id` (string, required)
  - `name` (string, required)
  - `serverId` (string, required)
Errors: 401 Unauthorized; 403 Forbidden; 422 Unprocessable Entity (`network_wrong_server`, `egress_blocked`); 500 Internal Server Error

## 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.

Authentication: session cookie or `Authorization: Bearer nct_…` token.

Parameters:
- `serviceId` (path, string, required)
- `networkId` (path, string, required)

Response 204: No Content
Errors: 401 Unauthorized; 403 Forbidden; 422 Unprocessable Entity; 500 Internal Server Error