Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.olostep.com/llms.txt

Use this file to discover all available pages before exploring further.

Attraverso l’endpoint /v1/monitors di Olostep puoi creare monitor persistenti che funzionano su un programma fisso, rilevano le modifiche delle pagine e ti notificano tramite email o webhook.
  • Crea un monitor da un query, un url, o entrambi
  • Esegui controlli ogni ora, giornalmente o settimanalmente
  • Invia avvisi a email o webhook_url
  • Elenca, ispeziona, aggiorna e elimina monitor
  • Leggi eventi snapshot del monitor da snapshot privati

​
Installazione

# pip install requests

import requests

​
Crea un monitor

Crea un monitor con POST /v1/monitors. L’endpoint convalida il tuo input, fornisce il monitor, crea il suo programma interno e restituisce un oggetto monitor attivo. È richiesto almeno uno tra query o url. È richiesto esattamente un target di notifica: o email o webhook_url.

​
Esempio di richiesta

import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"

payload = {
    "query": "Traccia le modifiche nei prezzi dei prodotti e nelle informazioni di stock",
    "url": "https://example.com/products/widget-pro",
    "frequency": "daily",
    "email": "alerts@example.com",
    "metadata": {
        "product_id": "widget-pro",
        "team": "growth"
    }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(f"{API_URL}/monitors", headers=headers, json=payload)
print(response.status_code)
print(json.dumps(response.json(), indent=2))

​
Risposta

La creazione del monitor avvenuta con successo restituisce HTTP 202 con un oggetto monitor: 
{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "status": "active",
  "schedule_id": "schedule_r4h9n2j7",
  "query": "Traccia le modifiche nei prezzi dei prodotti e nelle informazioni di stock",
  "url": "https://example.com/products/widget-pro",
  "frequency": "daily",
  "cron_expression": "0 0 * * ? *",
  "notification_channel": "email",
  "notification_target": "alerts@example.com",
  "metadata": {
    "product_id": "widget-pro",
    "team": "growth"
  },
  "created": 1745673871,
  "updated": 1745673871
}

​
Canali di notifica

I monitor supportano un canale per monitor:
  • email: imposta un campo email
  • webhook: imposta un campo webhook_url
Non puoi impostare entrambi in una richiesta.

​
Esempio di Webhook

{
  "query": "Osserva le modifiche nei termini legali",
  "url": "https://example.com/terms",
  "frequency": "weekly",
  "webhook_url": "https://hooks.example.com/olostep-monitor"
}

​
Frequenze

Le frequenze supportate per i monitor sono:
  • hourly
  • daily
  • weekly
L’API deriva automaticamente l’espressione cron del programma dalla frequenza selezionata.

​
Elenca i monitor

Recupera tutti i monitor per il tuo team con GET /v1/monitors. Per impostazione predefinita, i monitor eliminati sono filtrati. Usa ?include_deleted=true per includerli. 
import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

response = requests.get(f"{API_URL}/monitors", headers=headers)
result = response.json()
print(f"Total monitors: {result['count']}")
print(json.dumps(result, indent=2))

​
Ottieni un monitor

Recupera un singolo monitor con GET /v1/monitors/:monitor_id. 
import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
MONITOR_ID = "monitor_n8q2x4m1ak"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

response = requests.get(f"{API_URL}/monitors/{MONITOR_ID}", headers=headers)
print(json.dumps(response.json(), indent=2))

​
Elenca gli eventi del monitor

Usa GET /v1/monitors/:monitor_id/events per elencare gli eventi snapshot per un monitor. Questo endpoint supporta la paginazione:
  • limit (predefinito 25, massimo 100)
  • cursor (token di paginazione opaco da una risposta precedente)
Gli eventi sono restituiti dal più recente. Ogni elemento include un snapshot_url pre-firmato a breve termine in modo da poter recuperare in modo sicuro il contenuto dello snapshot privato.

​
Esempio

import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
MONITOR_ID = "monitor_n8q2x4m1ak"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

response = requests.get(
    f"{API_URL}/monitors/{MONITOR_ID}/events?limit=10",
    headers=headers
)
print(json.dumps(response.json(), indent=2))

​
Forma della risposta

{
  "data": [
    {
      "id": "run_v7k2p9m3",
      "run_id": "run_v7k2p9m3",
      "created": 1777960800,
      "changed": true,
      "summary": "Il prezzo è cambiato da $49 a $45 e lo stock è passato a bassa disponibilità.",
      "snapshot_url": "https://olostep-monitor-snapshot.s3.amazonaws.com/private/key?...signature..."
    }
  ],
  "has_more": false,
  "next_cursor": null
}
Se cursor è malformato, l’endpoint restituisce: 
{
  "error": "Invalid cursor."
}

​
Aggiorna un monitor

Aggiorna un monitor con POST /v1/monitors/:monitor_id. Aggiornamenti supportati:
  • metadata (unito con i metadati esistenti; passa valori di stringa vuoti per eliminare le chiavi)
  • frequency (hourly, daily, weekly)
Se aggiorni frequency, l’API ricrea internamente il programma del monitor.

​
Esempio di richiesta

import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
MONITOR_ID = "monitor_n8q2x4m1ak"

payload = {
    "frequency": "hourly",
    "metadata": {
        "owner": "ops-team",
        "deprecated_field": ""
    }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{API_URL}/monitors/{MONITOR_ID}",
    headers=headers,
    json=payload
)
print(json.dumps(response.json(), indent=2))

​
Elimina un monitor

Elimina un monitor con DELETE /v1/monitors/:monitor_id. L’eliminazione è soft per la riga del monitor (status diventa deleted) e rimuove anche le risorse di scheduling/agent-ombra interne legate a quel monitor. 
import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
MONITOR_ID = "monitor_n8q2x4m1ak"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

response = requests.delete(f"{API_URL}/monitors/{MONITOR_ID}", headers=headers)
print(json.dumps(response.json(), indent=2))

​
Errori comuni di validazione

Gli endpoint del monitor restituiscono errori di validazione chiari per richieste non valide comuni:
  • Mancano entrambi query e url
  • Mancanza di frequency, o valore di frequenza non supportato
  • Mancano entrambi email e webhook_url
  • Fornire entrambi email e webhook_url
  • Formato email non valido
  • URL webhook non valido (deve essere http o https)
  • Formato monitor_id non valido
Esempio di errore: 
{
  "error": "'frequency' deve essere uno di: hourly, daily, weekly."
}