API Reference

Complete reference for the LILLYDOO Pulse REST API. All endpoints accept and return JSON. Base URL: http://your-server:5000

Authentication

LILLYDOO Pulse uses Bearer token authentication. Include your API token in the Authorization header of every request to protected endpoints.

Example Request

curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://your-server:5000/api/dashboard/stats

Token Types

Type	Scope	Description
admin	Admin	Full access. Can manage tokens, agents, pollers, and all resources.
agent	Agent	Used by monitoring agents to register, send heartbeats, report metrics and check results.
poller	Poller	Used by distributed pollers to fetch tasks and submit check results.

Tip: Create tokens via the Token Management API or the admin dashboard. Tokens are shown only once at creation time -- store them securely.

Note: Monitor CRUD endpoints (ping, ssl, http, port), dashboard, categories, and maintenance endpoints are currently open (no auth required). Token-protected endpoints are marked with an auth badge.

Multi-Source Monitoring

Ping, SSL, HTTP, and Port monitors can be checked from multiple sources simultaneously. A source is either public (the Pulse server itself, running on the public Upsun instance) or poller (a registered Network Poller running inside a private network). The public source is always available; poller sources are added by referencing an active, registered poller's poller_id.

Each source executes its own check on the monitor's configured interval and produces its own check result. The dashboard aggregates results across sources: all sources up yields up, any source down yields down, and a mix yields warning. This lets you verify reachability of internal hosts from multiple network locations at once (for example: unreachable from Public but reachable from two different office pollers).

Multi-source is supported on /api/ping/, /api/ssl/, /api/http/, and /api/port/ monitors — all four monitor types.

Example: create a ping monitor checked from Public + one poller

POST /api/ping/
{
  "name": "intern.lillydoo.local",
  "target": "10.0.0.5",
  "interval_seconds": 300,
  "sources": [
    { "type": "public" },
    { "type": "poller", "poller_id": 3 }
  ],
  "category_ids": [4, 8]
}

Note: If sources is omitted or empty on create/update, the default [{"type":"public"}] is applied. All monitor types (Ping, SSL, HTTP, Port) support multi-source.

Error Handling

All errors return a JSON body with an error field describing what went wrong.

Error Response

{
  "error": "Ping monitor not found"
}

Status Code	Meaning
400	Bad Request -- missing or invalid parameters
401	Unauthorized -- missing or invalid token
403	Forbidden -- token does not have required permissions
404	Not Found -- resource does not exist
409	Conflict -- resource already exists (e.g. duplicate category name)

Ping Monitors

Create and manage ICMP ping monitors that check host availability and response time.

GET /api/ping/ List all ping monitors

No auth required

Returns all ping monitors with their latest check status, categories, and 24h uptime.

Response 200 OK

[
  {
    "id": 1,
    "name": "Google DNS",
    "type": "ping",
    "target": "8.8.8.8",
    "interval_seconds": 300,
    "active": 1,
    "latest_status": "up",
    "latest_response_time_ms": 12.5,
    "latest_checked_at": "2026-04-02T10:30:00",
    "uptime_24h": 99.8,
    "sources": [
      { "type": "public", "poller_id": null, "poller_name": null },
      { "type": "poller", "poller_id": 3, "poller_name": "FFM Poller" }
    ],
    "categories": [
      { "id": 1, "name": "Production", "color": "#00d68f" }
    ],
    "created_at": "2026-03-15T08:00:00",
    "updated_at": "2026-03-15T08:00:00"
  }
]

POST /api/ping/ Create a ping monitor

No auth required

Create a new ping monitor. The monitor will begin checking on its configured interval.

Request Body

Field	Type	Description
name REQUIRED	string	Display name for the monitor
target REQUIRED	string	Hostname or IP address to ping
interval_seconds optional	integer	Check interval in seconds (default: 300)
sources optional	array	Sources that check this monitor. Each item is `{"type":"public"}` or `{"type":"poller","poller_id":N}`. Defaults to `[{"type":"public"}]`.
category_ids optional	array	Array of category IDs to assign

Request

{
  "name": "intern.lillydoo.local",
  "target": "10.0.0.5",
  "interval_seconds": 60,
  "sources": [
    { "type": "public" },
    { "type": "poller", "poller_id": 3 }
  ],
  "category_ids": [1, 3]
}

Response 201 Created

