Bewary Events API

openapi: 3.2.0
info:
  title: Bewary Events 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: Events
paths:
  /v1/events:
    get:
      tags:
      - Events
      summary: Events of the account's watches
      description: 'The durable record of every event, the same objects the webhooks deliver: pull it to follow the stream

        (store next_cursor, ask again), to catch up after downtime, or instead of a webhook. Free.'
      operationId: listEvents
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          description: 'next_cursor of the previous page; omitted: from the oldest event kept (13 months).'
          title: Cursor
        description: 'next_cursor of the previous page; omitted: from the oldest event kept (13 months).'
      - name: types
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 1000
          - type: 'null'
          description: Comma-separated event types, e.g. domain.down,domain.ip_changed.
          title: Types
        description: Comma-separated event types, e.g. domain.down,domain.ip_changed.
      - name: watch_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 40
          - type: 'null'
          description: Only this watch's events.
          title: Watch Id
        description: Only this watch's events.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 100
          title: Limit
      - 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: Events after the cursor, oldest first, and the cursor to continue from.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventPage'
        '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_events
components:
  schemas:
    EventPage:
      properties:
        schema_version:
          type: string
          title: Schema Version
        events:
          items:
            $ref: '#/components/schemas/Event'
          type: array
          title: Events
          description: Oldest first.
        next_cursor:
          type: string
          title: Next Cursor
          description: Pass as `cursor` for the events after these; returned even when no event came, so a poller keeps its place.
        has_more:
          type: boolean
          title: Has More
      type: object
      required:
      - schema_version
      - events
      - next_cursor
      - has_more
      title: EventPage
    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
    Event:
      properties:
        id:
          type: string
          title: Id
          description: evt_ + a ULID; the webhook-id header of its deliveries.
        type:
          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
          title: Type
        at:
          type: string
          title: At
          description: When Bewary observed the change. RFC 3339 UTC.
        watch_id:
          type: string
          title: Watch Id
        entity:
          $ref: '#/components/schemas/WatchEntity'
        before:
          anyOf:
          - $ref: '#/components/schemas/EventState'
          - type: 'null'
        after:
          anyOf:
          - $ref: '#/components/schemas/EventState'
          - type: 'null'
        datasets:
          items:
            type: string
            enum:
            - registration
            - dns
            - certificates
            - web_archive
            - threat_feeds
            - threat_aggregates
            - brand_registry
            - web_pages
            - ip_network
            - phone_numbering
            - us_numbering
            - phone_complaints
            - honeypot_lines
            - phone_reports_de
            - shortcodes
            - email_providers
            - breaches
            - wallet_reports
            - sanctions
            - issuer_freezes
            - community_reports
            - campaigns
            - text_model
            - platform_pages
            - iban_registry
            - bank_codes
            - app_stores
            - short_links
            - payment_profiles
          type: array
          title: Datasets
          description: The datasets the change was read from (section 6.1).
      additionalProperties: false
      type: object
      required:
      - id
      - type
      - at
      - watch_id
      - entity
      - datasets
      title: Event
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
      - error
      title: ErrorResponse
    EventState:
      properties:
        status:
          anyOf:
          - type: string
            enum:
            - live
            - gone
            - broken
            - parked
          - type: 'null'
          title: Status
          description: DNS status.
        a:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: A
          description: IPv4 addresses, sorted.
        ns:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Ns
          description: Name servers of the zone, sorted.
        registered_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Registered At
          description: 'The registry''s registration date; null: the registry has no registration. RFC 3339 UTC.'
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
          description: The registry's expiry date. RFC 3339 UTC.
        within_days:
          anyOf:
          - type: integer
            enum:
            - 7
            - 30
          - type: 'null'
          title: Within Days
          description: 'domain.expiring: the threshold crossed.'
        hold:
          anyOf:
          - type: string
            enum:
            - none
            - registrar
            - registry
            - both
          - type: 'null'
          title: Hold
          description: 'Who holds the name out of the DNS (E4''s daily registry pass): none, registry, registrar or both.'
        listed:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Listed
          description: On a Bewary scam list, as the lookup's `listed` fact.
        sanctioned:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Sanctioned
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
          description: 'Brand events: the lookalike domain.'
        technique:
          anyOf:
          - type: string
            enum:
            - brand_word
            - typo
            - brand_tld
            - homoglyph
            - mixed_script
          - type: 'null'
          title: Technique
          description: 'Brand events: how the name imitates the brand: next to a scam word, one letter off, on an abused TLD, spelled with look-alike characters (1.5.0: the last two and brand_tld).'
        origin:
          anyOf:
          - type: string
            enum:
            - cert
            - zone
          - type: 'null'
          title: Origin
          description: 'Brand events: first seen in a certificate or in a zone file.'
      additionalProperties: false
      type: object
      title: EventState
      description: '`before` and `after` of an event: only the fields the change is about are present.'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: An API key, bw_…
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key