# Sys Monitor External API Guide

This guide documents the hosted Rust RS Server API surface for external clients that use a user API Key.

## Base URL

```text
https://serverstatus-rs.myfastools.com
```

Worker is only kept as a sanitized open-source reference package. Hosted production API calls should use the Rust RS Server base URL above.

## Authentication

Use the user API Key from the Dashboard:

```text
Authorization: Bearer YOUR_API_KEY
```

The user API Key is not a full administrator credential. It is designed for agent bootstrap, telemetry ingest, read-only inventory, read-only MCP, and bounded low-risk host metadata edits.

## Quick Checks

```bash
curl -sS "https://serverstatus-rs.myfastools.com/version"

curl -sS "https://serverstatus-rs.myfastools.com/api/v1/me/agents?view=summary" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Allowed With User API Key

### Agent ingest

- `POST /api/v1/report`
- `POST /api/v1/reports/batch`

The first accepted report registers the host under the GitHub user that owns the API Key. RS Server can then issue a machine-bound `agent_token` so migrated hosts continue reporting even after an old user API Key is revoked.

### Read-only host APIs

- `GET /api/v1/me/agents?view=summary`
- `GET /api/v1/agents`
- `GET /api/v1/agents/{id}`
- `GET /api/v1/agents/{id}/history`
- `GET /api/v1/agents/{id}/web-hosts/probe`
- `GET /api/v1/agents/ping-topology`
- `GET /api/v1/agents/traceroute`
- `GET /api/v1/reports`
- `GET /api/v1/stats`
- `GET /api/v1/releases/current`
- `GET /api/v1/commands`
- `GET /api/v1/commands/{agent_id}`
- `GET /api/v1/upgrades`
- `GET /api/v1/upgrades/{id}`

All user-scoped reads are filtered to hosts owned by the API Key owner.

### Low-risk host metadata

- `PUT /api/v1/agents/{id}/metadata`

Writable fields:

- `display_name`
- `group_name`
- `provider`
- `notes`
- `tags`

Bounds:

- `display_name`, `group_name`, and `provider`: 120 chars each.
- `notes`: 2000 chars.
- `tags`: up to 20 items, 64 chars each.

### MCP read-only tools

- `POST /mcp`

Current tools:

- `list_hosts`
- `search_hosts`
- `get_host_detail`
- `get_web_hosts`
- `get_security_posture`

Example:

```bash
curl -sS "https://serverstatus-rs.myfastools.com/mcp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Not Allowed With User API Key Alone

These operations require a logged-in browser session with recent browser reauth:

- command dispatch
- command deletion
- node task dispatch
- bulk upgrades
- API Key rotation or revocation
- global settings writes

Do not build external automation by expanding normal user API Key privileges. If write automation is needed later, use a scoped automation token with explicit capability bits, expiry, revocation, preview/confirm, and audit logging.

## Token Lifecycle

- User API Key: owned by a GitHub user; used for install, first report, read-only APIs, MCP, and bounded host metadata.
- Rotating key: old machines can keep reporting while migration finishes.
- Revoked key: blocked for future user API Key use.
- Machine `agent_token`: bound to one `agent_id`; used by migrated agents for report, TCP, command-channel polling, ping peers, and realtime paths.

This lifecycle lets a user replace a leaked API Key without breaking machines that already migrated to their machine token.