{
  "id": 5,
  "name": "Google DNS",
  "type": "ping",
  "target": "8.8.8.8",
  "interval_seconds": 60,
  "active": 1,
  "categories": [
    { "id": 1, "name": "Production", "color": "#00d68f" }
  ],
  "created_at": "2026-04-02T12:00:00",
  "updated_at": "2026-04-02T12:00:00"
}

GET /api/ping/{id} Get ping monitor details

No auth required

Returns full monitor details including the last 50 check results, uptime stats, and categories.

Response 200 OK

{
  "id": 1,
  "name": "Google DNS",
  "type": "ping",
  "target": "8.8.8.8",
  "interval_seconds": 300,
  "active": 1,
  "sources": [
    { "type": "public", "poller_id": null, "poller_name": null },
    { "type": "poller", "poller_id": 3, "poller_name": "FFM Poller" }
  ],
  "categories": [],
  "uptime_stats": {
    "uptime_1h": 100.0,
    "uptime_24h": 99.8,
    "uptime_7d": 99.95,
    "uptime_30d": 99.92
  },
  "results": [
    {
      "id": 100,
      "monitor_id": 1,
      "status": "up",
      "response_time_ms": 12.5,
      "details": { "packets_sent": 4, "packets_received": 4 },
      "checked_at": "2026-04-02T10:30:00"
    }
  ]
}

PUT /api/ping/{id} Update a ping monitor

No auth required

Update any field on an existing ping monitor. Only include the fields you want to change.

Request Body

Field	Type	Description
name optional	string	Display name
target optional	string	Hostname or IP address
interval_seconds optional	integer	Check interval in seconds
active optional	boolean	Enable/disable the monitor
sources optional	array	Replace the set of sources. Same shape as on create.
category_ids optional	array	Replace assigned category IDs

Request

{
  "name": "Google DNS (Primary)",
  "interval_seconds": 120,
  "active": true,
  "sources": [
    { "type": "public" },
    { "type": "poller", "poller_id": 3 }
  ]
}

Note: If sources is omitted on create/update, it defaults to [{"type":"public"}].

Response 200 OK

{
  "id": 1,
  "name": "Google DNS (Primary)",
  "type": "ping",
  "target": "8.8.8.8",
  "interval_seconds": 120,
  "active": 1,
  "categories": []
}

DELETE /api/ping/{id} Delete a ping monitor

No auth required

Permanently delete a ping monitor and all its check results.

Response 200 OK

{
  "message": "Monitor deleted"
}

POST /api/ping/{id}/check Trigger immediate check

No auth required

Trigger an immediate ping check. The result is stored and returned. No request body needed.

Response 201 Created

{
  "id": 150,
  "monitor_id": 1,
  "status": "up",
  "response_time_ms": 11.3,
  "details": {
    "packets_sent": 4,
    "packets_received": 4,
    "avg_rtt": 11.3
  },
  "checked_at": "2026-04-02T12:05:00"
}

SSL Monitors

Monitor SSL/TLS certificates for expiration, validity, and configuration issues.

GET /api/ssl/ List all SSL monitors

No auth required

Returns all SSL monitors with latest status, days remaining, categories, and 24h uptime.

Response 200 OK

[
  {
    "id": 2,
    "name": "Main Website",
    "type": "ssl",
    "target": "example.com",
    "last_status": "up",
    "last_response_time_ms": 245,
    "last_details": {
      "days_remaining": 87,
      "issuer": "Let's Encrypt",
      "expires": "2026-06-28T00:00:00"
    },
    "uptime_24h": 100.0,
    "sources": [
      { "type": "public" },
      { "type": "poller", "poller_id": 3 }
    ],
    "categories": []
  }
]

POST /api/ssl/ Create an SSL monitor

No auth required

Request Body

Field	Type	Description
name REQUIRED	string	Display name
target REQUIRED	string	Domain name (e.g. "example.com")
interval_seconds optional	integer	Check interval (default: 300)
sources optional	array	Sources that check this monitor. Each item is `{"type":"public"}` or `{"type":"poller","poller_id":N}`. Defaults to `[{"type":"public"}]`.
category_ids optional	array	Category IDs to assign

Request

{
  "name": "Main Website SSL",
  "target": "example.com",
  "interval_seconds": 3600,
  "sources": [
    { "type": "public" },
    { "type": "poller", "poller_id": 3 }
  ]
}

Response 201 Created

