title: "Processes API" description: "Manage watched processes per server — list, create, update, delete, view samples." last_updated: "2026-05-24"

Processes API

Watched processes are nested under their parent server. The agent polls pgrep/ps for each name and reports counts, CPU, and memory. Conceptual docs: Process monitoring.

All routes below require a bearer token.

List processes for a server

GET/servers/:id/processes

Auth: bearer

Returns all watched processes attached to the given server, with computed status.

Response — 200 OK

{
  "processes": [
    {
      "id": 18,
      "server_id": 12,
      "user_id": 3,
      "process_name": "nginx",
      "enabled": 1,
      "alert_on_down": 1,
      "alert_on_restart": 0,
      "alert_on_cpu": 1,
      "alert_on_memory": 1,
      "cpu_threshold_pct": 80,
      "memory_threshold_pct": 75,
      "last_count": 4,
      "last_cpu_pct": 12.4,
      "last_memory_pct": 8.1,
      "last_sample_at": "2026-05-24T18:41:00Z",
      "alerted_state": null,
      "status": "up"
    }
  ],
  "plan_limit": 10,
  "current_count": 1,
  "plan": "pro",
  "server": { "id": 12, "hostname": "web-01.prod", "last_agent_version": "2.4.1" }
}

status is computed: paused (disabled), pending (no sample yet), down (last_count = 0), alerting (running but currently alerting), up otherwise.

Errors

404 — server_not_found.

Create process

POST/servers/:id/processes

Auth: bearer

Request body

Field	Type	Required	Notes
`process_name`	string	yes	1-100 chars. No whitespace, newlines, or shell metacharacters — the characters `;`, `&`, `$`, backtick, backslash, `"`, `'`, `<`, `>`, `(`, `)`, `{`, `}`, and pipe are rejected.
`enabled`	boolean	no	Default `true`.
`alert_on_down`	boolean	no	Default `true`.
`alert_on_restart`	boolean	no	Default `false`.
`alert_on_cpu`	boolean	no	Default `false`.
`alert_on_memory`	boolean	no	Default `false`.
`cpu_threshold_pct`	number	no	`0.01`-`100`. Default `50`.
`memory_threshold_pct`	number	no	`0.01`-`100`. Default `25`.

{
  "process_name": "nginx",
  "alert_on_cpu": true,
  "cpu_threshold_pct": 80,
  "alert_on_memory": true,
  "memory_threshold_pct": 75
}

Response — 201 Created

{
  "process": {
    "id": 18,
    "server_id": 12,
    "process_name": "nginx",
    "enabled": 1,
    "status": "pending"
  }
}

Errors

400 — validation_failed with issues (e.g. process_name contains shell metacharacters).
402 — plan_limit_reached. Process limits are per-server (scope: "per_server" in the body).
404 — server_not_found.
409 — duplicate_process (a watched process with that name already exists on this server).

Get process

GET/servers/:id/processes/:procId

Auth: bearer

Returns the watched process, its last 100 samples, total sample count, and a count of restarts detected in the last 24 hours.

Response — 200 OK

{
  "process": {
    "id": 18,
    "process_name": "nginx",
    "status": "up",
    "last_count": 4
  },
  "samples": [
    {
      "id": 9912,
      "watched_process_id": 18,
      "count": 4,
      "cpu_pct": 12.4,
      "memory_pct": 8.1,
      "oldest_start_unix": 1716566400,
      "recorded_at": "2026-05-24T18:41:00Z"
    }
  ],
  "samples_total": 8640,
  "recent_restarts": 0
}

A restart is counted when oldest_start_unix increases between consecutive samples (within 24h).

Errors

404 — server_not_found or not_found.

Update process

PUT/servers/:id/processes/:procId

Auth: bearer

Updatable: process_name, enabled, alert_on_down, alert_on_restart, alert_on_cpu, alert_on_memory, cpu_threshold_pct, memory_threshold_pct. Same validation as create.

Response — 200 OK

{ "process": { "id": 18, "process_name": "nginx", "cpu_threshold_pct": 90, "status": "up" } }

Errors

400 — validation_failed, or no updatable fields provided.
404 — server_not_found or not_found.
409 — duplicate_process (renamed to a name already in use on this server).

Delete process

DELETE/servers/:id/processes/:procId

Auth: bearer

Response — 200 OK

{ "ok": true }

Errors

404 — server_not_found or not_found.