Setup

Admin access is disabled by default. To enable it, set the PWS_ADMIN_KEY environment variable to a secret string.

Login Flow

1. Navigate to /admin/login and enter your admin key.
2. On success, a pws_admin_key HttpOnly cookie is set (valid 24 hours, scoped to /admin).
3. All subsequent admin page and API requests are authenticated via this cookie.
4. Log out at /admin/logout to clear the cookie.

Authentication

All admin API endpoints require authentication. Provide the admin key via one of:

• Header: X-Admin-Key: your-key
• Query parameter: ?admin_key=your-key
• Cookie: pws_admin_key=your-key (set automatically after login)

Unauthenticated requests receive a 401 response.

Query the in-memory activity log. Returns matching entries newest-first plus aggregate stats.

Query Parameters

Name	Type	Description
level	string	info, warn, or error
category	string	api_request, extraction, auth, rate_limit, or system
search	string	Case-insensitive full-text search across message, path, method, errorCode, scraperName, sourceUrl
limit	number	Max entries to return (default 50)
offset	number	Skip entries for pagination (default 0)

Example Response

{
  "entries": [
    {
      "id": "42",
      "timestamp": 1700000000000,
      "level": "info",
      "category": "api_request",
      "message": "GET /public_api/v1/listings",
      "method": "GET",
      "path": "/public_api/v1/listings"
    }
  ],
  "total": 1,
  "stats": {
    "totalEntries": 128,
    "capacity": 1000,
    "byLevel": { "info": 100, "warn": 20, "error": 8 },
    "byCategory": { "api_request": 90, "extraction": 25, "auth": 5, "rate_limit": 3, "system": 5 }
  }
}

Returns a full dashboard snapshot: server health, listing store, rate limiter, log stats, and scraper status.

Example Response

{
  "health": { "status": "ok", "scrapersLoaded": 16, "storage": "in_memory" },
  "listings": { "count": 42 },
  "rateLimiter": { "activeClients": 3, "totalRequests": 87, "maxRequests": 60 },
  "logs": { "totalEntries": 128, "capacity": 1000, "byLevel": {...}, "byCategory": {...} },
  "scrapers": [
    { "name": "idealista", "loaded": true, "hosts": ["www.idealista.com"] }
  ]
}

GET returns the current runtime configuration. POST updates it.

GET Response

{ "config": { "maxRequests": 60 } }

POST Body (JSON)

Name	Type	Description
maxRequests	number	Rate limit per client per minute (1–1000)

Example

curl -X POST http://localhost:4321/admin/api/config \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: your-key" \
  -d '{"maxRequests": 120}'

# Response:
{ "success": true, "config": { "maxRequests": 120 } }

Execute a maintenance action. Send a JSON body with an action field.

Valid Actions

Action	Description
clear_logs	Clear all activity log entries
clear_mapping_cache	Clear the scraper mapping cache
clear_listing_store	Clear all stored listings
reset_rate_limiter	Reset all rate limit counters

Example

curl -X POST http://localhost:4321/admin/api/actions \
  -H "Content-Type: application/json" \
  -H "X-Admin-Key: your-key" \
  -d '{"action": "clear_logs"}'

# Response:
{ "success": true, "message": "Activity logs cleared" }

Admin UI Pages

The admin dashboard also includes browser-based UI pages:

Path	Description
/admin	Dashboard overview with stats and quick actions
/admin/logs	Activity log viewer with filtering and search
/admin/config	Runtime configuration editor
/admin/login	Login page
/admin/logout	Logout (clears session cookie)