> ## 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.
# Update Monitor
> Updates frequency, metadata, notification, and/or webhook. Frequency changes recreate the schedule. Returns 409 while status is provisioning.
**Merge semantics:** Metadata updates follow Stripe's approach — new keys are added, existing keys are updated, and keys set to empty string `""` are deleted.
## OpenAPI
````yaml openapi/monitors.json POST /v1/monitors/{monitor_id}
openapi: 3.0.3
info:
title: Monitors API
version: 1.0.0
servers:
- url: https://api.olostep.com
security: []
paths:
/v1/monitors/{monitor_id}:
post:
summary: Update Monitor
description: >-
Updates `frequency`, `metadata`, `notification`, and/or `webhook`.
Frequency changes delete and recreate the underlying schedule. Set
`webhook` to `null` to remove it. Returns `409` while `status` is
`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: >-
Natural-language schedule text. Recreates the internal
schedule.
metadata:
type: object
additionalProperties: true
description: >-
Merged with existing metadata; empty string values delete
keys.
notification:
$ref: '#/components/schemas/MonitorNotification'
webhook:
allOf:
- $ref: '#/components/schemas/MonitorWebhook'
nullable: true
description: Pass `null` to remove the webhook.
responses:
'200':
description: Monitor updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Monitor'
'400':
description: Invalid request or monitor deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Invalid API key.
'404':
description: Monitor not found.
'409':
description: Monitor is still provisioning.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error.
security:
- Authorization: []
components:
schemas:
MonitorNotification:
type: object
properties:
events:
type: array
items:
type: string
enum:
- changed
- first_snapshot
description: >-
When to notify. `changed` — deliver when a change is detected vs.
the previous snapshot. `first_snapshot` — deliver when the first
baseline snapshot is taken. Defaults to both when `channels` is
non-empty and `events` is empty.
channels:
type: array
items:
$ref: '#/components/schemas/NotificationChannel'
description: >-
Email, Slack, or SMS delivery targets. Resolved at runtime by the
monitor pipeline.
MonitorWebhook:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: >-
HTTP/HTTPS URL that receives monitor payloads (separate from
`notification.channels`).
Monitor:
type: object
properties:
id:
type: string
description: Unique monitor identifier (`monitor_…`).
object:
type: string
example: monitor
query:
type: string
description: Monitoring intent in natural language.
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: Optional JSON Schema for structured extraction output.
status:
type: string
enum:
- provisioning
- active
- paused
- failed
- deleted
description: Monitor lifecycle status.
error_message:
type: string
nullable: true
description: Present when `status` is `failed`.
last_run:
allOf:
- $ref: '#/components/schemas/MonitorLastRun'
nullable: true
description: >-
Latest snapshot summary. Included on `GET
/v1/monitors/{monitor_id}`.
agent:
$ref: '#/components/schemas/MonitorAgent'
metadata:
type: object
additionalProperties: true
created:
type: integer
description: Unix timestamp (seconds).
updated:
type: integer
description: Unix timestamp (seconds).
total_count:
type: integer
description: >-
Total snapshot count. Included on `GET /v1/monitors/{monitor_id}`
unless `include_total_count=false`.
mermaid_diagram:
type: string
description: >-
Mermaid flowchart of the monitor DAG. Included when
`include-diagram=true` on get.
ErrorResponse:
type: object
properties:
error:
type: string
monitor_id:
type: string
description: Present on some create/update error responses.
NotificationChannel:
type: object
required:
- type
- target
properties:
type:
type: string
enum:
- email
- slack
- sms
description: Delivery channel type.
target:
type: string
description: Email address, Slack webhook URL, or E.164 phone number (for SMS).
events:
type: array
items:
type: string
enum:
- changed
- first_snapshot
description: >-
Optional per-channel event filter. When omitted, channel delivery
follows top-level `notification.events` (or defaults when channels
are set).
MonitorTracked:
type: object
description: Resolved targets the monitor tracks after planning completes.
properties:
type:
type: string
nullable: true
description: Tracked surface type (for example `url` or `web_query`).
urls:
type: array
items:
type: string
format: uri
description: Concrete URLs being monitored.
web_query:
type: string
nullable: true
description: Web search query used when the monitor tracks a dynamic result set.
MonitorSourcePolicy:
type: object
description: >-
Optional URL/domain allow and deny lists applied during planning and
execution.
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: Natural-language schedule text (for example `every hour`).
cron:
type: string
nullable: true
description: Cron expression derived from `frequency`.
timezone:
type: string
example: UTC
description: Schedule timezone. Currently `UTC` for monitor schedules.
next_run_at:
type: string
format: date-time
nullable: true
description: >-
Next scheduled run (ISO 8601). `null` when the monitor is not
`active`.
MonitorLastRun:
type: object
properties:
id:
type: string
nullable: true
description: Run ID of the latest 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: Internal shadow agent ID used to execute the monitor DAG.
securitySchemes:
Authorization:
type: http
scheme: bearer
description: >-
Bearer authentication header of the form Bearer , where
is your auth token.
````