Bewary Datasets API

openapi: 3.2.0
info:
  title: Bewary Datasets 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: Datasets
paths:
  /v1/datasets:
    get:
      tags:
      - Datasets
      summary: The datasets behind every answer, US or worldwide
      description: 'Every dataset Bewary answers from, marked US (US-only data, such as US phone complaints and

        the US short code directory) or WW (worldwide). Each signal in an answer names its dataset, and

        each entity lists the datasets checked for it with `in_coverage`. Free.'
      operationId: listDatasets
      responses:
        '200':
          description: 'Every dataset the API answers from: its geography (US or WW), kind, the entity types it covers and, for scam lists, how many entries are active now.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetList'
        '429':
          description: 'rate_limited: wait for Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - {}
components:
  schemas:
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
      - error
      title: ErrorResponse
    DatasetList:
      properties:
        schema_version:
          type: string
          title: Schema Version
        datasets:
          items:
            $ref: '#/components/schemas/DatasetInfo'
          type: array
          title: Datasets
      type: object
      required:
      - schema_version
      - datasets
      title: DatasetList
    DatasetInfo:
      properties:
        id:
          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
          title: Id
        name:
          type: string
          title: Name
        coverage:
          type: string
          pattern: ^(WW|[A-Z]{2})$
          title: Coverage
          description: 'WW: worldwide. A country code (US, DE): that country''s data only.'
        kind:
          type: string
          enum:
          - scam_list
          - reference
          - own_traffic
          - model
          title: Kind
        entity_types:
          items:
            type: string
          type: array
          title: Entity Types
        active_entries:
          anyOf:
          - type: integer
          - type: 'null'
          title: Active Entries
          description: Active entries now, for scam lists; null otherwise.
        refreshed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Refreshed At
          description: RFC 3339 UTC of the last refresh, where tracked.
        target_countries:
          anyOf:
          - additionalProperties:
              type: integer
            type: object
          - type: 'null'
          title: Target Countries
          description: Active entries aimed at each country (ISO 3166-1 alpha-2), from the national lists that name them; entries no national list names are not counted here. Null when none.
        entity_countries:
          anyOf:
          - additionalProperties:
              type: integer
            type: object
          - type: 'null'
          title: Entity Countries
          description: 'Phone datasets: entries by the number''s own country (phone_complaints: the 13-month directory, 1.9.0). bank_codes: the bank codes held per country (an IBAN from another country is outside it). Null otherwise.'
        checked_entries:
          anyOf:
          - type: integer
          - type: 'null'
          title: Checked Entries
          description: 'Domain datasets: active entries the hourly re-check has read so far (a full pass takes about a week). email_providers: throwaway-mail domains the re-check has read (a full pass takes about two days).'
        live_entries:
          anyOf:
          - type: integer
          - type: 'null'
          title: Live Entries
          description: Of checked_entries, those that still resolve (live or parked); for email_providers, the throwaway domains that still receive mail. The rest are kept as history.
        quarantined_entries:
          anyOf:
          - type: integer
          - type: 'null'
          title: Quarantined Entries
          description: 'Scam lists: entries held back from every answer because the list had a bad day (far more new entries than usual, or many top sites and shorteners among them). Kept, not served, until the list''s next clean day or a person lifts the hold. Null when none.'
        held_entries:
          anyOf:
          - type: integer
          - type: 'null'
          title: Held Entries
          description: 'Entries a lookup answers from now (1.9.0): a scam list''s active entries; phone_complaints: the US numbers with complaints in the last 13 months (a superset of the listed repeat offenders); email_providers: throwaway-mail domains; dns: domains with recorded DNS state and change history; us_numbering: US number blocks with their original carrier; shortcodes, brand_registry, iban_registry, bank_codes: the codes, brands, countries and banks held. Null where a source is read at lookup time and holds no list.'
      type: object
      required:
      - id
      - name
      - coverage
      - kind
      - entity_types
      title: DatasetInfo
    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
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: An API key, bw_…
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key