> ## Documentation Index
> Fetch the complete documentation index at: https://docs.context.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Monitor
> Watch any page, sitemap, or extracted dataset for changes on a schedule, with signed webhooks when something changes.
0 Credits 1-10 Credits Per Run
Creating a monitor always triggers an immediate first run that captures the **baseline**: the snapshot every later run is compared against. Baseline runs perform no change detection and are billed like any other run.
## OpenAPI
````yaml POST /monitors
openapi: 3.0.0
info:
title: Context API
description: API for retrieving context data from any website
version: 1.0.0
servers:
- url: https://api.context.dev/v1
security: []
tags:
- name: Monitors
description: >-
Monitor pages, sitemaps, and extracted website data for exact or semantic
changes. The change.detected webhook payload is documented by the
MonitorsChangeDetectedWebhookPayload schema.
paths:
/monitors:
post:
tags:
- Monitors
summary: Create a monitor
description: >-
Creates a monitor. The request body is a union of the supported
target/change detection combinations. The monitor runs immediately after
creation to create its initial baseline.
operationId: createMonitor
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MonitorsCreateMonitorRequest'
examples:
page_exact:
summary: Exact page monitor
value:
mode: web
name: Acme pricing page
target:
type: page
url: https://acme.com/pricing
change_detection:
type: exact
schedule:
type: interval
frequency: 6
unit: hours
webhook:
url: https://example.com/webhook
sitemap_exact:
summary: Exact sitemap monitor
value:
mode: web
name: Acme sitemap
target:
type: sitemap
url: https://acme.com/sitemap.xml
change_detection:
type: exact
schedule:
type: interval
frequency: 1
unit: days
webhook:
url: https://example.com/webhook
extract_semantic:
summary: Semantic extract monitor
value:
mode: web
name: Acme website positioning
target:
type: extract
url: https://acme.com
instructions: >-
Extract the product positioning, pricing, packaging, and
headline feature claims.
max_pages: 10
change_detection:
type: semantic
schedule:
type: interval
frequency: 1
unit: days
webhook:
url: https://example.com/webhook
responses:
'201':
description: Monitor created
content:
application/json:
schema:
$ref: '#/components/schemas/MonitorsMonitor'
'400':
$ref: '#/components/responses/MonitorsBadRequest'
'401':
$ref: '#/components/responses/MonitorsUnauthorized'
'403':
$ref: '#/components/responses/MonitorsLimitExceeded'
security:
- bearerAuth: []
x-codeSamples:
- lang: JavaScript
source: |-
import ContextDev from 'context.dev';
const client = new ContextDev({
apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted
});
const monitor = await client.monitors.create({
change_detection: { type: 'exact' },
name: 'Acme pricing page',
schedule: {
type: 'interval',
frequency: 6,
unit: 'hours',
},
target: { type: 'page', url: 'https://acme.com/pricing' },
mode: 'web',
webhook: { url: 'https://example.com/webhook' },
});
console.log(monitor.id);
- lang: Python
source: |-
import os
from context.dev import ContextDev
client = ContextDev(
api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted
)
monitor = client.monitors.create(
change_detection={
"type": "exact"
},
name="Acme pricing page",
schedule={
"type": "interval",
"frequency": 6,
"unit": "hours",
},
target={
"type": "page",
"url": "https://acme.com/pricing",
},
mode="web",
webhook={
"url": "https://example.com/webhook"
},
)
print(monitor.id)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/context-dot-dev/context-go-sdk\"\n\t\"github.com/context-dot-dev/context-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tmonitor, err := client.Monitors.New(context.TODO(), contextdev.MonitorNewParams{\n\t\tChangeDetection: contextdev.MonitorNewParamsChangeDetectionUnion{\n\t\t\tOfExact: &contextdev.MonitorNewParamsChangeDetectionExact{},\n\t\t},\n\t\tName: \"Acme pricing page\",\n\t\tSchedule: contextdev.MonitorNewParamsSchedule{\n\t\t\tType: \"interval\",\n\t\t\tFrequency: 6,\n\t\t\tUnit: \"hours\",\n\t\t},\n\t\tTarget: contextdev.MonitorNewParamsTargetUnion{\n\t\t\tOfPage: &contextdev.MonitorNewParamsTargetPage{\n\t\t\t\tURL: \"https://acme.com/pricing\",\n\t\t\t},\n\t\t},\n\t\tMode: contextdev.MonitorNewParamsModeWeb,\n\t\tWebhook: contextdev.MonitorNewParamsWebhook{\n\t\t\tURL: \"https://example.com/webhook\",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", monitor.ID)\n}\n"
- lang: Ruby
source: |-
require "context_dev"
context_dev = ContextDev::Client.new(api_key: "My API Key")
monitor = context_dev.monitors.create(
change_detection: {type: :exact},
name: "Acme pricing page",
schedule: {frequency: 6, type: :interval, unit: :hours},
target: {type: :page, url: "https://acme.com/pricing"}
)
puts(monitor)
- lang: PHP
source: >-
monitors->create(
changeDetection: ['type' => 'exact'],
name: 'Acme pricing page',
schedule: ['frequency' => 6, 'type' => 'interval', 'unit' => 'hours'],
target: [
'type' => 'page',
'url' => 'https://acme.com/pricing',
'normalizeWhitespace' => true,
],
mode: 'web',
tags: ['pricing', 'competitor'],
webhook: ['url' => 'https://example.com/webhook'],
);
var_dump($monitor);
} catch (APIException $e) {
echo $e->getMessage();
}
- lang: CLI
source: |-
context-dev monitors create \
--api-key 'My API Key' \
--change-detection '{type: exact}' \
--name 'Acme pricing page' \
--schedule '{frequency: 6, type: interval, unit: hours}' \
--target '{type: page, url: https://acme.com/pricing}'
components:
schemas:
MonitorsCreateMonitorRequest:
type: object
title: Create monitor request
description: >-
Creates a web monitor. `mode` is the constant `web`; the behavior is
described by `target` (page, sitemap, or extract) and `change_detection`
(exact or semantic). Supported combinations: page + exact, sitemap +
exact, extract + semantic.
required:
- name
- target
- change_detection
- schedule
properties:
mode:
$ref: '#/components/schemas/MonitorsMode'
name:
type: string
minLength: 1
maxLength: 200
example: Acme pricing monitor
target:
$ref: '#/components/schemas/MonitorsTarget'
change_detection:
$ref: '#/components/schemas/MonitorsChangeDetection'
schedule:
$ref: '#/components/schemas/MonitorsSchedule'
webhook:
$ref: '#/components/schemas/MonitorsNullableWebhookConfig'
tags:
type: array
items:
type: string
minLength: 1
maxLength: 50
maxItems: 20
description: >-
User-defined tags for grouping and filtering monitors and their
changes.
example:
- pricing
- competitor
additionalProperties: false
MonitorsMonitor:
type: object
title: Monitor
description: >-
A web monitor. `mode` is the constant `web`; behavior is described by
`target` (page/sitemap/extract) and `change_detection` (exact/semantic).
required:
- mode
- id
- name
- target
- change_detection
- schedule
- status
- created_at
- updated_at
properties:
mode:
$ref: '#/components/schemas/MonitorsMode'
id:
type: string
example: mon_123
name:
type: string
example: Acme pricing monitor
target:
$ref: '#/components/schemas/MonitorsTarget'
change_detection:
$ref: '#/components/schemas/MonitorsChangeDetection'
schedule:
$ref: '#/components/schemas/MonitorsSchedule'
webhook:
$ref: '#/components/schemas/MonitorsNullableWebhookConfig'
status:
$ref: '#/components/schemas/MonitorsMonitorStatus'
last_run_at:
type: string
format: date-time
nullable: true
last_change_at:
type: string
format: date-time
nullable: true
next_run_at:
type: string
format: date-time
nullable: true
description: When the next scheduled run is due.
last_error:
nullable: true
description: >-
Error from the most recent failed run; null when the last run
succeeded.
allOf:
- $ref: '#/components/schemas/MonitorsRunError'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
tags:
type: array
items:
type: string
minLength: 1
maxLength: 50
maxItems: 20
description: >-
User-defined tags for grouping and filtering monitors and their
changes.
example:
- pricing
- competitor
baseline:
nullable: true
description: >-
Current baseline: the last observed value the monitor compares new
snapshots against. Its shape follows `target.type`
(page/sitemap/extract). Only populated on GET
/monitors/{monitor_id}; null until the first baseline run completes
(and after a target or change_detection update, which resets the
baseline).
oneOf:
- $ref: '#/components/schemas/MonitorsPageBaseline'
- $ref: '#/components/schemas/MonitorsSitemapBaseline'
- $ref: '#/components/schemas/MonitorsExtractBaseline'
additionalProperties: false
MonitorsMode:
type: string
title: Monitor mode
enum:
- web
description: >-
Top-level monitor category. Always `web` today; the concrete behavior is
described by `target` and `change_detection`.
MonitorsTarget:
description: Discriminated union describing what the monitor watches.
oneOf:
- $ref: '#/components/schemas/MonitorsPageTarget'
- $ref: '#/components/schemas/MonitorsSitemapTarget'
- $ref: '#/components/schemas/MonitorsExtractTarget'
discriminator:
propertyName: type
mapping:
page:
$ref: '#/components/schemas/MonitorsPageTarget'
sitemap:
$ref: '#/components/schemas/MonitorsSitemapTarget'
extract:
$ref: '#/components/schemas/MonitorsExtractTarget'
MonitorsChangeDetection:
description: Discriminated union describing how changes are detected.
oneOf:
- $ref: '#/components/schemas/MonitorsExactChangeDetection'
- $ref: '#/components/schemas/MonitorsSemanticChangeDetection'
discriminator:
propertyName: type
mapping:
exact:
$ref: '#/components/schemas/MonitorsExactChangeDetection'
semantic:
$ref: '#/components/schemas/MonitorsSemanticChangeDetection'
MonitorsSchedule:
description: >-
Discriminated union describing how the monitor is scheduled. Only
`interval` is supported today; `cron` and `exact_time` are reserved for
future use.
oneOf:
- $ref: '#/components/schemas/MonitorsIntervalSchedule'
discriminator:
propertyName: type
mapping:
interval:
$ref: '#/components/schemas/MonitorsIntervalSchedule'
MonitorsNullableWebhookConfig:
nullable: true
allOf:
- $ref: '#/components/schemas/MonitorsWebhookConfig'
MonitorsMonitorStatus:
type: string
enum:
- active
- paused
- failed
description: >-
Monitor lifecycle status. `failed` means the most recent run failed (see
the monitor's `last_error`); failed monitors keep running on schedule
and flip back to `active` on the next successful run. Monitors are
auto-`paused` after repeated consecutive failures or insufficient-credit
skips; resume by PATCHing status to `active`.
MonitorsRunError:
type: object
required:
- code
- message
properties:
code:
type: string
example: fetch_failed
message:
type: string
example: The target URL could not be fetched.
additionalProperties: false
MonitorsPageBaseline:
type: object
title: Page baseline
description: >-
Current baseline of a `page` monitor: the visible page text as last
observed.
required:
- text
- captured_at
properties:
text:
type: string
description: The page's visible text as last observed.
example: |-
Acme Pricing
Starter $9/mo…
captured_at:
type: string
format: date-time
description: When this baseline was last captured or replaced.
additionalProperties: false
MonitorsSitemapBaseline:
type: object
title: Sitemap baseline
description: >-
Current baseline of a `sitemap` monitor: the normalized URL set as last
observed.
required:
- urls
- url_count
- captured_at
properties:
urls:
type: array
items:
type: string
description: The sitemap URLs as last observed (sorted, normalized).
example:
- https://acme.com/blog/launch
- https://acme.com/pricing
url_count:
type: integer
description: Number of URLs in the baseline.
example: 2
captured_at:
type: string
format: date-time
description: When this baseline was last captured or replaced.
additionalProperties: false
MonitorsExtractBaseline:
type: object
title: Extract baseline
description: >-
Current baseline of an `extract` monitor: the pages it tracks and the
structured data as last extracted.
required:
- data
- urls_analyzed
- captured_at
properties:
data:
description: >-
The extracted structured data, matching the monitor's extraction
schema (same shape as the /web/extract endpoint's `data`). Refreshed
when the monitor re-discovers its page set (at most about once a
day); `null` when no extraction has been captured yet.
example:
plans:
- name: Starter
price: $9/mo
urls_analyzed:
type: array
items:
type: string
description: The page URLs the monitor tracks and analyzes for changes.
example:
- https://acme.com/pricing
captured_at:
type: string
format: date-time
description: When this baseline was last captured or replaced.
additionalProperties: false
ErrorResponse:
type: object
properties:
message:
type: string
description: Error message
error_code:
type: string
enum:
- INTERNAL_ERROR
- VALID
- NOT_FOUND
- FORBIDDEN
- USAGE_EXCEEDED
- RATE_LIMITED
- UNAUTHORIZED
- DISABLED
- INSUFFICIENT_PERMISSIONS
- TIMEOUT_EXCEEDS_MAXIMUM
- WEBSITE_ACCESS_ERROR
- EXTERNAL_PROVIDER_ERROR
- INPUT_VALIDATION_ERROR
- REQUEST_TIMEOUT
description: Error code indicating the type of error
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
MonitorsPageTarget:
type: object
title: Page target
description: Watch a single web page.
required:
- type
- url
properties:
type:
type: string
enum:
- page
url:
type: string
format: uri
example: https://acme.com/pricing
normalize_whitespace:
type: boolean
default: true
description: Normalize whitespace before comparing or analyzing text.
additionalProperties: false
MonitorsSitemapTarget:
type: object
title: Sitemap target
description: >-
Watch a sitemap for URL additions and removals. Crawled URLs are
normalized (lowercased host, no trailing slash/fragment) and scoped to
the monitored site and its subdomains before comparison. On a detected
difference the sitemap is re-fetched within the same run and only URLs
both observations agree on are reported, suppressing transient crawl
flaps.
required:
- type
- url
properties:
type:
type: string
enum:
- sitemap
url:
type: string
format: uri
description: Sitemap URL to monitor.
example: https://acme.com/sitemap.xml
include:
type: array
items:
type: string
description: URL path patterns to include.
example:
- /blog/*
- /pricing*
exclude:
type: array
items:
type: string
description: URL path patterns to exclude.
example:
- /legal/*
- /privacy
max_urls:
type: integer
minimum: 1
maximum: 10000
default: 5000
description: Maximum number of sitemap URLs to track (capped at 10,000).
additionalProperties: false
MonitorsExtractTarget:
type: object
title: Extract target
description: >-
Watch the monitor-relevant pages of a site for meaningful changes. A
crawl guided by `schema`/`instructions` selects up to `max_pages`
relevant pages to track; each run re-checks exactly those pages, and
confirmed content changes are judged against the monitor's instructions.
The tracked page set is refreshed by a periodic re-discovery crawl.
required:
- type
- url
- instructions
properties:
type:
type: string
enum:
- extract
url:
type: string
format: uri
description: Root URL to extract structured data from.
example: https://acme.com
schema:
type: object
additionalProperties: true
description: >-
JSON Schema describing the data you care about. It guides which
pages are selected for tracking and gives the change judge context
on what matters. If omitted, a default summary + key-points schema
is used.
example:
type: object
properties:
plans:
type: array
items:
type: object
properties:
name:
type: string
price:
type: string
instructions:
type: string
minLength: 1
maxLength: 2000
description: >-
Natural-language instructions guiding which pages and facts to track
and which changes to report.
example: >-
Extract every pricing plan with its monthly price and included
limits.
max_pages:
type: integer
minimum: 1
maximum: 50
default: 10
description: Maximum number of pages to track.
max_depth:
type: integer
minimum: 0
maximum: 10
description: >-
Optional maximum link depth from the starting URL (0 = only the
starting page).
follow_subdomains:
type: boolean
default: false
additionalProperties: false
MonitorsExactChangeDetection:
type: object
title: Exact
description: >-
Detect exact changes. For page targets, this means visible text diffs.
For sitemap targets, this means URL additions and removals.
required:
- type
properties:
type:
type: string
enum:
- exact
additionalProperties: false
MonitorsSemanticChangeDetection:
type: object
title: Semantic
description: >-
Detect meaning-level changes to the extracted data, ignoring cosmetic or
paraphrase-only differences. What is watched is determined by the
extract target's `schema` and `instructions`.
required:
- type
properties:
type:
type: string
enum:
- semantic
confidence_threshold:
type: number
minimum: 0
maximum: 1
default: 0.75
additionalProperties: false
MonitorsIntervalSchedule:
type: object
title: Interval
description: >-
Run the monitor on a fixed interval defined by a frequency and a unit,
e.g. every 6 hours or every 2 days. The total interval (frequency ×
unit) must be between 10 minutes and 1 year.
required:
- type
- frequency
- unit
properties:
type:
type: string
enum:
- interval
frequency:
type: integer
minimum: 1
maximum: 525600
description: >-
Number of units between runs. The resulting interval (frequency ×
unit) must be at least 10 minutes and at most 1 year (e.g. minimum
10 when unit is minutes; maximum 365 when unit is days).
example: 6
unit:
$ref: '#/components/schemas/MonitorsScheduleUnit'
additionalProperties: false
MonitorsWebhookConfig:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Webhook URL called when a change is detected.
example: https://example.com/webhook
secret:
type: string
readOnly: true
description: >-
Signing secret used to verify webhook authenticity. Each delivery
includes an `X-Context-Signature: t=,v1=` header, where
the HMAC is SHA-256 over `"{t}.{rawRequestBody}"` keyed by this
secret. Recompute it with a constant-time compare and reject stale
timestamps to prevent replay. Generated by the API; cannot be set by
clients.
example: whsec_8f3a…
additionalProperties: false
KeyMetadata:
type: object
description: >-
Metadata about the API key used for the request. Included in every
response whenever a valid API key is provided, even when the response
status is not 200.
properties:
credits_consumed:
type: integer
description: The number of credits consumed by this request.
credits_remaining:
type: integer
description: >-
The number of credits remaining for your organization after this
request.
required:
- credits_consumed
- credits_remaining
MonitorsScheduleUnit:
type: string
enum:
- minutes
- hours
- days
example: hours
responses:
MonitorsBadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
MonitorsUnauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
MonitorsLimitExceeded:
description: >-
Monitor limit for the account's plan reached (error_code
MONITOR_LIMIT_EXCEEDED)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````