Bewary Watches API

openapi: 3.2.0
info:
  title: Bewary Watches API
  description: 'Scam intelligence for apps and AI agents: links, domains, IPs, phone numbers, SMS short codes, emails, wallets, bank accounts (IBAN), mobile apps and payment handles, each with a typed verdict, facts and reason codes. Contract: https://bewary.app/docs. Pricing: https://bewary.app/pricing.'
  version: 1.9.0
servers:
- url: https://api.bewary.app
security:
- bearer: []
- apiKey: []
- {}
tags:
- name: Watches
paths:
  /v1/watches:
    post:
      tags:
      - Watches
      summary: Watch a domain, phone number, wallet or brand
      description: 'Get an event when the entity changes: a domain''s IP addresses, name servers, up/down/parked state,

        registration (re-registered, expiring, expired) or listing; a number''s or wallet''s listing; a new lookalike of a

        brand (EVENTS.md). 1 credit a day per watch, charged a day ahead (the first day now); a brand watch also costs

        1 credit per lookalike event. Watching an entity already watched updates its event types and charges nothing.'
      operationId: createWatch
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchIn'
      responses:
        '200':
          description: The watch, new or the existing one on that entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchCreated'
        '400':
          description: invalid_input or unsupported_type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'unauthorized: missing, revoked or wrong key, or an option that needs a key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: 'quota_exceeded: the key is out of credits'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'rate_limited: wait for Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 'degraded_unavailable: a needed source is down; retry later'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-mcp-tool: watch
    get:
      tags:
      - Watches
      summary: List watches
      description: Every live watch on the account, active or paused. Free.
      operationId: listWatches
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Every live watch, oldest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchList'
        '400':
          description: invalid_input or unsupported_type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'unauthorized: missing, revoked or wrong key, or an option that needs a key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'rate_limited: wait for Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 'degraded_unavailable: a needed source is down; retry later'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-mcp-tool: list_watches
  /v1/watches/{watch_id}:
    get:
      tags:
      - Watches
      summary: One watch and its delivery record
      description: 'The watch, with its events in the last 30 days, how many no webhook endpoint could take after every retry,

        and how many wait for a delivery. Free.'
      operationId: getWatch
      parameters:
      - name: watch_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 40
          title: Watch Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: The watch, its events in the last 30 days and how many could not be delivered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchDetail'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: invalid_input or unsupported_type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'unauthorized: missing, revoked or wrong key, or an option that needs a key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'rate_limited: wait for Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 'degraded_unavailable: a needed source is down; retry later'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Watches
      summary: Stop a watch
      description: No more events or charges for it; the day already paid is not refunded. Its events stay readable.
      operationId: deleteWatch
      parameters:
      - name: watch_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 40
          title: Watch Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Deleted. Its events stay in GET /v1/events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deleted'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: invalid_input or unsupported_type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'unauthorized: missing, revoked or wrong key, or an option that needs a key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'rate_limited: wait for Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 'degraded_unavailable: a needed source is down; retry later'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-mcp-tool: unwatch
