API Endpoints#

WatchGrid provides a REST API to manage agents, configure monitoring parameters, and set up notification channels.

General Information#

Base URL#

All API endpoints share the following base URL:

https://watchgrid.de/api

Authentication#

All requests require Bearer Token authentication. Retrieve your organization token from the Dashboard under Organization, and pass it in the HTTP header:

Authorization: Bearer <YOUR_API_TOKEN>
Accept: application/json

Agent Endpoints (/agent/)#

Endpoints used to register, configure, and query monitoring agents.

1. List All Agents#

Returns baseline information for all agents registered in your organization.

  • Method: GET

  • Path: /agent/all

  • Response: Array of agent objects (including hostname, UUID, version, OS, last activity, and alert status).

2. Register Agent#

Registers a new agent system.

  • Method: POST

  • Path: /agent/

  • Response: Success response containing the generated agent UUID.

3. Delete Agent#

Permanently removes an agent and its historical monitoring data.

  • Method: DELETE

  • Path: /agent/

  • Query Parameter: agent_id (agent UUID)

  • Response: Success or error payload.

4. Fetch Agent Details#

Retrieves details for a specific agent.

  • Method: GET

  • Path: /agent/info

  • Query Parameter: agent_id (agent UUID)

  • Response: Detailed agent object.

5. Update System Information (Agent)#

Used by the agent on startup/registration to report host hardware and operating system details.

  • Method: POST

  • Path: /agent/info

  • Body: JSON object containing hostname, OS type, OS version, architecture, uptime, and hardware capacity details (cpu_cores, ram_total_gb, disk_total_gb).

6. Submit Metric Snapshot (Agent)#

Used by agents or scripts to send periodic resource utilization data.

  • Method: POST

  • Path: /agent/metrics

  • Body: JSON object containing CPU utilization (%), RAM utilization (%), Disk utilization (%), hardware capacity specs (cpu_cores, ram_total_gb, disk_total_gb), open port check results, and monitored systemd service statuses.

7. Fetch Agent Configuration#

Retrieves active configuration for an agent. If no custom agent config exists, global organization config is returned.

  • Method: GET

  • Path: /agent/config

  • Query Parameter: agent_id (agent UUID)

  • Response: CPU/RAM/Disk warning & alert thresholds, metric intervals, port & service whitelists, update requirements.

8. Create/Update Custom Agent Configuration#

Creates or modifies custom configuration settings for an individual agent.

  • Methods: POST (create) / PUT (update)

  • Path: /agent/config

  • Body: JSON object specifying reporting interval (seconds), alert & warning thresholds, port whitelist, systemd services, and max allowed uptime limits.

9. Delete Custom Agent Configuration#

Removes agent-specific overrides, reverting the agent back to global organization configuration.

  • Method: DELETE

  • Path: /agent/config

  • Query Parameter: agent_id (agent UUID)

10. Update Agent Metadata#

Modifies agent hostname, notes/comments, or controls maintenance mode.

  • Method: PATCH

  • Path: /agent/

  • Query Parameter: agent_id (agent UUID)

  • Body: JSON payload with optional fields:

    • hostname (String)

    • comment (String)

    • maintenance_active (Boolean)

    • maintenance_minutes (Integer, optional auto-expiry)

    • maintenance_start / maintenance_end (ISO Timestamps)

11. Fetch / Update Global Organization Configuration#

  • Methods: GET (retrieve) / PUT (update)

  • Path: /agent/global-config

  • Response/Body: Global default CPU/RAM/Disk thresholds and baseline reporting intervals for all agents in the organization.

Notification Endpoints (/notification/)#

Endpoints used to configure and test alert notification channels.

1. List All Notification Channels#

Returns all configured alert channels for the organization.

  • Method: GET

  • Path: /notification/all

2. Create Channel#

Creates a new notification channel.

  • Method: POST

  • Path: /notification/

  • Body: JSON object:

    • channel_type (e.g., discord, gotify, ntfy, slack, webhook, email, sms)

    • destinations (Array of target URLs, email addresses, or phone numbers)

    • is_active (Boolean)

3. Update Channel#

Modifies settings of an existing notification channel.

  • Method: PUT

  • Path: /notification/

  • Query Parameter: channel_id (channel UUID)

  • Body: JSON payload matching channel creation.

4. Delete Channel#

Permanently deletes a notification channel.

  • Method: DELETE

  • Path: /notification/

  • Query Parameter: channel_id (channel UUID)

5. Fetch Channel Details#

Retrieves details for a specific notification channel.

  • Method: GET

  • Path: /notification/info

  • Query Parameter: channel_id (channel UUID)

6. Test Channel#

Triggers a test alert notification on the selected channel.

  • Method: GET

  • Path: /notification/test

  • Query Parameter: channel_id (channel UUID)