Servers API
Server infrastructure monitoring via agent. This page lists all 8 endpoints in the Servers area of the Visual Sentinel REST API.
Base URL: https://visualsentinel.com. Unless an endpoint says otherwise it accepts an API key or a session cookie, see Authentication. Most error responses use the ErrorResponse shape, see Errors and Rate limits.
Endpoints
- List servers:
GET /api/servers - Create server:
POST /api/servers - Get server details:
GET /api/servers/{id} - Update server:
PATCH /api/servers/{id} - Delete server:
DELETE /api/servers/{id} - Get server metrics:
GET /api/servers/{id}/metrics - Get agent install script:
GET /api/servers/agent/install.sh - Agent metrics report:
POST /api/servers/agent/report
List servers
GET /api/servers
Get all servers for the organization.
Responses
200: List of servers. Body: ServerListResponse.401: Not authenticated.403: Server monitoring not available on current plan or missing servers:read scope.
Create server
POST /api/servers
Register a new server for monitoring. Returns the server token for agent installation.
Request body (required): object.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Min length 1, max length 100. |
hostname | string | No | |
ipAddress | string | No | |
tags | array of string | No |
Responses
201: Server created. Body: object.402: Server limit reached.
| Field | Type | Required | Description |
|---|---|---|---|
server | Server | No | |
token | string | No | Agent authentication token (shown only once) |
Get server details
GET /api/servers/{id}
Get detailed information about a specific server including recent metrics and top processes.
Parameters
id(path, string (uuid), required)
Responses
200: Server details. Body: object.404: Server not found.
| Field | Type | Required | Description |
|---|---|---|---|
server | Server | No |
Update server
PATCH /api/servers/{id}
Update server name, tags, or alert configuration.
Parameters
id(path, string (uuid), required)
Request body (required): object.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | |
tags | array of string | No | |
alertConfig | object | No |
Responses
200: Server updated.
Delete server
DELETE /api/servers/{id}
Remove a server and all its monitoring data.
Parameters
id(path, string (uuid), required)
Responses
200: Server deleted.
Get server metrics
GET /api/servers/{id}/metrics
Get historical server metrics (CPU, memory, disk, network) with configurable time periods.
Parameters
id(path, string (uuid), required)period(query, string, optional): One of:1h,6h,24h,7d,30d. Default:1h.
Responses
200: Server metrics. Body: ServerMetricsResponse.404: Server not found.
Get agent install script
GET /api/servers/agent/install.sh
Download the server monitoring agent installation shell script.
Authentication: no session or API key needed.
Parameters
token(query, string, required)
Responses
200: Shell script. Body: string (text/x-shellscript).
Agent metrics report
POST /api/servers/agent/report
Endpoint for the server agent to submit metrics data. Authenticated via server token.
Authentication: no session or API key needed.
Request body (required): object.
| Field | Type | Required | Description |
|---|---|---|---|
token | string | No | |
cpu | object | No | |
memory | object | No | |
disk | object | No | |
network | object | No | |
processes | array of object | No | Top processes, at most 50. Max items 50. |
processes[].pid | integer | No | Minimum 0. |
processes[].name | string | No | |
processes[].command | string | No | |
processes[].cpuPercent | number | No | |
processes[].memoryPercent | number | No | |
processes[].memoryBytes | number | No | |
processes[].status | string | No | |
processes[].user | string | No |
Responses
200: Metrics recorded.401: Invalid server token.
Data models
Request and response shapes these endpoints use: ServerListResponse, Server, ServerMetricsResponse.
Generated from the OpenAPI 3.1 specification at https://docs.visualsentinel.com/openapi.json, the same file the interactive reference reads.