REST API

The dashboard is built on the server's JSON API, and you can call the same endpoints from scripts and automations. All paths are relative to your server, for example https://netignite.example.com/api/devices.

Basics

Authentication

The API uses the same session cookie as the dashboard. Log in with POST /api/auth/login and send the returned session cookie with every request. API keys aren't available yet.

# Log in and store the session cookie
curl -c cookies.txt -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"<password>"}' \
  https://netignite.example.com/api/auth/login

# Use the cookie
curl -b cookies.txt https://netignite.example.com/api/devices
curl -b cookies.txt -X POST https://netignite.example.com/api/devices/1/wakeup

Every endpoint except those under /api/auth/ requires a session. Without one, the server answers 401 with No session found or Invalid session. Sessions last 30 days and end when the server restarts.

Responses

Responses share one envelope:

{
    "status": "OK",
    "message": "Devices retrieved successfully.",
    "data": []
}

Errors use the matching HTTP status code: 400 for invalid input, 401 without a valid session, 404 for agents or devices that don't exist or belong to another user, 409 for conflicts, 503 when an agent is offline, and 500 for server errors. Updates answer 201.

Objects

{
    "id": 3,
    "name": "Office ESP32",
    "type": "microcontroller",
    "description": "Under the desk",
    "ownerID": 1
}

Agent objects never contain the secret. The server stores only a hash of it and returns the secret once, when you create an agent or regenerate its secret.

{
    "id": 1,
    "name": "Gaming PC",
    "type": "desktop",
    "description": null,
    "macAddress": "AA:BB:CC:DD:EE:FF",
    "port": 9,
    "agentID": 3,
    "ownerID": 1
}

id and ownerID are set by the server. Leave them out of request bodies.

Authentication

Log in

POST /api/auth/login

Sets the session cookie and answers 200 with Login successful. Wrong credentials return 401 with No matching credentials found.

Log out

POST /api/auth/logout

Ends the session and clears the cookie. Always answers 200.

Get the session

GET /api/auth/session

Returns the logged-in user, or 401 if there is no valid session.

{
    "status": "OK",
    "message": "Session valid",
    "data": {
        "userID": 1,
        "username": "admin",
        "role": "admin",
        "favorites": [],
        "expirationTimestamp": 1792351800000
    }
}

Account

Update an account

PUT /api/account/<userID>

Updates the username and password of the logged-in user.

Answers 201 with User Account updated successfully.

Admin mode. Admins can add ?adminMode=true to update the user given in the path instead of themselves. The first user (ID 1) can also change other users' role, and must send role when editing someone else.

Agents

List agents

GET /api/agents returns all of your agents as an array of agent objects.

Create an agent

POST /api/agents

Answers 201 with the new agent's ID and its generated secret. Store the secret now: it isn't returned again. The agent can connect right away.

{
    "status": "OK",
    "message": "Agent created successfully",
    "data": { "id": 3, "secret": "6f1c2e9a0b7d4c3e8a5f1b2c3d4e5f60" }
}

Get agent statuses

GET /api/agents/status?ids=1,2

Returns the connection status of your agents as a map from agent ID to "online", "offline" or "unknown". Without ids, all of your agents are included.

{ "status": "OK", "data": { "1": "online", "2": "offline" } }

Get an agent

GET /api/agents/<id> returns one agent object, or 404.

Update an agent

PUT /api/agents/<id> takes the same body as Create an agent and answers 201, or 404 if the agent doesn't exist. It changes only the name, type and description.

Regenerate an agent secret

POST /api/agents/<id>/regenerate-secret (no body)

Replaces the agent's secret and answers 200 with the new one, in the same shape as Create an agent. The old secret stops working immediately and a connected agent is disconnected. Returns 404 if the agent doesn't exist.

Delete an agent

DELETE /api/agents/<id> answers 200, or 404 if the agent doesn't exist. A connected agent is disconnected. Devices assigned to the agent are not deleted; reassign them first.

Devices

List devices

GET /api/devices returns all of your devices as an array of device objects. Add ?onlyFavorites=true to return only the devices in your favorites list.

Create a device

POST /api/devices

Answers 201; data is the new device's ID. Invalid fields return 400 with Invalid payload. An agentID that isn't one of your agents returns 400 with No matching agent found for the given AgentID.

Get device statuses

GET /api/devices/status?ids=1,2

Asks each device's agent whether the device is online and returns a map from device ID to "online", "offline" or "unknown". Without ids, all of your devices are checked. The devices are checked one after another, and each check can take up to 5 seconds, so filter with ids when you only need a few.

{ "status": "OK", "data": { "1": "online", "4": "unknown" } }

Get a device

GET /api/devices/<id> returns one device object, or 404.

Update a device

PUT /api/devices/<id> takes the same body as Create a device and answers 201, or 404 if the device doesn't exist.

Delete a device

DELETE /api/devices/<id> answers 200, or 404 if the device doesn't exist.

Wake a device

POST /api/devices/<id>/wakeup (no body)

Sends a Wake-on-LAN command through the device's agent.

Agent WebSocket

/api/agent-control-service is the WebSocket endpoint for agents, not a REST endpoint. See Agent Protocol.