components:
  schemas:
    Watch:
      properties:
        id:
          type: string
          title: Id
          description: wch_ + a ULID.
        entity:
          $ref: '#/components/schemas/WatchEntity'
        events:
          items:
            type: string
            enum:
            - domain.ip_changed
            - domain.ns_changed
            - domain.down
            - domain.up
            - domain.parked
            - domain.listed
            - domain.delisted
            - domain.reregistered
            - domain.expiring
            - domain.expired
            - domain.held
            - phone.listed
            - phone.delisted
            - wallet.listed
            - wallet.delisted
            - wallet.sanctioned
            - brand.lookalike_registered
            - brand.lookalike_cert
            - brand.lookalike_live
          type: array
          title: Events
          description: The event types this watch produces.
        status:
          type: string
          enum:
          - active
          - paused
          title: Status
          description: 'paused: the balance could not pay a day; a top-up resumes it and produces the gap.'
        created_at:
          type: string
          title: Created At
          description: RFC 3339 UTC.
        paid_until:
          type: string
          title: Paid Until
          description: Events are produced for changes up to this time. RFC 3339 UTC.
        paused_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Paused At
        last_event_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Event At
        credits_per_day:
          type: integer
          title: Credits Per Day
          description: What a day of this watch costs (PRICING section 3.1).
      type: object
      required:
      - id
      - entity
      - events
      - status
      - created_at
      - paid_until
      - credits_per_day
      title: Watch
    WatchIn:
      properties:
        entity:
          $ref: '#/components/schemas/WatchEntity'
        events:
          anyOf:
          - items:
              type: string
              enum:
              - domain.ip_changed
              - domain.ns_changed
              - domain.down
              - domain.up
              - domain.parked
              - domain.listed
              - domain.delisted
              - domain.reregistered
              - domain.expiring
              - domain.expired
              - domain.held
              - phone.listed
              - phone.delisted
              - wallet.listed
              - wallet.delisted
              - wallet.sanctioned
              - brand.lookalike_registered
              - brand.lookalike_cert
              - brand.lookalike_live
            type: array
          - type: 'null'
          title: Events
          description: 'The event types to produce; omitted or empty: every event type of the entity type.'
      type: object
      required:
      - entity
      title: WatchIn
    WatchDetail:
      properties:
        id:
          type: string
          title: Id
          description: wch_ + a ULID.
        entity:
          $ref: '#/components/schemas/WatchEntity'
        events:
          items:
            type: string
            enum:
            - domain.ip_changed
            - domain.ns_changed
            - domain.down
            - domain.up
            - domain.parked
            - domain.listed
            - domain.delisted
            - domain.reregistered
            - domain.expiring
            - domain.expired
            - domain.held
            - phone.listed
            - phone.delisted
            - wallet.listed
            - wallet.delisted
            - wallet.sanctioned
            - brand.lookalike_registered
            - brand.lookalike_cert
            - brand.lookalike_live
          type: array
          title: Events
          description: The event types this watch produces.
        status:
          type: string
          enum:
          - active
          - paused
          title: Status
          description: 'paused: the balance could not pay a day; a top-up resumes it and produces the gap.'
        created_at:
          type: string
          title: Created At
          description: RFC 3339 UTC.
        paid_until:
          type: string
          title: Paid Until
          description: Events are produced for changes up to this time. RFC 3339 UTC.
        paused_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Paused At
        last_event_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Event At
        credits_per_day:
          type: integer
          title: Credits Per Day
          description: What a day of this watch costs (PRICING section 3.1).
        events_30d:
          type: integer
          title: Events 30D
          description: Events this watch produced in the last 30 days.
        undelivered_30d:
          type: integer
          title: Undelivered 30D
          description: Of those, events a webhook endpoint could not take after every retry (dead deliveries). They stay in GET /v1/events.
        pending_deliveries:
          type: integer
          title: Pending Deliveries
          description: Events waiting for a webhook attempt or a retry.
      type: object
      required:
      - id
      - entity
      - events
      - status
      - created_at
      - paid_until
      - credits_per_day
      - events_30d
      - undelivered_30d
      - pending_deliveries
      title: WatchDetail
    ErrorDetail:
      properties:
        code:
          type: string
          enum:
          - invalid_input
          - unsupported_type
          - unauthorized
          - forbidden
          - quota_exceeded
          - rate_limited
          - not_found
          - input_too_large
          - internal
          - degraded_unavailable
          - gone
          title: Code
        message:
          type: string
          title: Message
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
      type: object
      required:
      - code
      - message
      title: ErrorDetail
    WatchEntity:
      properties:
        type:
          type: string
          enum:
          - domain
          - phone
          - wallet
          - brand
          title: Type
          description: 'What is watched: a domain or host, an E.164 phone number, a wallet address, or a brand id of the lookalike registry.'
        value:
          type: string
          maxLength: 320
          minLength: 1
          title: Value
          description: As in the lookup endpoints. Stored in canonical form (the answer shows it).
      additionalProperties: false
      type: object
      required:
      - type
      - value
      title: WatchEntity
    WatchCreated:
      properties:
        id:
          type: string
          title: Id
          description: wch_ + a ULID.
        entity:
          $ref: '#/components/schemas/WatchEntity'
        events:
          items:
            type: string
            enum:
            - domain.ip_changed
            - domain.ns_changed
            - domain.down
            - domain.up
            - domain.parked
            - domain.listed
            - domain.delisted
            - domain.reregistered
            - domain.expiring
            - domain.expired
            - domain.held
            - phone.listed
            - phone.delisted
            - wallet.listed
            - wallet.delisted
            - wallet.sanctioned
            - brand.lookalike_registered
            - brand.lookalike_cert
            - brand.lookalike_live
          type: array
          title: Events
          description: The event types this watch produces.
        status:
          type: string
          enum:
          - active
          - paused
          title: Status
          description: 'paused: the balance could not pay a day; a top-up resumes it and produces the gap.'
        created_at:
          type: string
          title: Created At
          description: RFC 3339 UTC.
        paid_until:
          type: string
          title: Paid Until
          description: Events are produced for changes up to this time. RFC 3339 UTC.
        paused_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Paused At
        last_event_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Event At
        credits_per_day:
          type: integer
          title: Credits Per Day
          description: What a day of this watch costs (PRICING section 3.1).
        created:
          type: boolean
          title: Created
          description: 'false: a live watch on this entity existed; its event types were updated and nothing was charged.'
        credits:
          type: integer
          title: Credits
          description: 'Credits charged by this call: the first day of a new watch.'
      type: object
      required:
      - id
      - entity
      - events
      - status
      - created_at
      - paid_until
      - credits_per_day
      - created
      - credits
      title: WatchCreated
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
      - error
      title: ErrorResponse
    Deleted:
      properties:
        id:
          type: string
          title: Id
        deleted:
          type: boolean
          title: Deleted
      type: object
      required:
      - id
      - deleted
      title: Deleted
    WatchList:
      properties:
        watches:
          items:
            $ref: '#/components/schemas/Watch'
          type: array
          title: Watches
      type: object
      required:
      - watches
      title: WatchList
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: An API key, bw_…
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key