Managing Servers and Groups via the API

The Server Scout API provides comprehensive endpoints for managing your server fleet programmatically. Whether you're automating server provisioning, cleaning up decommissioned systems, or maintaining an inventory, the API enables efficient bulk operations and seamless integration with your existing workflows.

Authentication and Permissions

All management operations require proper authentication using your API key. Most server operations require server owner permissions, whilst user management functions need admin role access. Include your API key in the Authorization header:

Authorization: Bearer your-api-key-here

Listing Servers

Retrieve all servers in your account with their current status, group assignments, and metadata:

GET /api/v1/servers

The response includes each server's display name, hostname, online status, group assignment, last check-in time, and basic system information. This endpoint supports pagination for large server fleets and serves as the foundation for bulk operations.

Adding Servers

Create a new server entry and receive the installation command:

POST /api/v1/servers
Content-Type: application/json

{
  "display_name": "Web Server 01",
  "hostname": "web01.example.com",
  "group_id": 123
}

The response includes the unique server ID, API key for the agent, and the complete installation command ready to execute on your target server. This enables automated provisioning workflows where servers are added to monitoring as part of your deployment pipeline.

Editing Server Details

Update server information including display names, hostnames, and group assignments:

PUT /api/v1/servers/{server_id}
Content-Type: application/json

{
  "display_name": "Production Web Server 01",
  "hostname": "prod-web01.example.com",
  "group_id": 456
}

Changes take effect immediately in the dashboard and don't require agent reconfiguration for display name or group changes.

Deleting Servers

Permanently remove a server and all associated metric history:

DELETE /api/v1/servers/{server_id}

Warning: This action is irreversible and removes all historical data. Consider pausing monitoring instead if you might restore the server later.

Managing Groups

Server groups help organise your fleet and apply bulk actions. Create new groups:

POST /api/v1/groups
Content-Type: application/json

{
  "name": "Production Servers",
  "description": "All production environment servers"
}

Rename existing groups:

PUT /api/v1/groups/{group_id}
Content-Type: application/json

{
  "name": "Production Web Servers"
}

Delete groups (servers are moved to the default group):

DELETE /api/v1/groups/{group_id}

Pausing and Resuming Monitoring

Control monitoring status without removing servers entirely:

PUT /api/v1/servers/{server_id}/status
Content-Type: application/json

{
  "status": "paused"
}

Use "active" to resume monitoring. Paused servers retain their configuration and historical data but don't generate alerts or collect new metrics.

Bulk Operations

Efficiently manage multiple servers by iterating through the server list endpoint. For example, to pause all servers in a specific group:

1. List all servers and filter by group ID
2. Iterate through the results
3. Update each server's status to paused

This approach works for bulk group reassignments, mass configuration updates, or fleet-wide status changes.

Practical Use Cases

Automated Provisioning: Integrate server creation into your deployment scripts. When spinning up new infrastructure, automatically add servers to Server Scout with appropriate group assignments and naming conventions.

Automated Cleanup: Remove decommissioned servers from monitoring as part of your infrastructure teardown process. This prevents false alerts and keeps your server list clean.

Fleet Reporting: Export server lists and current statuses for inventory management, compliance reporting, or capacity planning. The API provides structured data that integrates easily with reporting tools or spreadsheets.

Group Reorganisation: Bulk reassign servers between groups as your infrastructure evolves, perhaps moving servers between development, staging, and production groups as they progress through your pipeline.

The Server Scout API's management endpoints provide the flexibility to integrate monitoring seamlessly into your existing infrastructure automation, whether you're managing dozens or hundreds of servers.