> ## 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. # Crea Monitor > Crea un monitor da una query in linguaggio naturale. Fornisce un agente ombra, genera una specifica del workflow, mette in coda la pianificazione del DAG e programma esecuzioni ricorrenti. Configura la consegna con notification.channels e/o webhook. Restituisce 202 con stato provisioning, o trasmette i progressi con ?stream=1. ## OpenAPI ````yaml it/openapi/monitors.json POST /v1/monitors openapi: 3.0.3 info: title: API dei Monitor version: 1.0.0 servers: - url: https://api.olostep.com security: [] paths: /v1/monitors: post: summary: Crea Monitor description: >- Crea un monitor da una `query` in linguaggio naturale, fornisce un agente interno e un programma, genera una specifica del flusso di lavoro e mette in coda la pianificazione del DAG. Restituisce HTTP `202` con `status: provisioning` quando la richiesta si completa senza streaming. Passa `?stream=1` o `Accept: text/event-stream` per ricevere Eventi Inviati dal Server per le fasi di provisioning e i token di ragionamento della specifica. Il monitor diventa `active` dopo che la pianificazione risolve i target tracciati. parameters: - name: stream in: query required: false schema: type: string enum: - '1' - 'true' description: >- Quando impostato, la risposta è `text/event-stream` con eventi `phase`, `reasoning_token`, `complete` e `error`. requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string description: Cosa monitorare, in linguaggio naturale. source_policy: $ref: '#/components/schemas/MonitorSourcePolicy' frequency: type: string maxLength: 50 default: every hour description: >- Programma in linguaggio naturale (ad esempio `ogni giorno alle 9am`). L'intervallo minimo è ogni 10 minuti. I programmi usano UTC. notification: $ref: '#/components/schemas/MonitorNotification' webhook: $ref: '#/components/schemas/MonitorWebhook' metadata: type: object additionalProperties: true output_schema: type: object additionalProperties: true description: Schema JSON per l'output di estrazione strutturata. responses: '200': description: >- Stream di provisioning (`text/event-stream`) quando `stream=1`. Termina con un evento `complete` contenente l'oggetto monitor. content: text/event-stream: schema: type: string '202': description: Monitor accettato; provisioning avviato (non in streaming). content: application/json: schema: $ref: '#/components/schemas/Monitor' '400': description: >- Richiesta non valida (query, frequency, source_policy, notification, webhook, metadata, o output_schema). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Chiave API non valida. '500': description: Errore interno del server durante la creazione del monitor. '503': description: Agente master FDA non disponibile durante il provisioning. security: - Authorization: [] components: schemas: 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 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. 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. ````