Skip to content
FirstSIDocs

Integration examples

Ready-to-adapt examples in PowerShell, Python and curl: ticketing, monitoring, remote diagnostics.

In these examples, FIRSTSI_TOKEN holds the token and https://console.example.com stands for your console's address. Put in your own values.

PowerShell: offline computers

Offline computers (read:machines)
$headers = @{ Authorization = "Bearer $env:FIRSTSI_TOKEN" }
$url = "https://console.example.com/api/v1/machines?status=offline&limit=500"
$r = Invoke-RestMethod -Uri $url -Headers $headers
$r.data | Select-Object hostname, ip, agent_version, last_seen_at | Format-Table

Python: read a list to the end

Walk through a paginated list (read:flows)
import os, requests

BASE = "https://console.example.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['FIRSTSI_TOKEN']}"}

def read_all(route, **filters):
    cursor = None
    while True:
        params = dict(filters, **({"cursor": cursor} if cursor else {}))
        r = requests.get(f"{BASE}{route}", headers=HEADERS, params=params, timeout=60)
        r.raise_for_status()
        body = r.json()
        yield from body["data"]
        cursor = body["meta"].get("next_cursor")
        if not cursor:
            break

for flow in read_all("/flows", machine="pc-009", period="24h", limit=500):
    print(flow)

Ticketing tool: show a computer's network state

When a ticket mentions a computer, your tool can fetch its NetDiag summary (scope read:netdiag):

NetDiag summary of a computer over 24 h
curl -s "https://console.example.com/api/v1/netdiag/machines/pc-009/summary?period=24h" \
  -H "Authorization: Bearer $FIRSTSI_TOKEN"

The response gives the breakdown of verdicts (OK, PC, LAN, INFRA, WAN, DNS, SERVICE), the main causes and the latest measurement. Often that is enough to answer "it's the Wi-Fi" or "it's the server" without opening the console.

Monitoring: open alerts

Open alerts (read:alerts)
curl -s "https://console.example.com/api/v1/alerts" -H "Authorization: Bearer $FIRSTSI_TOKEN"

To acknowledge an alert from your tool (scope write:alerts), send a note:

Acknowledge an alert (write:alerts)
curl -s -X POST "https://console.example.com/api/v1/alerts/hm-128/ack" \
  -H "Authorization: Bearer $FIRSTSI_TOKEN" -H "Content-Type: application/json" \
  -d '{"note":"Taken by on-call, ticket #1234"}'

An alert's identifier starts with its origin: hm-… for availability, siem-… for the SIEM. NetDiag alerts (nd-…) cannot be acknowledged; they close on their own when the computer recovers.

Run a diagnostic on a computer

With the write:netdiag scope, you can request a traceroute, a speed test or a network capture. The result shows up a few moments later in the computer's events.

Traceroute from a computer (write:netdiag)
curl -s -X POST "https://console.example.com/api/v1/netdiag/machines/pc-009/actions" \
  -H "Authorization: Bearer $FIRSTSI_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"trace","target":"srv-app-01.example.local"}'
actionEffect
traceTraceroute to target (host name or address; without target, to the gateway)
speedSpeed test against the FirstSI server (20 MB down, 8 MB up)
captureNetwork capture lasting seconds seconds (5 to 120, 30 by default), viewable in FirstSI

Every write is logged, with its body, in the Public API screen.

Source: · FirstSI Docs · updated 2026-10-10