> ## 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.
# Aggiorna Monitor
> Aggiorna frequenza, metadati, notifica e/o webhook. Le modifiche alla frequenza ricreano il programma. Restituisce 409 mentre lo stato è in provisioning.
**Semantica di fusione:** Gli aggiornamenti dei metadati seguono l'approccio di Stripe — le nuove chiavi vengono aggiunte, le chiavi esistenti vengono aggiornate e le chiavi impostate su stringa vuota `""` vengono eliminate.
## OpenAPI
````yaml it/openapi/monitors.json POST /v1/monitors/{monitor_id}
openapi: 3.0.3
info:
title: API dei Monitor
version: 1.0.0
servers:
- url: https://api.olostep.com
security: []
paths:
/v1/monitors/{monitor_id}:
post:
summary: Aggiorna Monitor
description: >-
Aggiorna `frequency`, `metadata`, `notification`, e/o `webhook`. Le
modifiche alla frequenza eliminano e ricreano il programma sottostante.
Imposta `webhook` su `null` per rimuoverlo. Restituisce `409` mentre
`status` è `provisioning`.
parameters:
- name: monitor_id
in: path
required: true
schema:
type: string
pattern: ^monitor_
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
frequency:
type: string
description: >-
Testo del programma in linguaggio naturale. Ricrea il
programma interno.
metadata:
type: object
additionalProperties: true
description: >-
Fuso con i metadata esistenti; i valori di stringa vuota
eliminano le chiavi.
notification:
$ref: '#/components/schemas/MonitorNotification'
webhook:
allOf:
- $ref: '#/components/schemas/MonitorWebhook'
nullable: true
description: Passa `null` per rimuovere il webhook.
responses:
'200':
description: Monitor aggiornato.
content:
application/json:
schema:
$ref: '#/components/schemas/Monitor'
'400':
description: Richiesta non valida o monitor eliminato.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Chiave API non valida.
'404':
description: Monitor non trovato.
'409':
description: Il monitor è ancora in fase di provisioning.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Errore interno del server.
security:
- Authorization: []
components:
schemas:
MonitorNotification:
type: object
properties:
events:
type: array
items:
type: string
enum:
- changed
- first_snapshot
description: >-
Quando notificare. `changed` — consegna quando viene rilevato un
cambiamento rispetto allo snapshot precedente. `first_snapshot` —
consegna quando viene preso il primo snapshot di riferimento.
Predefinito a entrambi quando `channels` non è vuoto e `events` è
vuoto.
channels:
type: array
items:
$ref: '#/components/schemas/NotificationChannel'
description: >-
Destinatari di consegna via Email, Slack, o SMS. Risolti a runtime
dalla pipeline del monitor.
MonitorWebhook:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: >-
URL HTTP/HTTPS che riceve i payload del monitor (separato da
`notification.channels`).
Monitor:
type: object
properties:
id:
type: string
description: Identificatore unico del monitor (`monitor_…`).
object:
type: string
example: monitor
query:
type: string
description: Intento di monitoraggio in linguaggio naturale.
tracked:
$ref: '#/components/schemas/MonitorTracked'
source_policy:
$ref: '#/components/schemas/MonitorSourcePolicy'
schedule:
$ref: '#/components/schemas/MonitorSchedule'
notification:
$ref: '#/components/schemas/MonitorNotification'
webhook:
allOf:
- $ref: '#/components/schemas/MonitorWebhook'
nullable: true
output_schema:
type: object
additionalProperties: true
nullable: true
description: Schema JSON opzionale per l'output di estrazione strutturata.
status:
type: string
enum:
- provisioning
- active
- paused
- failed
- deleted
description: Monitora lo stato del ciclo di vita.
error_message:
type: string
nullable: true
description: Presente quando `status` è `failed`.
last_run:
allOf:
- $ref: '#/components/schemas/MonitorLastRun'
nullable: true
description: >-
Riepilogo dell'istantanea più recente. Incluso su `GET
/v1/monitors/{monitor_id}`.
agent:
$ref: '#/components/schemas/MonitorAgent'
metadata:
type: object
additionalProperties: true
created:
type: integer
description: Timestamp Unix (secondi).
updated:
type: integer
description: Timestamp Unix (secondi).
total_count:
type: integer
description: >-
Conteggio totale delle istantanee. Incluso su `GET
/v1/monitors/{monitor_id}` a meno che `include_total_count=false`.
mermaid_diagram:
type: string
description: >-
Diagramma di flusso Mermaid del DAG del monitor. Incluso quando
`include-diagram=true` su get.
ErrorResponse:
type: object
properties:
error:
type: string
monitor_id:
type: string
description: Presente su alcune risposte di errore di creazione/aggiornamento.
NotificationChannel:
type: object
required:
- type
- target
properties:
type:
type: string
enum:
- email
- slack
- sms
description: Tipo di canale di consegna.
target:
type: string
description: >-
Indirizzo email, URL webhook di Slack, o numero di telefono E.164
(per SMS).
events:
type: array
items:
type: string
enum:
- changed
- first_snapshot
description: >-
Filtro eventi opzionale per canale. Quando omesso, la consegna del
canale segue `notification.events` a livello superiore (o i valori
predefiniti quando i canali sono impostati).
MonitorTracked:
type: object
description: >-
Target risolti che il monitor traccia dopo che la pianificazione è
completata.
properties:
type:
type: string
nullable: true
description: Tipo di superficie tracciata (ad esempio `url` o `web_query`).
urls:
type: array
items:
type: string
format: uri
description: URL concreti monitorati.
web_query:
type: string
nullable: true
description: >-
Query di ricerca web utilizzata quando il monitor traccia un set di
risultati dinamico.
MonitorSourcePolicy:
type: object
description: >-
Liste di permessi e negazioni opzionali di URL/domini applicate durante
la pianificazione e l'esecuzione.
properties:
include_urls:
type: array
items:
type: string
format: uri
exclude_urls:
type: array
items:
type: string
format: uri
include_domains:
type: array
items:
type: string
exclude_domains:
type: array
items:
type: string
MonitorSchedule:
type: object
properties:
frequency:
type: string
nullable: true
description: >-
Testo di pianificazione in linguaggio naturale (ad esempio `ogni
ora`).
cron:
type: string
nullable: true
description: Espressione Cron derivata da `frequency`.
timezone:
type: string
example: UTC
description: >-
Fuso orario della pianificazione. Attualmente `UTC` per le
pianificazioni dei monitor.
next_run_at:
type: string
format: date-time
nullable: true
description: >-
Prossima esecuzione pianificata (ISO 8601). `null` quando il monitor
non è `active`.
MonitorLastRun:
type: object
properties:
id:
type: string
nullable: true
description: ID di esecuzione dell'ultimo snapshot (`run_…`).
status:
type: string
example: completed
change_detected:
type: boolean
nullable: true
ran_at:
type: string
format: date-time
nullable: true
MonitorAgent:
type: object
properties:
id:
type: string
nullable: true
description: ID agente ombra interno utilizzato per eseguire il DAG del monitor.
securitySchemes:
Authorization:
type: http
scheme: bearer
description: >-
Intestazione di autenticazione Bearer del tipo Bearer , dove
è il tuo token di autenticazione.
````