{
  "id": 6,
  "name": "Main Website SSL",
  "type": "ssl",
  "target": "example.com",
  "interval_seconds": 3600,
  "active": 1,
  "sources": [
    { "type": "public" },
    { "type": "poller", "poller_id": 3 }
  ],
  "categories": []
}

Note: If sources is omitted on create/update, it defaults to [{"type":"public"}].

GET /api/ssl/{id} Get SSL monitor details

No auth required

Returns full SSL monitor details with last 50 results, uptime stats, and certificate info.

Response 200 OK

{
  "id": 2,
  "name": "Main Website",
  "type": "ssl",
  "target": "example.com",
  "interval_seconds": 3600,
  "active": 1,
  "sources": [
    { "type": "public" },
    { "type": "poller", "poller_id": 3 }
  ],
  "categories": [],
  "results": []
}

PUT /api/ssl/{id} Update an SSL monitor

No auth required

Same fields as create. Only include fields you want to change. Supports name, target, interval_seconds, active, sources, and category_ids.

Request

{
  "interval_seconds": 7200,
  "sources": [
    { "type": "public" },
    { "type": "poller", "poller_id": 5 }
  ]
}

DELETE /api/ssl/{id} Delete an SSL monitor

No auth required

Permanently deletes the SSL monitor and all its check results.

Response 200 OK

{ "message": "Monitor deleted" }

POST /api/ssl/{id}/check Trigger immediate SSL check

No auth required

Performs an immediate SSL certificate check. Returns days remaining, issuer, expiry, and validity status.

Response 201 Created

{
  "id": 200,
  "monitor_id": 2,
  "status": "up",
  "response_time_ms": 312,
  "details": {
    "days_remaining": 87,
    "issuer": "Let's Encrypt Authority X3",
    "subject": "example.com",
    "not_before": "2026-01-02T00:00:00",
    "not_after": "2026-06-28T00:00:00"
  },
  "checked_at": "2026-04-02T12:10:00"
}

HTTP Monitors

Monitor web endpoints with HTTP/HTTPS requests. Supports custom methods, expected status codes, and content matching.

GET /api/http/ List all HTTP monitors

No auth required

Returns all HTTP monitors with latest status, parsed URL/method/expected_status, categories, and 24h uptime.

Response 200 OK

[
  {
    "id": 3,
    "name": "API Health Check",
    "type": "http",
    "url": "https://api.example.com/health",
    "method": "GET",
    "expected_status": 200,
    "search_string": null,
    "latest_status": "up",
    "latest_response_time_ms": 189,
    "uptime_24h": 99.5,
    "sources": [
      { "type": "public", "poller_id": null, "poller_name": null },
      { "type": "poller", "poller_id": 3, "poller_name": "FFM Poller" }
    ],
    "categories": []
  }
]

POST /api/http/ Create an HTTP monitor

No auth required

Request Body

Field	Type	Description
name REQUIRED	string	Display name
url REQUIRED	string	Full URL to monitor (including protocol)
method optional	string	HTTP method: GET, POST, PUT, etc. (default: GET)
expected_status optional	integer	Expected HTTP status code (default: 200)
search_string optional	string	String that must appear in the response body
interval_seconds optional	integer	Check interval (default: 300)
sources optional	array	Sources that check this monitor. Each item is `{"type":"public"}` or `{"type":"poller","poller_id":N}`. Defaults to `[{"type":"public"}]`.
category_ids optional	array	Category IDs to assign

Request

{
  "name": "API Health Check",
  "url": "https://api.example.com/health",
  "method": "GET",
  "expected_status": 200,
  "search_string": "\"status\":\"ok\"",
  "interval_seconds": 60,
  "sources": [
    { "type": "public" },
    { "type": "poller", "poller_id": 3 }
  ]
}

Note: If sources is omitted on create/update, it defaults to [{"type":"public"}].

Response 201 Created

{
  "id": 7,
  "name": "API Health Check",
  "type": "http",
  "active": 1,
  "categories": []
}

GET /api/http/{id} Get HTTP monitor details

No auth required

Returns monitor details with last 50 results and uptime stats.

PUT /api/http/{id} Update an HTTP monitor

No auth required

Partial update. Supports: name, url, method, expected_status, search_string, interval_seconds, active, sources, category_ids.

DELETE /api/http/{id} Delete an HTTP monitor

No auth required

Permanently deletes the HTTP monitor and all results.

Response 200 OK

