> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Create a monitor

> Create a monitor with POST /v1/monitors: a topic, an optional schedule and webhook. The response carries the webhook signing secret.

Start watching the web for new pages about a topic. Store `webhook.secret` from the response. Only this response and an [update](https://docs.keenable.ai/api-reference/monitors/update.md) that adds a first webhook carry it. Send an `Idempotency-Key` header so a retried create doesn't make a second monitor. See [Monitors](https://docs.keenable.ai/products/monitors) for schedules, events and signatures.

## When to use it

Create one monitor per topic. Every key in your organization sees the same monitors, so first [list your monitors](https://docs.keenable.ai/api-reference/monitors/list.md) with `name` and reuse one on the same topic. Write `search.query` as a topic in plain words, not keywords. [Write a good query](https://docs.keenable.ai/products/monitors#write-a-good-query) has examples.

A new monitor starts empty and doesn't backfill: it matches only pages crawled after you create it. For pages already published, use [Search](https://docs.keenable.ai/products/search.md). A create counts toward your organization's active monitors. See [Limits](https://docs.keenable.ai/products/monitors#limits).

The same `Idempotency-Key` with the same body within 24 hours returns the monitor the first call created. The same key with another body returns `409` with `idempotency_conflict`.

## SDK, CLI and MCP

| Client | Call |
| - | - |
| Python, TypeScript | `client.monitors.create(...)` |
| Go | `client.Monitors.Create(ctx, params)` |
| Rust | `client.monitors().create(&params)` |
| CLI | `keenable monitors create "<topic>"`, with `--every`, `--cron`, `--webhook`, `--idempotency-key` |
| MCP | `create_monitor`, with `query`, `name`, `webhookUrl`, `includeDomains` and `excludeDomains` |

The SDK methods need SDK 0.2.0 or later. Each SDK sends an `Idempotency-Key` on every create, yours or a new one, so it can retry the call safely. See [SDKs → Monitors](https://docs.keenable.ai/sdks.md#monitors), [CLI → Monitors](https://docs.keenable.ai/cli.md#monitors) and [Monitors tools](https://docs.keenable.ai/mcp-server.md#monitors-tools).

## Related operations

* [Update a monitor](https://docs.keenable.ai/api-reference/monitors/update.md) changes the query, schedule or webhook later.
* [Run a monitor now](https://docs.keenable.ai/api-reference/monitors/trigger.md) starts a run without waiting for the schedule.
* [List results](https://docs.keenable.ai/api-reference/monitors/results.md) reads every result the monitor accepted.

For a step-by-step guide, see [Create a monitor](https://docs.keenable.ai/guides/create-a-monitor.md).


## OpenAPI

````yaml POST /v1/monitors
openapi: 3.0.3
info:
  title: Keenable API
  version: 1.0.0
  description: Web search, page fetching and monitors API.
servers:
  - url: https://api.keenable.ai
    description: Production
security:
  - apiKey: []
  - bearerAuth: []
paths:
  /v1/monitors:
    post:
      tags:
        - Monitors
      summary: Create a monitor
      description: >-
        Start watching the web for new pages about a topic. Takes a few seconds.
        The response carries `webhook.secret` when you send a webhook. Only this
        call and an update that adds the first webhook return it. The monitor
        starts empty and doesn't backfill.
      operationId: monitors.create
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: >-
            Any string. Within 24 hours, the same key with the same body returns
            the monitor the first call created instead of creating another one.
          example: 8e1c4d2a-releases-monitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorCreateRequest'
      responses:
        '201':
          description: The new monitor, with `webhook.secret` when you sent a webhook
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '400':
          $ref: '#/components/responses/MonitorBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MonitorForbidden'
        '409':
          description: >-
            The `Idempotency-Key` was used in the last 24 hours with another
            body (`idempotency_conflict`). Send a new key, or the original body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          $ref: '#/components/responses/MonitorRateLimited'
        '503':
          $ref: '#/components/responses/MonitorsUnavailable'
      x-codeSamples:
        - lang: typescript
          label: TypeScript
          source: |
            import { Keenable } from "keenable";

            async function main() {
              // reads KEENABLE_API_KEY from the environment
              const client = new Keenable();
              const monitor = await client.monitors.create({
                name: "Open-weights LLM releases",
                search: { query: "new open-weights LLM releases" },
                webhook: {
                  url: "https://hooks.example.com/keenable",
                  events: ["monitor.result.found", "monitor.disabled"],
                },
              });
              console.log(monitor.id, monitor.status);
              console.log(monitor.webhook?.secret); // shown once: store it
            }

            main();
        - lang: python
          label: Python
          source: |
            from keenable import Keenable

            # reads KEENABLE_API_KEY from the environment
            client = Keenable()
            monitor = client.monitors.create(
                name="Open-weights LLM releases",
                search={"query": "new open-weights LLM releases"},
                webhook={
                    "url": "https://hooks.example.com/keenable",
                    "events": ["monitor.result.found", "monitor.disabled"],
                },
            )
            print(monitor.id, monitor.status)
            print(monitor.webhook.secret)  # shown once: store it
        - lang: go
          label: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/keenableai/keenable-sdk/go\"\n)\n\nfunc main() {\n\t// reads KEENABLE_API_KEY from the environment\n\tclient, err := keenable.New(nil)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer client.Close()\n\n\tmonitor, err := client.Monitors.Create(context.Background(), &keenable.MonitorCreateParams{\n\t\tName:   \"Open-weights LLM releases\",\n\t\tSearch: keenable.MonitorSearchParams{Query: \"new open-weights LLM releases\"},\n\t\tWebhook: &keenable.MonitorWebhookParams{\n\t\t\tURL:    \"https://hooks.example.com/keenable\",\n\t\t\tEvents: []string{\"monitor.result.found\", \"monitor.disabled\"},\n\t\t},\n\t})\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfmt.Println(monitor.ID, monitor.Status)\n\tif monitor.Webhook != nil && monitor.Webhook.Secret != nil {\n\t\tfmt.Println(*monitor.Webhook.Secret) // shown once: store it\n\t}\n}\n"
        - lang: rust
          label: Rust
          source: >
            use keenable::{Client, MonitorCreateParams, MonitorSearchParams,
            MonitorWebhookParams};


            #[tokio::main]

            async fn main() -> Result<(), keenable::Error> {
                // reads KEENABLE_API_KEY from the environment
                let client = Client::new()?;
                let monitor = client
                    .monitors()
                    .create(&MonitorCreateParams {
                        name: Some("Open-weights LLM releases".into()),
                        search: MonitorSearchParams::new("new open-weights LLM releases"),
                        webhook: Some(MonitorWebhookParams {
                            url: Some("https://hooks.example.com/keenable".into()),
                            events: Some(vec!["monitor.result.found".into(), "monitor.disabled".into()]),
                        }),
                        ..Default::default()
                    })
                    .await?;
                println!("{} {}", monitor.id, monitor.status);
                if let Some(webhook) = monitor.webhook {
                    println!("{}", webhook.secret.unwrap_or_default()); // shown once: store it
                }
                Ok(())
            }
        - lang: bash
          label: curl
          source: |
            curl -X POST https://api.keenable.ai/v1/monitors \
              -H "X-API-Key: $KEENABLE_API_KEY" \
              -H "Content-Type: application/json" \
              -H "Idempotency-Key: open-weights-llm-releases" \
              -d '{
                "name": "Open-weights LLM releases",
                "search": {"query": "new open-weights LLM releases"},
                "webhook": {
                  "url": "https://hooks.example.com/keenable",
                  "events": ["monitor.result.found", "monitor.disabled"]
                }
              }'
components:
  schemas:
    MonitorCreateRequest:
      type: object
      additionalProperties: false
      required:
        - search
      properties:
        name:
          type: string
          maxLength: 200
          nullable: true
          description: A display name. Defaults to the query.
          example: Open-weights LLM releases
        search:
          $ref: '#/components/schemas/MonitorSearch'
        schedule:
          $ref: '#/components/schemas/MonitorSchedule'
          nullable: true
          description: >-
            When runs happen. Without a schedule, runs happen only when you
            trigger one.
        webhook:
          $ref: '#/components/schemas/MonitorWebhook'
          nullable: true
        output_schema:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            A JSON Schema. With it, each run that finds pages also returns
            `output`: a summary of those pages in this shape, with the pages
            that support each field.
        metadata:
          type: object
          additionalProperties:
            type: string
          maxProperties: 50
          description: >-
            Your own string tags, at most 50 keys. Every webhook event carries
            them. For example `{"team": "research"}`.
          nullable: true
    Monitor:
      type: object
      required:
        - id
        - object
        - name
        - status
        - search
        - schedule
        - webhook
        - metadata
        - last_run_at
        - next_run_at
        - upcoming_runs
        - created_at
        - updated_at
      properties:
        id:
          type: string
          example: mon_3kq9z2c8f1a04b7d9e6f5a21
        object:
          type: string
          enum:
            - monitor
        name:
          type: string
          nullable: true
          example: Open-weights LLM releases
        status:
          type: string
          enum:
            - active
            - paused
            - disabled
            - completed
          description: >-
            `active` and `paused` are set by you. `completed`: a `once` monitor
            after its run. `disabled`: set by Keenable after 10 failed runs in a
            row, or when no webhook delivery succeeded for 3 days. Only an
            active monitor matches pages.
        search:
          type: object
          required:
            - query
            - max_results
            - include_domains
            - exclude_domains
            - content
          properties:
            query:
              type: string
            max_results:
              type: integer
            include_domains:
              type: array
              items:
                type: string
              nullable: true
            exclude_domains:
              type: array
              items:
                type: string
              nullable: true
            content:
              $ref: '#/components/schemas/MonitorContent'
              nullable: true
        schedule:
          $ref: '#/components/schemas/MonitorSchedule'
          nullable: true
          description: >-
            All three keys are always present. `timezone` is `UTC` for a cron
            schedule sent without one, and `null` for `interval` and `once`.
        output_schema:
          type: object
          nullable: true
          additionalProperties: true
        webhook:
          type: object
          nullable: true
          required:
            - url
            - events
          properties:
            url:
              type: string
            events:
              type: array
              items:
                type: string
                enum:
                  - monitor.created
                  - monitor.updated
                  - monitor.deleted
                  - monitor.run.created
                  - monitor.run.completed
                  - monitor.run.failed
                  - monitor.disabled
                  - monitor.result.found
                  - monitor.result.changed
            secret:
              type: string
              example: whsec_example
              description: >-
                The signing secret. Only the create response and the response to
                an update that adds the first webhook have it.
        metadata:
          type: object
          nullable: true
          additionalProperties:
            type: string
        last_run_at:
          type: string
          format: date-time
          nullable: true
          description: When the last run ended.
        next_run_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            The next scheduled run. `null` without a schedule or while the
            monitor isn't active.
        upcoming_runs:
          type: array
          items:
            type: string
            format: date-time
          description: >-
            The next three run times, in UTC. Empty without a schedule or while
            the monitor isn't active.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Short error title, such as `Invalid parameter` or `Not found`.
          example: Invalid parameter
        message:
          type: string
          description: What went wrong and what to change. Sometimes absent.
          example: '"max_results": must be an integer between 1 and 50'
        details:
          description: Structured details, when the error has any.
        retryAfter:
          type: integer
          description: >-
            Seconds to wait before retrying. Present on `429` responses from
            Keenable's own rate limits, matching the `Retry-After` header.
    MonitorSearch:
      type: object
      additionalProperties: false
      required:
        - query
      description: >-
        What to watch for. A field other than these returns `400` with
        `monitor_option_not_supported`.
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 2000
          description: The topic in plain words, not keywords or a boolean expression.
          example: new open-weights LLM releases
        max_results:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: The most pages one run returns.
        include_domains:
          type: array
          items:
            type: string
          nullable: true
          description: Only pages on these sites.
          example:
            - huggingface.co
            - github.com
        exclude_domains:
          type: array
          items:
            type: string
          nullable: true
          description: Never pages on these sites.
        content:
          $ref: '#/components/schemas/MonitorContent'
          nullable: true
    MonitorSchedule:
      type: object
      additionalProperties: false
      required:
        - type
      description: >-
        When runs happen. A schedule that breaks a rule returns `400` with
        `invalid_request`, and `message` says which rule.
      properties:
        type:
          type: string
          enum:
            - cron
            - interval
            - once
          description: >-
            `cron`: a five-field cron expression, at most once an hour.
            `interval`: a duration from 1h to 90d, counted from when the
            schedule was set. `once`: one run at a timestamp or after a delay,
            up to a year ahead.
        value:
          type: string
          nullable: true
          description: >-
            For `cron`, the expression, such as `0 9 * * 1-5`. For `interval`, a
            number and a unit (`m`, `h`, `d` or `w`), such as `6h` or `2w`. For
            `once`, an ISO 8601 timestamp such as `2026-12-01T12:00:00Z` or a
            delay such as `2h`; leave it out to run now.
          example: 0 9 * * 1-5
        timezone:
          type: string
          nullable: true
          description: >-
            An IANA time zone for `cron`, such as `Europe/Paris`. Defaults to
            `UTC`. Only `cron` takes it; with another type the API returns
            `400`.
          example: Europe/Paris
    MonitorWebhook:
      type: object
      additionalProperties: false
      required:
        - url
      properties:
        url:
          type: string
          description: A public `https` address. Private and local hosts return `400`.
          example: https://hooks.example.com/keenable
        events:
          type: array
          items:
            type: string
            enum:
              - monitor.created
              - monitor.updated
              - monitor.deleted
              - monitor.run.created
              - monitor.run.completed
              - monitor.run.failed
              - monitor.disabled
              - monitor.result.found
              - monitor.result.changed
          nullable: true
          description: >-
            The events to send. Defaults to the seven `monitor.*` and
            `monitor.run.*` events plus `monitor.result.found` (each new result,
            minutes after it is found) and `monitor.result.changed` (a result
            you already got changed in substance). List events to send only
            those.
    MonitorContent:
      type: object
      additionalProperties: false
      properties:
        text:
          type: boolean
          default: false
          description: >-
            Add each page's text to results and events: its first 6,000
            characters, kept for 3 days after the match.
  headers:
    XRequestId:
      description: ID of this request. Include it when you report a problem.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
      example: 1
  responses:
    MonitorBadRequest:
      description: >-
        The request is invalid. `code` is `invalid_request` for a missing or
        wrong field or a schedule that breaks a rule, and
        `monitor_option_not_supported` for a field Monitors doesn't have or
        doesn't offer yet. `message` names the field. Correct the request;
        retrying unchanged returns the same error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: >-
        No key was sent (`Missing authentication`), or the key is malformed,
        unknown or has the wrong prefix (`Authentication failed`, with
        `Malformed API key` or `Invalid API key` in `message`). Send a valid key
        in `X-API-Key` or `Authorization: Bearer`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    MonitorForbidden:
      description: >-
        Your key is valid but can't do this. `monitors_not_enabled`: Monitors is
        turned off for your organization; contact support@keenable.ai.
        `monitor_limit_reached`: your organization already has 100 active
        monitors; pause or delete one, then retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    MonitorRateLimited:
      description: >-
        Your organization sent more than 120 Monitors requests, or more than 10
        creates, in the last minute (`rate_limited`). Wait, then retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
    MonitorsUnavailable:
      description: >-
        The Monitors service didn't answer (`monitors_unavailable`). The request
        may not have been applied. Retry after a few seconds; retry a create
        with the same `Idempotency-Key`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your API key, such as `keen_...`. Create one in the Keenable console. If
        you send both this header and `Authorization`, the API uses this one.
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your API key sent as `Authorization: Bearer keen_...`, for clients that
        only support bearer tokens.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.