Skip to main content

REST API

Everything the NetEdge interface does goes through a REST API in JSON under /api/v1 — the web application itself is just another client of that API. If You can do this from the sidebar, or you can automate it by HTTP: Create nodes from a provisioning script, launch a deploy from your own pipeline, or export the inventory to another tool.

This page covers the core product API. If your license includes additional modules (P2P cascading recipes, post-cloning tasks, SNMP, RBAC…), these modules add their own endpoints — they will be documented here in future updates to this guide.

Conventions​

  • Base URL — the same address you use to access the interface (e.g., http://localhost:8080).
  • Prefix — All business endpoints are assigned the prefix /api/v1.
  • Format — JSON in the request and response bodies, except for uploads and image downloads (binary/multipart) and live streams (Server-Sent Events).
  • Status Codes — 200/201 success, 400 invalid payload, 401 Missing or expired token, 403 Insufficient role or functionality not included in your license, 404 resource does not exist, 409 conflict status (for example, a deployment already in progress), 429 request limit surpassed.

Authentication​

Most endpoints require a JWT Bearer token. Obtain it using your Your usual username and password:

TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"netedge"}' | jq -r .token)

And use it in every subsequent request:

curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/auth/me

The token expires after 24 hours. If your installation has the Auto-registration enabled (see Settings), also There are public endpoints that do not require a token for password recovery and registration of count: POST /api/v1/auth/forgot, POST /api/v1/auth/reset, and POST /api/v1/auth/register.

Live Status Without Polling (Server-Sent Events)​

Everything the interface displays "in real time" — the fleet status, the Deployment progress, log entry — travels via SSE: the The server pushes a new snapshot only when something changes, rather than the The client should check at regular intervals. Since the EventSource standard does not allow To send headers, you must first request a single-use ticket:

SSE_TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/events/stream-token \
  -H "Authorization: Bearer $TOKEN" | jq -r .token)

curl -N "http://localhost:8080/api/v1/nodes/status/stream?token=$SSE_TOKEN"

Available streams: GET /api/v1/events/stream (sidebar, version, license summary), GET /api/v1/nodes/status/stream (status of the fleet), GET /api/v1/deployments/progress/stream (deployment progress (in progress) and GET /api/v1/logs/stream (log console). Each has a equivalent GET normal without a stream as a fallback option.

Infrastructure​

See the complete user guide at Infrastructure.

  • GET/POST /api/v1/zones, GET/PUT/DELETE /api/v1/zones/:id
  • GET/POST /api/v1/subzones, GET/PUT/DELETE /api/v1/subzones/:id
  • GET/POST /api/v1/groups, GET/PUT/DELETE /api/v1/groups/:id
  • GET/POST /api/v1/nodes, GET/PUT/DELETE /api/v1/nodes/:id
  • GET /api/v1/nodes/status — snapshot of the status of the entire fleet
  • POST /api/v1/nodes/:id/wol, POST /api/v1/groups/:id/wol, POST /api/v1/zones/:id/wol — Wake-on-LAN immediately
  • GET/POST /api/v1/wol-schedules, GET/PUT/DELETE /api/v1/wol-schedules/:id — Wake-on-LAN scheduled (one-time or recurring, cron expression)
  • GET/PUT /api/v1/node-capture/:kind/:id — automatic capture of Unknown teams assigned to a zone/subzone/group
  • GET /api/v1/history/node/:id, GET /api/v1/history/group/:id, POST /api/v1/history/rollback — Deployment and Capture History

Each node supports an array of tags ("tags": ["aula-3"] in the creation/editing section). To sort by tag: resolves the nodes with GET /api/v1/nodes/tags (catalog of existing tags) and POST /api/v1/nodes/by-tags ({"tags":["aula-3"],"match_mode":"any"} or "all", returns {node_ids, nodes}), and passes those node_ids to the creation of the usual layout.

Example — creating a node:

curl -X POST http://localhost:8080/api/v1/nodes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"pc-aula-01","mac":"AA:BB:CC:DD:EE:FF","ip":"192.168.1.10","group_id":"<group-id>"}'

Images​

See the complete user guide at Images.

  • GET/POST /api/v1/images — list / upload (multipart)
  • GET/DELETE /api/v1/images/:id
  • POST /api/v1/images/bulk-delete
  • POST /api/v1/images/:id/download-token + GET /api/v1/images/:id/download?token=… — Download using a temporary token, without exposing your session
curl -X POST http://localhost:8080/api/v1/images \
  -H "Authorization: Bearer $TOKEN" \
  -F "name=Ubuntu 22.04 Aula 1" \
  -F "os=Ubuntu 22.04" \
  -F "file=@imagen.raw.zst"

Recipes​

See the complete user guide at Recipes.

  • GET/POST /api/v1/recipes, GET/PUT/DELETE /api/v1/recipes/:id
  • POST /api/v1/recipes/from-preset — create from a preset (low_ram, balanced, fast)
  • POST /api/v1/recipes/bulk-delete
curl -X POST http://localhost:8080/api/v1/recipes/from-preset \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Aula RAM baja","preset":"low_ram","uses_image":1}'

Deployments​

See the complete user guide at Deployments.

  • GET/POST /api/v1/deployments — list / create (by group or by a specific list of node_ids)
  • GET/DELETE /api/v1/deployments/:id, DELETE /api/v1/deployments/:id/purge
  • GET /api/v1/deployments/:id/cascade-plan — who is rebroadcasting whom
  • GET /api/v1/deployments/:id/metrics-history — speed/progress historical data for the charts
  • GET /api/v1/console/nodes, POST /api/v1/console/:node_id/token + GET /api/v1/console/:node_id/ws — Live remote console via WebSocket (The token above is a one-time, ephemeral ticket—not your JWT.)
curl -X POST http://localhost:8080/api/v1/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe_id": "<recipe-id>",
    "group_id": "<group-id>",
    "image_id": "<image-id>",
    "post_action": "reboot"
  }'

