> For the complete documentation index, see [llms.txt](https://docs.visualsentinel.com/llms.txt)

# 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](https://docs.visualsentinel.com/guides/authentication.md). Most error responses use the [ErrorResponse](https://docs.visualsentinel.com/reference/models/error-response.md) shape, see [Errors](https://docs.visualsentinel.com/guides/errors.md) and [Rate limits](https://docs.visualsentinel.com/guides/rate-limits.md).

## Endpoints

- [List servers](#list-servers): `GET /api/servers`
- [Create server](#create-server): `POST /api/servers`
- [Get server details](#get-server): `GET /api/servers/{id}`
- [Update server](#update-server): `PATCH /api/servers/{id}`
- [Delete server](#delete-server): `DELETE /api/servers/{id}`
- [Get server metrics](#get-server-metrics): `GET /api/servers/{id}/metrics`
- [Get agent install script](#get-agent-install-script): `GET /api/servers/agent/install.sh`
- [Agent metrics report](#agent-report): `POST /api/servers/agent/report`

## List servers

`GET /api/servers`

Get all servers for the organization.

**Responses**

- `200`: List of servers. Body: [ServerListResponse](https://docs.visualsentinel.com/reference/models/server-list-response.md).
- `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](https://docs.visualsentinel.com/reference/models/server.md) | 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](https://docs.visualsentinel.com/reference/models/server.md) | 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](https://docs.visualsentinel.com/reference/models/server-metrics-response.md).
- `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](https://docs.visualsentinel.com/reference/models/server-list-response.md), [Server](https://docs.visualsentinel.com/reference/models/server.md), [ServerMetricsResponse](https://docs.visualsentinel.com/reference/models/server-metrics-response.md).

Generated from the OpenAPI 3.1 specification at [https://docs.visualsentinel.com/openapi.json](https://docs.visualsentinel.com/openapi.json), the same file the interactive reference reads.