Bewary Bulk API

openapi: 3.2.0
info:
  title: Bewary Bulk 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: Bulk
paths:
  /v1/bulk:
    get:
      tags:
      - Bulk
      summary: What the bulk files hold now
      description: 'Our verdicts as files: a CSV of domains, links, phone numbers and wallets, a DNS response policy zone (RPZ)

        of domains, and STIX 2.1 indicators of domains and links (also as a TAXII 2.1 collection at /v1/taxii2/). Rebuilt

        every hour; full files, and deltas after any version of the last 30 days. Free with any key; the files need a

        key enabled for bulk and a day pass.'
      operationId: bulkManifest
      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: The latest version, recent versions, entries by type, the formats and the price.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkManifest'
        '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'
  /v1/bulk/notices:
    get:
      tags:
      - Bulk
      summary: Licence notices that travel with the bulk files
      description: 'Plain text. The notices some licences ask to travel with copies of their data; every RPZ and STIX file carries

        them too. Free.'
      operationId: bulkNotices
      responses:
        '200':
          description: Successful Response
          content:
            text/plain:
              schema:
                type: string
      security:
      - {}
  /v1/bulk/{fmt}:
    get:
      tags:
      - Bulk
      summary: Download a bulk file (full or delta)
      description: 'The latest version of a bulk file. Needs a key enabled for bulk; the day''s first file buys the account''s day

        pass (5,000 credits), later files that day are free. Headers: X-Bulk-Version, X-Bulk-Entries, ETag.'
      operationId: bulkFile
      parameters:
      - name: fmt
        in: path
        required: true
        schema:
          type: string
          description: csv, rpz or stix.
          title: Fmt
        description: csv, rpz or stix.
      - name: type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Entity types, comma separated: csv domain,url,phone,wallet; rpz domain; stix domain,url. Default: all the format carries.'
          title: Type
        description: 'Entity types, comma separated: csv domain,url,phone,wallet; rpz domain; stix domain,url. Default: all the format carries.'
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 0
          - type: 'null'
          description: 'A version id: only what was added, changed or removed after it (csv and stix). The CSV then starts with a `change` column.'
          title: Since
        description: 'A version id: only what was added, changed or removed after it (csv and stix). The CSV then starts with a `change` column.'
      - 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
      - name: if-none-match
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-None-Match
      - name: accept-encoding
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Accept-Encoding
      responses:
        '200':
          description: 'The file: text/csv, text/dns (an RPZ zone) or application/stix+json;version=2.1. Gzipped when the request accepts gzip.'
        '304':
          description: Not modified (If-None-Match).
        '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'
        '403':
          description: 'forbidden: the key is not enabled for this (bulk delivery: PATCH /v1/keys/{id})'
          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-bulk-day-credits: 5000
components:
  schemas:
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
      - error
      title: ErrorResponse
    BulkFormat:
      properties:
        format:
          type: string
          enum:
          - csv
          - rpz
          - stix
          title: Format
        media_type:
          type: string
          title: Media Type
        types:
          items:
            type: string
            enum:
            - domain
            - url
            - phone
            - wallet
          type: array
          title: Types
          description: Entity types the format carries.
        full:
          type: string
          title: Full
          description: Path of the full file.
        delta:
          anyOf:
          - type: string
          - type: 'null'
          title: Delta
          description: Path of a delta after a version, or null (RPZ is served whole).
      type: object
      required:
      - format
      - media_type
      - types
      - full
      title: BulkFormat
    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
    BulkManifest:
      properties:
        schema_version:
          type: string
          title: Schema Version
        policy:
          type: string
          title: Policy
          description: The licence policy version the entries passed (app/licences.py).
        version:
          anyOf:
          - $ref: '#/components/schemas/BulkVersion'
          - type: 'null'
          description: The latest version, or null before the first build.
        versions:
          items:
            $ref: '#/components/schemas/BulkVersion'
          type: array
          title: Versions
          description: Recent versions, newest first; deltas reach back 30 days.
        types:
          additionalProperties:
            type: integer
          type: object
          title: Types
          description: Current entries by entity type.
        formats:
          items:
            $ref: '#/components/schemas/BulkFormat'
          type: array
          title: Formats
        price:
          $ref: '#/components/schemas/BulkPrice'
        key_enabled:
          type: boolean
          title: Key Enabled
          description: This key may download the files (PATCH /v1/keys/{id}).
        notices:
          type: string
          title: Notices
          description: Licence notices that travel with the files.
      type: object
      required:
      - schema_version
      - policy
      - versions
      - types
      - formats
      - price
      - key_enabled
      - notices
      title: BulkManifest
      description: 'GET /v1/bulk: what the bulk files hold now. Free with any key.'
    BulkPrice:
      properties:
        credits_per_day:
          type: integer
          title: Credits Per Day
          description: One day pass per account per UTC day covers every format, full and delta, and the TAXII collection.
        pass_today:
          type: boolean
          title: Pass Today
          description: This account already holds today's pass.
      type: object
      required:
      - credits_per_day
      - pass_today
      title: BulkPrice
    BulkVersion:
      properties:
        id:
          type: integer
          title: Id
          description: Increases with every change; the RPZ serial. Pass it as `since` for a delta.
        created_at:
          type: string
          title: Created At
          description: RFC 3339 UTC.
        entries:
          type: integer
          title: Entries
          description: Entries in this version.
        added:
          type: integer
          title: Added
        changed:
          type: integer
          title: Changed
        removed:
          type: integer
          title: Removed
      type: object
      required:
      - id
      - created_at
      - entries
      - added
      - changed
      - removed
      title: BulkVersion
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: An API key, bw_…
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key