Skip to content
Ishvana Ishvana Docs

Start Monitoring

POST
/api/agents/monitor/start

Start monitoring a URL for content changes.

Validates the URL (SSRF guard), persists the monitor record to SQLite, then registers the URL with Lagan’s in-memory web_monitor. SQLite is written first — if Lagan registration fails the row is rolled back so we never report success when the URL was never actually registered.

Args: request: MonitoringStartRequest with URL and monitoring config.

Returns: MonitoringStartResponse with monitor_id, status, and next_check_at.

Raises: HTTPException 400: No active project set, or URL rejected by the outbound URL validator. HTTPException 503: Lagan agent or its web_monitor tool unavailable.

Request Body required

Section titled “Request Body required ”
MonitoringStartRequest

Request to start monitoring a URL for changes.

Initiates continuous monitoring of a webpage for content changes with configurable check intervals and change detection thresholds.

Fields:

  • url: URL to monitor for changes (required, must be valid HTTP/HTTPS)
  • interval_minutes: Check interval in minutes (5-1440, default 60)
  • change_threshold: Content change threshold percentage (0.0-1.0, default 0.1)
  • notify_on_change: Whether to send notifications on content changes

Constraints:

  • Minimum interval: 5 minutes (to prevent excessive requests)
  • Maximum interval: 1440 minutes (24 hours)
  • Change threshold: 0.1 = 10% content change triggers notification

Usage: Used to initiate web monitoring operations for change detection.

Integration:

  • MonitoringRoutes: Request validation for /monitoring/start endpoint
  • MonitoringService: Change detection configuration
  • Notification System: Change notification triggers
object
url
required
Url

URL to monitor for changes

string format: uri
>= 1 characters <= 2083 characters
intervalMinutes
Intervalminutes

Check interval in minutes (5-1440)

integer
default: 60 >= 5 <= 1440
changeThreshold
Changethreshold

Content change threshold (0.0-1.0, 0.1 = 10% change)

number
default: 0.1 <= 1
notifyOnChange
Notifyonchange

Whether to send notifications on content changes

boolean
default: true

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

MonitoringStartResponse

Response after starting a monitoring operation.

Confirms monitoring operation initiation with assigned monitor ID and scheduling information.

Fields:

  • success: Whether monitoring started successfully
  • monitor_id: Unique identifier for this monitoring operation
  • url: URL being monitored
  • interval_minutes: Configured check interval in minutes
  • status: Current monitor status (active, initializing, error)
  • next_check_at: ISO timestamp of next scheduled check
  • message: Human-readable status message

Status Values:

  • active: Monitor is running and scheduled
  • initializing: Monitor is starting up
  • error: Monitor failed to start

Usage: Returned after successfully starting a monitoring operation.

Integration:

  • MonitoringRoutes: Response model for /monitoring/start endpoint
  • Frontend: Monitor status display
object
success
required
Success

Whether monitoring started successfully

boolean
monitorId
required
Monitorid

Unique identifier for this monitoring operation

string
url
required
Url

URL being monitored

string
intervalMinutes
required
Intervalminutes

Check interval in minutes

integer
>= 5
status
required
Status

Monitor status

string
Allowed values: active initializing error
nextCheckAt
Any of:
string
message
required
Message

Status message

string

422

Section titled “422 ”

Validation Error

HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object