{ "message": "Monitor deleted" }

POST /api/http/{id}/check Trigger immediate HTTP check

No auth required

Performs an immediate HTTP request check. Returns status code, response time, and body match results.

Response 201 Created

{
  "id": 300,
  "monitor_id": 3,
  "status": "up",
  "response_time_ms": 195,
  "details": {
    "status_code": 200,
    "expected_status": 200,
    "search_string_found": true
  },
  "checked_at": "2026-04-02T12:15:00"
}

Port Monitors

Monitor TCP port connectivity. Check if services like databases, mail servers, or custom apps are accepting connections.

GET /api/port/ List all port monitors

No auth required

Returns all port monitors with parsed host and port fields, latest status, categories, and uptime.

Response 200 OK

[
  {
    "id": 4,
    "name": "PostgreSQL",
    "type": "port",
    "host": "db.example.com",
    "port": 5432,
    "latest_status": "up",
    "latest_response_time_ms": 3.2,
    "uptime_24h": 100.0,
    "sources": [
      { "type": "public", "poller_id": null, "poller_name": null },
      { "type": "poller", "poller_id": 3, "poller_name": "FFM Poller" }
    ],
    "categories": []
  }
]

POST /api/port/ Create a port monitor

No auth required

Request Body

Field	Type	Description
name REQUIRED	string	Display name
host REQUIRED	string	Hostname or IP address
port REQUIRED	integer	TCP port number (1-65535)
interval_seconds optional	integer	Check interval (default: 300)
sources optional	array	Sources that check this monitor. Each item is `{"type":"public"}` or `{"type":"poller","poller_id":N}`. Defaults to `[{"type":"public"}]`.
category_ids optional	array	Category IDs to assign

Request

{
  "name": "PostgreSQL",
  "host": "db.example.com",
  "port": 5432,
  "interval_seconds": 60,
  "sources": [
    { "type": "public" },
    { "type": "poller", "poller_id": 3 }
  ]
}

Note: If sources is omitted on create/update, it defaults to [{"type":"public"}].

Response 201 Created

{
  "id": 8,
  "name": "PostgreSQL",
  "type": "port",
  "host": "db.example.com",
  "port": 5432,
  "active": 1,
  "categories": []
}

GET /api/port/{id} Get port monitor details

No auth required

Returns monitor details with last 50 results, parsed host/port, and uptime stats.

PUT /api/port/{id} Update a port monitor

No auth required

Partial update. Supports: name, host, port, interval_seconds, active, sources, category_ids.

DELETE /api/port/{id} Delete a port monitor

No auth required

Permanently deletes the port monitor and all results.

Response 200 OK

{ "message": "Monitor deleted" }

POST /api/port/{id}/check Trigger immediate port check

No auth required

Performs an immediate TCP connection check on the configured host and port.

Response 201 Created

{
  "id": 400,
  "monitor_id": 4,
  "status": "up",
  "response_time_ms": 2.8,
  "details": {
    "host": "db.example.com",
    "port": 5432,
    "connected": true
  },
  "checked_at": "2026-04-02T12:20:00"
}

Dashboard API

Aggregate endpoints for dashboard views. All read-only, no authentication required.

GET /api/dashboard/stats Get dashboard statistics

No auth required

Returns aggregate counts of monitors by status, plus category usage stats.

Response 200 OK

{
  "total_monitors": 12,
  "monitors_up": 10,
  "monitors_down": 1,
  "monitors_warning": 1,
  "monitors_maintenance": 0,
  "categories": [
    { "id": 1, "name": "Production", "color": "#00d68f", "count": 8 },
    { "id": 2, "name": "Staging", "color": "#ffaa00", "count": 4 }
  ]
}

GET /api/dashboard/recent Get recent check results

No auth required

Returns the last 50 check results across all monitors, with monitor name, type, and categories.

Response 200 OK

[
  {
    "id": 500,
    "monitor_id": 1,
    "monitor_name": "Google DNS",
    "monitor_type": "ping",
    "status": "up",
    "response_time_ms": 12.5,
    "details": { /* ... */ },
    "checked_at": "2026-04-02T12:30:00",
    "categories": []
  }
]

GET /api/dashboard/overview Get all monitors overview

No auth required

Returns all monitors with their latest check result, categories, and 24h uptime. Sorted by status (down first).

Response 200 OK

