API Documentation

RESTful API for diagnostics data collection and management

Getting Started

The Diagnostics Platform API enables automated collection of system diagnostics data from remote endpoints. All requests require authentication via Bearer token.

Base URL

https://your.domain/api/v1

Authentication

Include your API token in the Authorization header:

Authorization: Bearer your_api_token_here

Content Type

All requests and responses use JSON format:

Content-Type: application/json

Submit Diagnostics Data

POST /api/v1/submit

Submit diagnostics data from a monitored system.

Request Body

{ "hostname": "string", "timestamp": "ISO8601 datetime", "metrics": { "cpu_usage": "number", "memory_usage": "number", "memory_total": "number", "disk_usage": "number", "network_rx_bytes": "number", "network_tx_bytes": "number", "uptime_seconds": "number" }, "logs": [ { "level": "string", "message": "string", "timestamp": "ISO8601 datetime" } ], "tags": ["string"] }

Example Request

curl -X POST https://your.domain/api/v1/submit \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "hostname": "web-server-01", "timestamp": "2025-11-01T07:30:00Z", "metrics": { "cpu_usage": 45.2, "memory_usage": 68.5, "memory_total": 16384, "disk_usage": 82.1, "network_rx_bytes": 1048576000, "network_tx_bytes": 524288000, "uptime_seconds": 3456789 }, "logs": [ { "level": "warning", "message": "High memory usage detected", "timestamp": "2025-11-01T07:29:45Z" } ], "tags": ["production", "web"] }'

Response

{ "status": "success", "message": "Diagnostics data received", "id": "diag_1a2b3c4d5e6f", "timestamp": "2025-11-01T07:30:01Z" }

Retrieve Diagnostics Data

GET /api/v1/diagnostics/{hostname}

Retrieve diagnostics history for a specific hostname.

Query Parameters

Parameter Type Description
from ISO8601 Start date for data retrieval
to ISO8601 End date for data retrieval
limit integer Maximum number of records (default: 100)

Example Request

curl -X GET "https://your.domain/api/v1/diagnostics/web-server-01?from=2025-11-01T00:00:00Z&limit=50" \ -H "Authorization: Bearer YOUR_TOKEN"

Response

{ "status": "success", "hostname": "web-server-01", "count": 2, "data": [ { "id": "diag_1a2b3c4d5e6f", "timestamp": "2025-11-01T07:30:00Z", "metrics": { "cpu_usage": 45.2, "memory_usage": 68.5, "disk_usage": 82.1 } } ] }

List Monitored Systems

GET /api/v1/systems

Get a list of all monitored systems.

Example Request

curl -X GET https://your.domain/api/v1/systems \ -H "Authorization: Bearer YOUR_TOKEN"

Response

{ "status": "success", "count": 3, "systems": [ { "hostname": "web-server-01", "last_seen": "2025-11-01T07:30:00Z", "status": "healthy", "tags": ["production", "web"] }, { "hostname": "db-server-01", "last_seen": "2025-11-01T07:29:30Z", "status": "warning", "tags": ["production", "database"] } ] }

Health Check

GET /api/v1/health

Check API availability and service health.

Example Request

curl -X GET https://your.domain/api/v1/health

Response

{ "status": "healthy", "version": "1.0.0", "uptime": 3456789, "timestamp": "2025-11-01T07:30:00Z" }

Response Codes

Code Description
200 OK Request succeeded
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Missing or invalid authentication token
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred

Rate Limiting

API requests are limited to prevent abuse:

Rate limit headers are included in all responses:

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

Code Examples

Python

import requests import json from datetime import datetime url = "https://your.domain/api/v1/submit" headers = { "Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json" } data = { "hostname": "server-01", "timestamp": datetime.utcnow().isoformat() + "Z", "metrics": { "cpu_usage": 45.2, "memory_usage": 68.5, "disk_usage": 82.1 }, "tags": ["production"] } response = requests.post(url, headers=headers, json=data) print(response.json())

JavaScript/Node.js

const fetch = require('node-fetch'); const submitDiagnostics = async () => { const response = await fetch( 'https://your.domain/api/v1/submit', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ hostname: 'server-01', timestamp: new Date().toISOString(), metrics: { cpu_usage: 45.2, memory_usage: 68.5, disk_usage: 82.1 }, tags: ['production'] }) } ); const data = await response.json(); console.log(data); }; submitDiagnostics();

Bash/cURL

#!/bin/bash API_TOKEN="YOUR_TOKEN" HOSTNAME=$(hostname) TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ") curl -X POST https://your.domain/api/v1/submit \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d "{ \"hostname\": \"$HOSTNAME\", \"timestamp\": \"$TIMESTAMP\", \"metrics\": { \"cpu_usage\": 45.2, \"memory_usage\": 68.5, \"disk_usage\": 82.1 }, \"tags\": [\"production\"] }"

Support

For assistance with the API: