---
title: "Create a monitor"
method: POST
path: "/v1/monitors"
tags: ["monitors"]
---

# Create a monitor

`POST /v1/monitors`

## Request

- Base URL: `https://api.olostep.com`
- URL: `https://api.olostep.com/v1/monitors`
- Auth: HTTP bearer

Starts monitoring a target for changes. When `?stream=1`, responds with a text/event-stream provisioning stream instead of the buffered 202.

## Query parameters

- `stream` '1' | 'true': When truthy, respond with a provisioning event stream instead of a 202.

## Request body

- object
  - `query` string, required: What to monitor, in natural language.
  - `source_policy` object
    - `include_urls` string[]
    - `exclude_urls` string[]
    - `include_domains` string[]
    - `exclude_domains` string[]
  - `frequency` string: Natural-language schedule (e.g. "every day at 9am"). Minimum interval is 10 minutes.
  - `notification` object
    - `events` string[]
    - `channels` object[]
      - `type` 'email' | 'slack' | 'sms', required
      - `target` string, required
      - `events` string[]
  - `webhook` object
    - `url` string, uri, required
  - `metadata` object
  - `output_schema` object: JSON Schema for structured extraction output.

## Response `202`

Default Response

- object: A monitor resource.
  - `id` string, required
  - `object` string
  - `query` string, required
  - `tracked` object
    - `type` string, nullable
    - `urls` string[]
    - `web_query` string, nullable
  - `source_policy` object
    - `include_urls` string[]
    - `exclude_urls` string[]
    - `include_domains` string[]
    - `exclude_domains` string[]
  - `schedule` object
    - `frequency` string, nullable
    - `cron` string, nullable
    - `timezone` string
    - `next_run_at` string, nullable
  - `notification` object
    - `events` string[]
    - `channels` object[]
      - `type` 'email' | 'slack' | 'sms', required
      - `target` string, required
      - `events` string[]
  - `webhook` object, nullable
    - `url` string, uri, required
  - `output_schema` object, nullable
  - `status` 'provisioning' | 'active' | 'paused' | 'failed' | 'deleted', required
  - `error_message` string, nullable
  - `last_run` object, nullable
    - `id` string, nullable
    - `status` string
    - `change_detected` boolean, nullable
    - `ran_at` string, nullable
  - `last_change` object, nullable
    - `id` string, nullable
    - `ran_at` string, nullable
    - `changed` boolean, nullable
  - `agent` object
    - `id` string, nullable
  - `metadata` object
  - `created` number, required
  - `updated` number
  - `total_count` number
  - `mermaid_diagram` string

## Other responses

- `400`: Default Response
- `401`: Default Response
- `429`: Default Response
- `502`: Default Response
- `503`: Default Response
- `504`: Default Response

---

[API](https://skmtc.dev/olostep/apis/olostep-api.md) · [All operations](https://skmtc.dev/olostep/apis/olostep-api/llms.txt) · [OpenAPI document](https://skmtc.dev/olostep/apis/olostep-api/revisions/13c766ab100c?raw)