[
  {
    "id": 1,
    "name": "Google DNS",
    "type": "ping",
    "target": "8.8.8.8",
    "active": true,
    "latest_check": {
      "status": "up",
      "response_time_ms": 12.5,
      "checked_at": "2026-04-02T12:30:00"
    },
    "categories": [],
    "uptime_24h": 99.8
  }
]

Categories API

Organize monitors into categories with custom colors. Categories can be assigned to any monitor type.

GET /api/categories/ List all categories

No auth required

Returns all categories ordered by name.

Response 200 OK

[
  { "id": 1, "name": "Production", "color": "#00d68f" },
  { "id": 2, "name": "Staging", "color": "#ffaa00" }
]

POST /api/categories/ Create a category

No auth required

Request Body

Field	Type	Description
name REQUIRED	string	Category name (must be unique)
color optional	string	Hex color code (default: "#6b7280")

Request

{
  "name": "Production",
  "color": "#00d68f"
}

Response 201 Created

{
  "id": 3,
  "name": "Production",
  "color": "#00d68f"
}

409 Conflict is returned if a category with the same name already exists.

PUT /api/categories/{id} Update a category

No auth required

Update category name and/or color. Name uniqueness is enforced.

Field	Type	Description
name optional	string	New category name
color optional	string	New hex color code

Response 200 OK

{
  "id": 1,
  "name": "Prod",
  "color": "#10b981"
}

DELETE /api/categories/{id} Delete a category

No auth required

Deletes the category. Monitor-category assignments are removed automatically (cascade).

Response 200 OK

{ "message": "Category deleted" }

GET /api/categories/{id}/monitors List monitors in a category

No auth required

Returns all monitors assigned to the specified category.

Response 200 OK

[
  {
    "id": 1,
    "name": "Google DNS",
    "type": "ping",
    "target": "8.8.8.8",
    "active": 1
  }
]

Maintenance Windows API

Schedule maintenance windows to suppress alerts for specific monitors during planned downtime.

GET /api/maintenance/ List all maintenance windows

No auth required

Returns all maintenance windows ordered by start time (newest first). Includes a computed is_active boolean.

Response 200 OK

[
  {
    "id": 1,
    "name": "DB Migration",
    "monitor_ids": [1, 4],
    "start_time": "2026-04-05T02:00:00",
    "end_time": "2026-04-05T04:00:00",
    "recurring": 0,
    "recurrence_type": null,
    "notes": "Schema migration to v2",
    "is_active": false,
    "created_at": "2026-04-01T10:00:00"
  }
]

POST /api/maintenance/ Create a maintenance window

No auth required

Request Body

Field	Type	Description
name REQUIRED	string	Window name / description
monitor_ids REQUIRED	array	Monitor IDs to suppress, or `["all"]` for all monitors
start_time REQUIRED	string	ISO 8601 start time
end_time REQUIRED	string	ISO 8601 end time (must be after start_time)
recurring optional	integer	0 = one-time, 1 = recurring (default: 0)
recurrence_type optional	string	Recurrence pattern (e.g. "weekly", "monthly")
notes optional	string	Free-form notes

Request

{
  "name": "Weekly Backup Window",
  "monitor_ids": [1, 4, 8],
  "start_time": "2026-04-06T03:00:00",
  "end_time": "2026-04-06T05:00:00",
  "recurring": 1,
  "recurrence_type": "weekly",
  "notes": "Automated backup causes brief downtime"
}

Response 201 Created

{
  "id": 2,
  "name": "Weekly Backup Window",
  "monitor_ids": [1, 4, 8],
  "start_time": "2026-04-06T03:00:00",
  "end_time": "2026-04-06T05:00:00",
  "recurring": 1,
  "recurrence_type": "weekly",
  "notes": "Automated backup causes brief downtime",
  "is_active": false,
  "created_at": "2026-04-02T14:00:00"
}

GET /api/maintenance/active List active maintenance windows

No auth required

Returns only currently active maintenance windows (where current time is between start and end).

GET /api/maintenance/{id} Get a maintenance window

No auth required

Returns a single maintenance window by ID.

PUT /api/maintenance/{id} Update a maintenance window

No auth required

Partial update. All fields from the create endpoint are supported. start_time must remain before end_time.

DELETE /api/maintenance/{id} Delete a maintenance window

No auth required

Response 200 OK

{ "message": "Maintenance window deleted" }

Token Management API

Manage API tokens for agents, pollers, and administrators. All endpoints require an admin token.

