Set up networks and sites

Networks and sites are the topology layer for Beam devices. A network is a logical segment; a site is a location where devices operate, and its routes decide which networks those devices can reach. The order matters: create the networks first, then create sites whose routes reference them, then register devices to the sites through the Fleets API.

Create a network

A network is created with PUT. Its spec is currently empty but must be present; the meaningful content is in metadata.

curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/infra/networks/production-network" \

-H "Authorization: Bearer <YOUR_TOKEN>" \

-H "Content-Type: application/json" \

-d '{

"metadata": {

"displayName": "Production Network",

"labels": { "environment": "production" }

},

"spec": {}

}'

Reading a network back shows its status.owner (User or System) and status.scope (Connecting between sites, or Local within one). System-owned and local networks are created by the platform.

Create a site with routes

Once the network exists, create a site whose routes reference it. A route requires only networkName. You can add an optional defaultTransport to set how content moves on that network.

curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/infra/sites/headquarters" \

-H "Authorization: Bearer <YOUR_TOKEN>" \

-H "Content-Type: application/json" \

-d '{

"metadata": {

"displayName": "Headquarters",

"labels": { "region": "europe", "type": "primary" }

},

"spec": {

"routes": [\
\
        {\
\
          "networkName": "production-network",\
\
          "defaultTransport": { "type": "SRTListener" }\
\
        }\
\
      ]

}

}'

defaultTransport.type is one of Auto, SRTListener, SRTCaller, UDP, or RISTListener. A device assigned to this site (through its siteName) automatically reaches the networks the site routes to.

Update and delete

PATCH updates labels, display name, or a site’s routes. A PATCH to routes replaces the whole array, so send the complete set.

curl -X PATCH "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/infra/sites/headquarters" \

-H "Authorization: Bearer <YOUR_TOKEN>" \

-H "Content-Type: application/json" \

-d '{ "metadata": { "displayName": "Main Headquarters" } }'

What goes wrong

• Creating a site before its network exists. A route references a network by name. Create the networks first.
• A delete returns 409 Conflict. A network cannot be deleted while a site routes to it, and a site cannot be deleted while devices or flows reference it. Clear those references first.
• Trying to delete a system-owned resource. System-owned networks and sites cannot be deleted, though they can be modified. Check status.owner before you try.

What comes next

• Manage devices: register Beam devices against the sites you created.