> ## 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
> 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
> Read an API key from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat; send them to https://docs.keenable.ai/api-keys.md
> 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.
> Every error, with its cause and fix: https://docs.keenable.ai/errors.md

# Create a monitor

> Create a monitor with POST /v1/monitors: a topic in plain words, an optional schedule and webhook. The response is the only one that carries the webhook signing secret.

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


## 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 is the only one that carries `webhook.secret`. 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.hit", "monitor.disabled"],
                },
              });
              console.log(monitor.id, monitor.status);
              console.log(monitor.webhook?.secret); // only the create response carries 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.hit", "monitor.disabled"],
                },
            )
            print(monitor.id, monitor.status)
            print(monitor.webhook.secret)  # only the create response carries 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.hit\", \"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) // only the create response carries 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.hit".into(), "monitor.disabled".into()]),
                        }),
                        ..Default::default()
                    })
                    .await?;
                println!("{} {}", monitor.id, monitor.status);
                if let Some(webhook) = monitor.webhook {
                    println!("{}", webhook.secret.unwrap_or_default()); // only the create response carries 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.hit", "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.hit
                  - monitor.update
            secret:
              type: string
              example: whsec_example
              description: The signing secret. Only the response to the create call has 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.
        agent_run_id:
          type: string
          nullable: true
          description: 'Always `null`: not available yet.'
        backfill:
          type: object
          nullable: true
          description: 'Always `null`: not available yet.'
        memory_scope:
          type: string
          nullable: true
          description: 'Always `null`: not available yet.'
        estimated_cost_usd:
          type: number
          nullable: true
          description: 'Always `null`: monitors are free for now.'
        cost_this_month_usd:
          type: number
          nullable: true
          description: 'Always `null`: monitors are free for now.'
        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.hit
              - monitor.update
          nullable: true
          description: >-
            The events to send. Defaults to the seven `monitor.*` and
            `monitor.run.*` events. Add `monitor.hit` to get each new page
            minutes after it is found, and `monitor.update` for pages you
            already got that changed.
    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.