Skip to main content

ThingConnect Pulse API

The ThingConnect Pulse REST API provides programmatic access to all monitoring data and configuration management features. Use the API to integrate Pulse with external systems, automate configuration updates, and build custom dashboards.

Base URL​

http://localhost:8090/api
Default Port

The default port is 8090, but check your installation if using a different port. All API endpoints are prefixed with /api.

Authentication​

All API endpoints require authentication using cookie-based sessions.

Login Process​

  1. POST to /api/auth/login with credentials
  2. Receive authentication cookie
  3. Include cookie in subsequent requests
  4. Session expires after 24 hours of inactivity

Example Login​

# Login and save cookies
curl -c cookies.txt -X POST http://localhost:8090/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

# Use cookies for authenticated requests
curl -b cookies.txt http://localhost:8090/api/status/live

Session Management​

Session Duration

  • 24-hour sliding expiration
  • Extended by each API request
  • Automatic logout after inactivity

Cookie Security

  • HTTP-only cookies (not accessible via JavaScript)
  • Secure flag in production environments
  • SameSite protection enabled

Available Endpoints​

Live Status Monitoring​

GET /api/status/live

Retrieve current status of all monitored endpoints with optional filtering.

Query Parameters:

  • group (optional): Filter by group ID
  • search (optional): Search endpoint names and hosts

Response:

{
  "items": [
    {
      "endpoint": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Production Server",
        "host": "192.168.1.10",
        "type": "icmp",
        "group": {
          "id": "production",
          "name": "Production Floor",
          "color": "#00FF00"
        }
      },
      "status": "UP",
      "rttMs": 12.5,
      "lastChangeTs": "2024-12-01T14:30:45Z",
      "sparkline": [
        {"ts": "2024-12-01T14:00:00Z", "s": "UP"},
        {"ts": "2024-12-01T14:15:00Z", "s": "UP"}
      ]
    }
  ]
}

Historical Data Access​

GET /api/history/endpoint/{id}

Retrieve historical monitoring data for a specific endpoint.

Path Parameters:

  • id: Endpoint UUID

Query Parameters:

  • from: Start timestamp (ISO 8601 format)
  • to: End timestamp (ISO 8601 format)
  • bucket: Data granularity (raw, 15m, daily)

Example Request:

curl -b cookies.txt \
  "http://localhost:8090/api/history/endpoint/550e8400-e29b-41d4-a716-446655440000?from=2024-12-01T00:00:00Z&to=2024-12-01T23:59:59Z&bucket=15m"

Response:

{
  "endpoint": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Server",
    "host": "192.168.1.10",
    "type": "icmp"
  },
  "raw": [],
  "rollup15m": [
    {
      "bucketTs": "2024-12-01T14:00:00Z",
      "upPct": 95.5,
      "avgRttMs": 23.7,
      "downEvents": 1
    }
  ],
  "rollupDaily": [],
  "outages": [
    {
      "startedTs": "2024-12-01T14:30:45Z",
      "endedTs": "2024-12-01T14:45:12Z",
      "durationS": 867,
      "lastError": "Connection timeout"
    }
  ]
}

Endpoint Details​

GET /api/endpoints/{id}

Get detailed information about a specific endpoint including recent checks and outages.

Path Parameters:

  • id: Endpoint UUID

Query Parameters:

  • windowMinutes (optional): Recent check window in minutes (default: 60)

Response:

{
  "endpoint": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Server",
    "host": "192.168.1.10",
    "type": "icmp",
    "intervalSeconds": 60,
    "timeoutMs": 3000,
    "enabled": true
  },
  "recent": [
    {
      "ts": "2024-12-01T14:30:45Z",
      "status": "UP",
      "rttMs": 12.5,
      "error": null
    }
  ],
  "outages": [
    {
      "startedTs": "2024-12-01T14:30:45Z",
      "endedTs": "2024-12-01T14:45:12Z",
      "durationS": 867,
      "lastError": "Connection timeout"
    }
  ]
}

Configuration Management​

POST /api/configuration/apply

Apply a new YAML configuration to the system.

Headers:

  • Content-Type: text/plain
  • X-Actor (optional): Name of person applying configuration
  • X-Note (optional): Notes about the configuration change

Query Parameters:

  • dryRun (optional): If true, validate only without applying

Request Body:

version: 1
defaults:
  interval_seconds: 60
  timeout_ms: 3000
  retries: 1

groups:
  - id: production
    name: "Production Floor"

targets:
  - name: "Production Server"
    host: "192.168.1.10"
    type: icmp
    group: production

Response:

{
  "configVersionId": "v1.2024.12.01.143045",
  "added": 5,
  "updated": 2,
  "removed": 1,
  "warnings": []
}

GET /api/configuration/versions

List all configuration versions with metadata.

Response:

[
  {
    "id": "v1.2024.12.01.143045",
    "appliedTs": "2024-12-01T14:30:45Z",
    "fileHash": "sha256:abc123...",
    "filePath": "/versions/v1.2024.12.01.143045.yaml",
    "actor": "admin",
    "note": "Added new production endpoints"
  }
]

GET /api/configuration/versions/{id}

Download a specific configuration version as YAML.

Response:

version: 1
defaults:
  interval_seconds: 60
# ... rest of configuration

GET /api/configuration/current

Get the currently active configuration as YAML.

User Management (Administrators Only)​

GET /api/usermanagement

List all users with pagination and filtering.

Query Parameters:

  • page (optional): Page number (default: 1)
  • pageSize (optional): Items per page (default: 20, max: 100)
  • search (optional): Search username or email
  • role (optional): Filter by role (Administrator or User)
  • isActive (optional): Filter by active status