GET /api/tokens/ List all tokens

Admin only

Returns all tokens. Token values are masked (only first 8 characters shown).

Request

curl -H "Authorization: Bearer ADMIN_TOKEN" \
     http://your-server:5000/api/tokens/

Response 200 OK

[
  {
    "id": 1,
    "token": "sw_a1b2c...",
    "name": "Primary Admin",
    "type": "admin",
    "active": 1,
    "created_at": "2026-03-01T08:00:00",
    "last_used_at": "2026-04-02T12:00:00"
  }
]

POST /api/tokens/ Create a new token

Admin only

Request Body

Field	Type	Description
name REQUIRED	string	Descriptive name for the token
type REQUIRED	string	One of: `admin`, `agent`, `poller`

Request

{
  "name": "NYC Agent",
  "type": "agent"
}

Response 201 Created

{
  "id": 5,
  "token": "sw_a1b2c3d4e5f6g7h8i9j0...",
  "name": "NYC Agent",
  "type": "agent",
  "message": "Store this token securely. It will not be shown again."
}

Important: The full token value is only returned once at creation time. Store it immediately in a secure location.

DELETE /api/tokens/{id} Deactivate a token

Admin only

Soft-deletes a token by setting it to inactive. The token can no longer be used for authentication.

Response 200 OK

{
  "message": "Token 5 deactivated"
}

POST /api/tokens/{id}/regenerate Regenerate a token

Admin only

Replaces the token value with a new one. The old token immediately stops working. No request body needed.

Response 200 OK

{
  "id": 5,
  "token": "sw_newtoken123456789...",
  "name": "NYC Agent",
  "type": "agent",
  "message": "Token regenerated. Store this token securely. It will not be shown again."
}

Agent API

Endpoints for monitoring agents running on remote servers. Agents register, send heartbeats, report system metrics, and submit check results.

Agent Endpoints (require agent token)

POST /api/agent/register Register an agent

Agent token

Register a new agent or re-register an existing one. If the same token+hostname combination already exists, the agent is updated instead of duplicated.

Request Body

Field	Type	Description
hostname REQUIRED	string	Hostname of the agent machine
os_info optional	string	Operating system information
agent_version optional	string	Agent software version

Request

curl -X POST http://your-server:5000/api/agent/register \
  -H "Authorization: Bearer AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "web-server-01",
    "os_info": "Ubuntu 24.04 LTS",
    "agent_version": "1.0.0"
  }'

Response 201 Created

{
  "agent_id": 1,
  "message": "Agent registered"
}

POST /api/agent/heartbeat Send heartbeat

Agent token

Update the agent's last heartbeat time and set status to "online". Should be called periodically (e.g. every 60s).

Field	Type	Description
agent_id REQUIRED	integer	Agent ID returned from registration

Request

{ "agent_id": 1 }

Response 200 OK

{
  "status": "ok",
  "server_time": "2026-04-02T12:35:00"
}

POST /api/agent/metrics Report system metrics

Agent token

Submit system resource metrics from the agent host.

Field	Type	Description
agent_id REQUIRED	integer	Agent ID
cpu_percent optional	number	CPU usage percentage
memory_percent optional	number	Memory usage percentage
disk_percent optional	number	Disk usage percentage
load_avg optional	string	System load average
processes optional	integer	Number of running processes
uptime_seconds optional	integer	System uptime in seconds
custom_metrics optional	object	Arbitrary key-value pairs

Request

{
  "agent_id": 1,
  "cpu_percent": 45.2,
  "memory_percent": 72.8,
  "disk_percent": 38.1,
  "load_avg": "1.25 0.98 0.85",
  "processes": 215,
  "uptime_seconds": 864000,
  "custom_metrics": {
    "nginx_connections": 142,
    "redis_memory_mb": 256
  }
}

Response 200 OK

{
  "status": "ok",
  "collected_at": "2026-04-02T12:36:00"
}

POST /api/agent/check-results Report check results

Agent token

Submit monitoring check results performed locally by the agent.

Field	Type	Description
agent_id REQUIRED	integer	Agent ID
results REQUIRED	array	Array of check result objects

Request

{
  "agent_id": 1,
  "results": [
    {
      "monitor_id": 1,
      "status": "up",
      "response_time_ms": 5.2,
      "details": { "packets_sent": 4, "packets_received": 4 }
    }
  ]
}

