Back to Documentation
API
v1.0

API Reference

Complete REST API documentation for integrating Nodewarden with your applications and workflows.

Last updated: December 1, 2024
7 min read

API Reference

The Nodewarden API provides programmatic access to your monitoring data and configuration. Use it to integrate monitoring into your applications, automate workflows, and build custom dashboards.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

bash
Authorization: Bearer your-api-key-here

Getting Your API Key

  1. Log in to your Nodewarden dashboard
  2. Go to Settings → API Keys
  3. Click "Generate New Key"
  4. Copy and store the key securely

Security Note: API keys provide full access to your account. Keep them secure and rotate them regularly.

Base URL

All API endpoints are available at:

https://api.nodewarden.com/v1

Rate Limiting

API requests are limited to:

  • 1000 requests per hour for free accounts
  • 10,000 requests per hour for paid accounts
  • 100,000 requests per hour for enterprise accounts

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1638360000

Error Handling

The API uses standard HTTP status codes and returns JSON error responses:

json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request is missing required parameters",
    "details": {
      "missing_fields": ["customer_id"]
    }
  }
}

Common error codes:

  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 429 - Rate Limited
  • 500 - Internal Server Error

Endpoints

Hosts

List Hosts

Get all monitored hosts for your account.

http
GET /hosts

Parameters:

  • limit (optional) - Number of results to return (default: 50, max: 200)
  • offset (optional) - Number of results to skip (default: 0)
  • status (optional) - Filter by status: online, offline, warning

Example Request:

bash
curl -H "Authorization: Bearer your-api-key" \
  "https://api.nodewarden.com/v1/hosts?limit=10&status=online"

Example Response:

json
{
  "data": [
    {
      "id": "host_123",
      "name": "web-server-01",
      "hostname": "web01.example.com",
      "ip_address": "192.168.1.10",
      "status": "online",
      "last_seen": "2024-12-01T10:30:00Z",
      "agent_version": "1.2.3",
      "os": {
        "name": "Ubuntu",
        "version": "20.04",
        "architecture": "x86_64"
      },
      "metrics": {
        "cpu_usage": 25.5,
        "memory_usage": 67.2,
        "disk_usage": 45.8
      }
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Get Host Details

Get detailed information about a specific host.

http
GET /hosts/{host_id}

Example Request:

bash
curl -H "Authorization: Bearer your-api-key" \
  "https://api.nodewarden.com/v1/hosts/host_123"

Metrics

Query Metrics

Query time-series metrics data.

http
GET /metrics

Parameters:

  • host_id (required) - Host identifier
  • metric (required) - Metric name (e.g., cpu.usage, memory.usage)
  • start_time (required) - Start time (ISO 8601 format)
  • end_time (required) - End time (ISO 8601 format)
  • resolution (optional) - Data resolution: 1m, 5m, 1h, 1d (default: 5m)

Example Request:

bash
curl -H "Authorization: Bearer your-api-key" \
  "https://api.nodewarden.com/v1/metrics?host_id=host_123&metric=cpu.usage&start_time=2024-12-01T00:00:00Z&end_time=2024-12-01T12:00:00Z&resolution=1h"

Example Response:

json
{
  "data": {
    "metric": "cpu.usage",
    "host_id": "host_123",
    "points": [
      {
        "timestamp": "2024-12-01T00:00:00Z",
        "value": 15.2
      },
      {
        "timestamp": "2024-12-01T01:00:00Z",
        "value": 18.7
      }
    ]
  }
}

Available Metrics

Common metric names:

| Metric | Description | Unit | |--------|-------------|------| | cpu.usage | CPU utilization percentage | percent | | memory.usage | Memory utilization percentage | percent | | disk.usage | Disk utilization percentage | percent | | network.in | Network bytes received | bytes/sec | | network.out | Network bytes transmitted | bytes/sec | | load.1m | 1-minute load average | float | | uptime | System uptime | seconds |

Alerts

List Alert Rules

Get all alert rules for your account.

http
GET /alerts/rules

Example Response:

json
{
  "data": [
    {
      "id": "rule_456",
      "name": "High CPU Usage",
      "description": "Alert when CPU usage exceeds 80%",
      "enabled": true,
      "conditions": [
        {
          "metric": "cpu.usage",
          "operator": "greater_than",
          "threshold": 80,
          "duration": "5m"
        }
      ],
      "notifications": ["email", "slack"]
    }
  ]
}

Create Alert Rule

Create a new alert rule.

http
POST /alerts/rules

Request Body:

json
{
  "name": "High Memory Usage",
  "description": "Alert when memory usage exceeds 90%",
  "enabled": true,
  "conditions": [
    {
      "metric": "memory.usage",
      "operator": "greater_than",
      "threshold": 90,
      "duration": "3m"
    }
  ],
  "notifications": ["email"]
}

WordPress

List WordPress Sites

Get all monitored WordPress sites.

http
GET /wordpress/sites

Example Response:

json
{
  "data": [
    {
      "id": "wp_789",
      "url": "https://example.com",
      "name": "Example Site",
      "version": "6.4.1",
      "status": "healthy",
      "last_updated": "2024-12-01T10:15:00Z",
      "plugins": {
        "total": 15,
        "active": 12,
        "updates_available": 3
      },
      "performance": {
        "page_load_time": 1.2,
        "core_web_vitals": "good"
      }
    }
  ]
}

SDKs and Libraries

Official SDKs are available for popular programming languages:

  • JavaScript/Node.js: npm install @nodewarden/sdk
  • Python: pip install nodewarden
  • PHP: composer require nodewarden/sdk
  • Go: go get github.com/moriahlabs/nodewarden-go-sdk

JavaScript Example

javascript
import { Nodewarden } from '@nodewarden/sdk';

const nw = new Nodewarden({ apiKey: 'your-api-key' });

// Get all hosts
const hosts = await nw.hosts.list();

// Query metrics
const metrics = await nw.metrics.query({
  hostId: 'host_123',
  metric: 'cpu.usage',
  startTime: '2024-12-01T00:00:00Z',
  endTime: '2024-12-01T12:00:00Z'
});

Python Example

python
from nodewarden import Client

nw = Client(api_key='your-api-key')

# Get all hosts
hosts = nw.hosts.list()

# Query metrics
metrics = nw.metrics.query(
    host_id='host_123',
    metric='cpu.usage',
    start_time='2024-12-01T00:00:00Z',
    end_time='2024-12-01T12:00:00Z'
)

Webhooks

Nodewarden can send webhook notifications for alerts and system events.

Setting Up Webhooks

  1. Go to Settings → Webhooks in your dashboard
  2. Click "Add Webhook"
  3. Enter your endpoint URL
  4. Select events to receive
  5. Save and test the webhook

Webhook Payload

json
{
  "event": "alert.triggered",
  "timestamp": "2024-12-01T10:30:00Z",
  "data": {
    "alert": {
      "id": "alert_123",
      "rule_name": "High CPU Usage",
      "severity": "warning",
      "host": {
        "id": "host_123",
        "name": "web-server-01"
      },
      "metric": {
        "name": "cpu.usage",
        "value": 85.2,
        "threshold": 80
      }
    }
  }
}

Support

Need help with the API?

Was this page helpful?

Help us improve our documentation

    API Reference | Nodewarden Documentation