Response:

{
  "data": [
    {
      "id": "user-uuid",
      "username": "admin",
      "email": "admin@company.com",
      "role": "Administrator",
      "createdAt": "2024-12-01T10:00:00Z",
      "lastLoginAt": "2024-12-01T14:30:45Z",
      "isActive": true
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 1,
    "totalItems": 5
  }
}

POST /api/usermanagement

Create a new user account.

Request Body:

{
  "username": "newuser",
  "email": "newuser@company.com",
  "password": "SecurePass123!",
  "confirmPassword": "SecurePass123!",
  "role": "User"
}

Response:

{
  "id": "new-user-uuid",
  "username": "newuser",
  "email": "newuser@company.com",
  "role": "User",
  "createdAt": "2024-12-01T14:30:45Z",
  "isActive": true
}

PUT /api/usermanagement/{id}

Update user details (username, email).

PUT /api/usermanagement/{id}/role

Change user role between Administrator and User.

Request Body:

{
  "role": "Administrator"
}

PUT /api/usermanagement/{id}/status

Toggle user active/inactive status.

PUT /api/usermanagement/{id}/password

Reset user password (forces password change on next login).

DELETE /api/usermanagement/{id}

Delete a user account permanently.

Data Export​

CSV Export via API​

Use the web interface CSV export feature, or query historical data via API and format as needed.

Historical Data Export Process:

  1. Query /api/history/endpoint/{id} with desired date range
  2. Specify appropriate bucket type (raw, 15m, daily)
  3. Process JSON response into desired format

Bulk Data Access​

For Multiple Endpoints:

  1. Get endpoint list from /api/status/live
  2. Query each endpoint's historical data
  3. Combine results as needed

Performance Considerations:

  • Use rollup data (15m, daily) for large date ranges
  • Implement pagination for large datasets
  • Consider caching for frequently accessed data

Error Handling​

HTTP Status Codes​

  • 200 OK: Successful request
  • 400 Bad Request: Invalid parameters or request format
  • 401 Unauthorized: Authentication required or session expired
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Endpoint or resource not found
  • 500 Internal Server Error: Server-side error

Error Response Format​

{
  "message": "Human-readable error description",
  "error": "Technical error details (optional)",
  "validationErrors": [
    {
      "path": "targets[0].port",
      "message": "Port is required for TCP probes",
      "value": null
    }
  ]
}

Common Error Scenarios​

Authentication Errors

  • Session expired: Re-authenticate with login endpoint
  • Invalid credentials: Check username/password
  • Missing cookies: Ensure cookie handling in client

Configuration Errors

  • YAML syntax errors: Check indentation and format
  • Validation failures: Review error details for specific issues
  • Missing required fields: Ensure all mandatory properties are present

Data Query Errors

  • Invalid date ranges: Check ISO 8601 format and logical ranges
  • Endpoint not found: Verify endpoint ID exists
  • Invalid bucket type: Use raw, 15m, or daily only

Rate Limiting and Best Practices​

API Usage Guidelines​

Request Frequency

  • Live status: No more than once per 30 seconds
  • Historical data: Reasonable intervals based on data freshness
  • Configuration changes: Only when actually needed

Data Retrieval

  • Use appropriate bucket types for your analysis needs
  • Request only the date ranges you actually need
  • Cache results when possible

Authentication

  • Reuse sessions rather than logging in repeatedly
  • Handle session expiration gracefully
  • Log out when finished to clean up server resources

Integration Patterns​

Dashboard Integration

  • Poll live status every 30-60 seconds
  • Use sparkline data for trend visualization
  • Handle endpoint additions/removals dynamically

Alerting Systems

  • Monitor for status changes in live feed
  • Use outage data for alert correlation
  • Implement proper alert de-duplication

Reporting Systems

  • Use rollup data for historical reports
  • Schedule report generation during off-peak hours
  • Cache report data to reduce API load
API Development

The Pulse web interface uses the same API endpoints documented here. Use browser developer tools to see example requests and responses while using the web interface.

Example Integrations​

PowerShell Script Example​

# Login and get current status
$loginBody = @{
    username = "admin"
    password = "your-password"
} | ConvertTo-Json

$session = Invoke-WebRequest -Uri "http://localhost:8090/api/auth/login" `
    -Method POST -Body $loginBody -ContentType "application/json" `
    -SessionVariable pulseSession

# Get live status
$status = Invoke-RestMethod -Uri "http://localhost:8090/api/status/live" `
    -WebSession $pulseSession

# Display endpoints that are DOWN
$status.items | Where-Object { $_.status -eq "DOWN" } |
    Select-Object @{N="Name";E={$_.endpoint.name}},
                  @{N="Host";E={$_.endpoint.host}},
                  @{N="LastChange";E={$_.lastChangeTs}}

Python Script Example​

import requests
import json
from datetime import datetime, timedelta

# Login
session = requests.Session()
login_data = {
    "username": "admin",
    "password": "your-password"
}
session.post("http://localhost:8090/api/auth/login", json=login_data)

# Get historical data for last 24 hours
end_time = datetime.now()
start_time = end_time - timedelta(days=1)

endpoint_id = "550e8400-e29b-41d4-a716-446655440000"
history = session.get(f"http://localhost:8090/api/history/endpoint/{endpoint_id}",
    params={
        "from": start_time.isoformat() + "Z",
        "to": end_time.isoformat() + "Z",
        "bucket": "15m"
    })

# Calculate average uptime
rollups = history.json()["rollup15m"]
if rollups:
    avg_uptime = sum(r["upPct"] for r in rollups) / len(rollups)
    print(f"24-hour average uptime: {avg_uptime:.1f}%")

Next Steps​