Response 200 OK

{
  "status": "ok",
  "inserted": 1
}

GET /api/agent/tasks/{agent_id} Get assigned tasks

Agent token

Returns monitors assigned to this agent. Assignment is based on matching the agent's hostname to a category name.

Response 200 OK

[
  {
    "id": 1,
    "name": "Google DNS",
    "type": "ping",
    "target": "8.8.8.8",
    "interval_seconds": 60
  }
]

Admin Endpoints (require admin token)

GET /api/agent/ List all agents

Admin only

Returns all registered agents with status, hostname, IP, and version info.

Response 200 OK

[
  {
    "id": 1,
    "hostname": "web-server-01",
    "ip_address": "10.0.1.15",
    "os_info": "Ubuntu 24.04 LTS",
    "agent_version": "1.0.0",
    "last_heartbeat": "2026-04-02T12:35:00",
    "status": "online",
    "registered_at": "2026-03-20T09:00:00"
  }
]

GET /api/agent/{id}/metrics Get agent metrics

Admin only

Returns recent system metrics for an agent. Supports ?limit=N query parameter (default: 100).

Request

curl -H "Authorization: Bearer ADMIN_TOKEN" \
     http://your-server:5000/api/agent/1/metrics?limit=10

Response 200 OK

[
  {
    "id": 50,
    "agent_id": 1,
    "cpu_percent": 45.2,
    "memory_percent": 72.8,
    "disk_percent": 38.1,
    "load_avg": "1.25 0.98 0.85",
    "processes": 215,
    "uptime_seconds": 864000,
    "custom_metrics": "{}",
    "collected_at": "2026-04-02T12:36:00"
  }
]

DELETE /api/agent/{id} Delete an agent

Admin only

Removes the agent registration and all its stored metrics.

Response 200 OK

{
  "status": "deleted",
  "agent_id": 1,
  "hostname": "web-server-01"
}

Poller API

Endpoints for distributed pollers that execute monitoring checks from different geographic locations. The poller API enables LILLYDOO Pulse to perform checks from multiple vantage points.

Poller Endpoints (require poller token)

POST /api/poller/register Register a poller

Poller token

Request Body

Field	Type	Description
name REQUIRED	string	Poller display name
location optional	string	Geographic location (e.g. "US-East", "EU-West")
poller_version optional	string	Poller software version

Request

{
  "name": "US-East-1",
  "location": "Virginia, US",
  "poller_version": "1.0.0"
}

Response 201 Created

{
  "poller_id": 1,
  "message": "Poller registered"
}

POST /api/poller/heartbeat Send poller heartbeat

Poller token

Keep the poller's status as "online". Call periodically.

Request

{ "poller_id": 1 }

Response 200 OK

{ "status": "ok", "server_time": "2026-04-02T12:40:00" }

GET /api/poller/tasks/{poller_id} Get assigned tasks

Poller token

Fetch the list of monitors this poller should check. The poller should call this periodically and execute the returned checks.

Response 200 OK

[
  {
    "id": 1,
    "name": "Google DNS",
    "type": "ping",
    "target": "8.8.8.8",
    "interval_seconds": 60
  }
]

POST /api/poller/results Submit check results

Poller token

Submit monitoring check results from the poller. Same structure as agent check-results.

Request

{
  "poller_id": 1,
  "results": [
    {
      "monitor_id": 1,
      "status": "up",
      "response_time_ms": 25.4,
      "details": {}
    }
  ]
}

Response 200 OK

{ "status": "ok", "inserted": 1 }

Admin Endpoints (require admin token)

GET /api/poller/ List all pollers

Admin only

Returns all registered pollers with status, location, and version info.

Response 200 OK

[
  {
    "id": 1,
    "name": "US-East-1",
    "location": "Virginia, US",
    "status": "online",
    "last_heartbeat": "2026-04-02T12:40:00",
    "assigned_monitors": 5
  }
]

PUT /api/poller/{id}/assign Assign monitors to poller

Admin only

Assign a set of monitors to be checked by this poller.

Request

{
  "monitor_ids": [1, 2, 3, 7]
}

Response 200 OK

{
  "status": "ok",
  "poller_id": 1,
  "assigned_monitors": 4
}

DELETE /api/poller/{id} Delete a poller

Admin only

Removes a poller registration and all its assignments.

Response 200 OK

{
  "status": "deleted",
  "poller_id": 1
}