Networks API

All endpoints require a bearer token (a login JWT or an API key) and a permission, listed with each endpoint.

A network is a private, region-scoped network that lets your pods talk to each other on private IPs. Pods attach to a network from the pod side (at pod creation, or via networkId on update a pod), not from here. A pod created without a networkId reuses your oldest network in that Region, or gets a new one if you have none there - either way it shows up in this list.

The network object

{
  "id": "6a4d5b83b7006ccae6391a22",
  "name": "app-net",
  "cidr": "10.20.0.0/24",
  "gateway": "10.20.0.1",
  "description": "Production network",
  "accountId": "6a4d5b83b7006ccae639100a",
  "serverId": "6a4d5b83b7006ccae639170f",
  "status": "Active",
  "health": "Healthy",
  "healthCheckedAt": "2026-09-16T14:30:00Z",
  "createdAt": "2026-09-01T12:00:00Z",
  "updatedAt": "2026-09-01T12:00:30Z"
}

Field	Meaning
cidr	The private address range, normalised to its base address.
gateway	First usable address in the range (assigned automatically).
serverId	The Region the network lives in. Fixed at creation.
status	The one-time provisioning outcome: Provisioning, Active, or Failed.
health	The live reachability of the network's uplink: Healthy, Unhealthy, or absent if it has not been checked yet. healthDetail carries the reason when it is unhealthy, and healthCheckedAt when it was last looked at.
error	Present only when status is Failed.

status tells you whether the network was built; health tells you whether it is working right now. History for the second one is on GET /api/uptime/networks/:id.

List networks

GET /api/networks?page=1&limit=20&search=app

Needs networks:read. Paginated, newest first; search matches name, cidr, and description.

curl https://cloud-api.microapps.io/api/networks \
  -H "Authorization: Bearer $MICROAPPS_API_KEY"

Create a network

POST /api/networks

Needs networks:create, $3 of credit, and a free slot under your network limit.

curl -X POST https://cloud-api.microapps.io/api/networks \
  -H "Authorization: Bearer $MICROAPPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "app-net",
    "cidr": "10.20.0.0/24",
    "description": "Production network",
    "serverId": "6a4d5b83b7006ccae639170f"
  }'

Field	Type	Notes
cidr	string	Required. Must be a private IPv4 range, with a prefix from the block's own size down to /30: 10.0.0.0/8 allows /8-/30, 172.16.0.0/12 allows /12-/30, 192.168.0.0/16 allows /16-/30. Anything else is 400 "Invalid private network: ...".
serverId	string	Required. The Region. Get valid ids from /open/config-options. A server that cannot host networks is 400 "Networks can only be created on compute nodes".
name	string	Optional. 2 to 30 characters (letters, numbers, spaces, hyphens). Left blank, we generate one. Must be unique within your account, or 409 "Network name ... is already taken".
description	string	Optional. Trimmed and capped at 1024 characters.

Response 201:

{
  "id": "6a4d5b83b7006ccae6391a22",
  "name": "app-net",
  "cidr": "10.20.0.0/24",
  "gateway": "10.20.0.1",
  "description": "Production network",
  "accountId": "6a4d5b83b7006ccae639100a",
  "serverId": "6a4d5b83b7006ccae639170f",
  "status": "Provisioning",
  "createdAt": "2026-09-16T09:00:00Z",
  "updatedAt": null
}

Creating a network is asynchronous: it comes back Provisioning and flips to Active once it is ready. Pods can only attach to an Active network - attaching one that is still building is 400 "Network app-net is not ready (status: Provisioning)". Networks are free, but the create call still needs at least $3 of account credit like any other create (402 otherwise).

Describe a network

GET /api/networks/:id

Needs networks:read. Returns the network object.

Pods on a network

GET /api/networks/:id/resources

Needs networks:read. Plain array of the pods attached to the network:

curl https://cloud-api.microapps.io/api/networks/6a4d5b83b7006ccae6391a22/resources \
  -H "Authorization: Bearer $MICROAPPS_API_KEY"

[
  {
    "id": "6a4d5b83b7006ccae6391810",
    "name": "my-app",
    "status": "Running",
    "os": "ubuntu",
    "version": "24.04",
    "privateIp": "10.20.0.5"
  }
]

Network traffic

GET /api/networks/:id/traffic

Needs networks:read.

{ "totalIn": 44210000, "totalOut": 981200000, "podCount": 2 }

Totals are summed from the latest telemetry sample of each attached pod, so the byte counters are cumulative since each pod last started. podCount counts only the pods that had a sample to contribute - a stopped or brand-new pod is skipped, so it can be lower than the number of pods in /resources.

Update a network

PUT /api/networks/:id

Needs networks:update.

curl -X PUT https://cloud-api.microapps.io/api/networks/6a4d5b83b7006ccae6391a22 \
  -H "Authorization: Bearer $MICROAPPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "app-net-prod", "description": "Production network (updated)" }'

Only name and description can change, and name has to stay unique on your account (409 otherwise). The CIDR and Region are fixed once the network exists - to change either, create a new network and move the pods.

Delete a network

DELETE /api/networks/:id

Needs networks:delete. Returns 204. If any pod is still attached it returns 409 "Network is still in use by N pods" - move those pods to another network first, with networkId on update a pod.