Vai al contenuto
FirstSIDocs

Iniziare con l'API

Che cosa copre l'API pubblica, come chiamarla e com'è fatta una risposta.

#/api-tokensadmin (creazione dei token)

L'API pubblica apre i dati di FirstSI agli altri vostri strumenti: ticketing, supervisione generale, dashboard, script, assistenti IA. Copre tutti i moduli ed è in sola lettura, con tre eccezioni precise: riconoscere un avviso, regolare NetDiag e lanciare un'azione di diagnostica su una postazione.

L'essenziale

L'indirizzo di base è https://<vostra-console>/api/v1. Ogni chiamata porta un token del vostro cliente nell'intestazione Authorization: Bearer <token> (vedi Token API). Un token ha degli ambiti (read:netdiag, read:flows…); una rotta di cui manca l'ambito risponde 403.

Le risposte sono in JSON, nella forma { data, meta }, con le date in UTC nel formato ISO 8601. Ogni token ha diritto a 600 chiamate al minuto; oltre, il server risponde 429 con un'intestazione Retry-After.

Il contratto v1 evolve solo con aggiunte compatibili. Una rimozione viene annunciata con 12 mesi di anticipo.

La prima chiamata

La rotta /me serve a verificare un token: restituisce il nome, gli ambiti e la data di scadenza.

Verificare un token
curl -s https://console.esempio.it/api/v1/me \
  -H "Authorization: Bearer fsi_live_xxxxxxxxxxxx"

Poi, per esempio, l'elenco delle postazioni con l'agente (ambito read:machines):

Elencare le postazioni
curl -s "https://console.esempio.it/api/v1/machines?status=online&limit=50" \
  -H "Authorization: Bearer fsi_live_xxxxxxxxxxxx"
Risposta (estratto)
{
  "data": [
    { "id": 21, "hostname": "postazione-009", "ip": "10.20.0.9", "os": "Windows 11", "agent_version": "2026.10.7.0",
      "status": "online", "last_seen_at": "2026-10-07T08:12:40Z", "modules": ["netflow", "netdiag"] }
  ],
  "meta": { "limit": 50, "next_cursor": null }
}

Che cosa copre l'API

Ambito funzionaleEsempi di rotteAmbito del token
Parco/machines, /machines/{hostname}read:machines
Esperienza di rete delle postazioni/netdiag/machines, /netdiag/machines/{hostname}/summaryread:netdiag
Flussi di rete/flows, /flows/destinations, /flows/summary, /flows/exploreread:flows
Avvisi e disponibilità/alerts, /monitorsread:alerts, read:monitors
Inventario e vulnerabilità/inventory/…read:inventory
Sicurezza (SIEM, Active Directory)/security/…read:security
Database, DNS, file, rete, firewall/databases/…, /dns/…, /files/…, /network/…, /firewall/…l'ambito read:* corrispondente

Tutte le rotte con i relativi parametri sono nel riferimento dell'API. La console fornisce anche la specifica OpenAPI (/api/v1/openapi.json) e una documentazione interattiva (/api/v1/docs).

Per un assistente IA

Gli stessi dati esistono anche come strumenti MCP. Claude, ChatGPT, Copilot o qualunque client compatibile li chiamano da soli per rispondere a una domanda come «quale postazione ha avuto un problema di rete stamattina?». Vedi Server MCP.

Per approfondire

Fonte: · Docs FirstSI · aggiornato il 10/10/2026