Network​

See the complete user guide at Network.

  • GET/POST /api/v1/boot/ifaces, GET/PUT/DELETE /api/v1/boot/ifaces/:id
  • PUT /api/v1/boot/ifaces/:id/dhcp, PUT /api/v1/boot/ifaces/:id/pxe
  • GET /api/v1/boot/ifaces/:id/conflicts — live scan of another DHCP server/PXE on the same subnet
  • GET /api/v1/boot/global + PUT /api/v1/boot/global/dhcp / .../pxe — the global template that each interface inherits from

Log​

See the complete user guide at Log.

  • GET /api/v1/logs/stream — the same live console you see on the interface, such as Server-Sent Events

Settings​

See the complete user guide under Settings.

  • GET/PUT /api/v1/settings/all, GET/PUT /api/v1/settings/image_dir, GET/PUT /api/v1/settings/timezone
  • GET/PUT /api/v1/mail/settings + POST /api/v1/mail/test — server outgoing email
  • GET/PUT /api/v1/signup/settings, GET /api/v1/signup/pending, POST /api/v1/signup/users/:id/approve / .../reject — self-registration
  • GET /api/v1/updates/status, POST /api/v1/updates/check, POST /api/v1/updates/apply — auto-update
  • GET /api/v1/config/backup (download a .netedge) and POST /api/v1/config/restore (multipart) — full backup
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/config/backup -o backup.netedge

License​

See the complete user guide under License and Support.

  • GET /api/v1/license/status
  • POST /api/v1/license/activate — body {"activation_key":"NE-XXXX-XXXX-XXXX"}
  • POST /api/v1/license/heartbeat — forces a check with the license server right now
  • GET/PUT /api/v1/license/server-url, GET/POST/DELETE /api/v1/license/server-urls

Users​

  • GET/POST /api/v1/users, PUT/DELETE /api/v1/users/:id — accounts and role (admin or superadmin)

The API That Customers Themselves Use PXE​

When a device boots from the network, netdd communicates with NetEdge via HTTP, without a token — it's the same API you would use, but designed so that the the power consumption of the machine being cloned:

  • POST /api/v1/tracker/register / .../heartbeat, GET /api/v1/tracker/peers — Peer registry and P2P swarm progress
  • POST /api/v1/metrics/, POST /api/v1/summary/ — periodic telemetry and deployment summary events

You don't need to call these endpoints yourself — we describe them here so that so you understand where the live charts come from Deployments if you ever monitor network traffic.