Skip to main content

Base URL

All requests require an X-API-Key header. See Authentication.

Endpoints

Create a Monitor

The response is 201 Created and contains the new Monitor plus its first baseline run:
Monitor responses do not currently echo purpose or dashboard-managed email settings.

Common Fields

string
required
fetch for a Page Monitor or search for a Topic Monitor.
object
required
Type-specific configuration. See the Page and Topic fields below.
string
required
A five-field cron expression. It runs in UTC unless prefixed with an IANA time zone, for example CRON_TZ=America/New_York 0 9 * * 1-5. Topic schedules must keep every run at least 30 minutes apart.
string
Optional Monitor name, up to 100 characters.
string
Optional description of the change that matters, up to 2000 characters. TinyFish evaluates detected changes against this purpose.
string
Optional public HTTP or HTTPS URL that receives every scheduled run result.
Email delivery is currently configured in the dashboard. The REST API does not accept email settings.

Page Config

string
required
Public HTTP or HTTPS webpage URL.
string
default:"json"
Extracted content format: json, markdown, or html.
Include links found on the webpage.
Include image links found on the webpage.
string[]
CSS selectors (1-20) that scope each run to matching elements, so the Monitor only reports changes inside them, for example [".price"]. Works like Fetch’s include_selectors. If no selector matches when you create the Monitor, the request fails with 422, lists selectors found on the page, and no Monitor is created. If a later run matches nothing, that run fails with selector_not_matched.
string[]
CSS selectors (1-20) for elements to remove before comparing, such as ads, timestamps, or rotating banners.
Page Monitors always run Fetch with ttl: 0 to prefer fresh content. The deprecated config.ttl field is accepted for compatibility but does not change this behavior.

Topic Config

string
required
Search query to repeat, up to 2000 characters.
integer
Optional freshness window from 1 to 5,256,000 minutes.
integer
default:"10"
Number of results to compare per run, from 1 to 10.

List and Get Monitors

The list response wraps Monitor objects in a monitors array. To retrieve one Monitor:
Saved run history is currently available in the dashboard. The REST API returns the baseline from creation and the result of each run-now request, but does not provide a run-history list endpoint.

Pause or Resume

Send a status-only update. active resumes the schedule and paused stops future scheduled runs without removing history.

Edit a Monitor

Send only the fields you want to change: schedule_cron, name, purpose, or webhook_url. Omitted fields keep their existing values, and null clears the name, purpose, or webhook URL. Send at least one field.
The SDKs’ update methods still take schedule_cron. To change several fields at once:
The target type and its config cannot be changed after creation. Create a new Monitor to watch a different page or topic.
Do not combine status with schedule or metadata fields in one request. Send lifecycle and edit updates separately.

Run Now

The response is 201 Created with the Page Fetch result or Topic Search result under run. Run now works for active, paused, and failed Monitors. A Topic Monitor run can return 409 Conflict with error.code set to RETRY_REQUIRED when the run could not be created. Retry the request.
Run now records the result but does not send webhook or email notifications. Those delivery paths run only for scheduled checks.

Delete a Monitor

Deleting a Monitor permanently removes the Monitor and its schedule. Its run history is no longer available from Monitor.

Scheduled Webhook Payloads

Webhooks are sent for every scheduled run, including runs with no changes. Page payloads include a fetch_monitor_id; Topic payloads include a search_monitor_id.
  • outcome is changed or unchanged compared with the previous run. It is baseline when there is no previous run to compare with, such as the first run.
  • diff is a unified diff against the previous run. It is null for baseline and unchanged runs.
  • diff_truncated is true when the diff was cut at a line to keep the payload under 1 MB. Open the run in the dashboard for the full diff.
  • judgment checks the change against the Monitor’s purpose. It is null for baseline and unchanged runs, and when the Monitor has no purpose. summary is set only when is_relevant is true. When the check fails, is_relevant is null and error is set.
  • results holds the full page content for every run.
Webhook delivery is best effort and retried up to three times. A delivery failure does not change the completed Monitor run.