Bewary Calibration API

openapi: 3.2.0
info:
  title: Bewary Calibration 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: Calibration
paths:
  /v1/calibration/site:
    get:
      tags:
      - Calibration
      summary: How the site score becomes a probability
      description: 'The calibration behind `site.p_scam_site` on /v1/domain: for each band of the domain verdict''s raw score, how

        many labelled hosts fell in it, how many were scam sites, the probability served for it and the band''s 95%

        interval. Refit as the nightly audit labels more hosts. Free.'
      operationId: siteCalibration
      responses:
        '200':
          description: Every score band of the domain verdict, the labelled hosts in it, how many were scam sites, the probability served and its 95% interval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteCalibration'
        '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
    SiteCalibration:
      properties:
        schema_version:
          type: string
          title: Schema Version
        version:
          type: string
          title: Version
          description: The fit, e.g. site-cal-20261030-702; `site.calibration` names it.
        fitted_at:
          type: string
          title: Fitted At
          description: When it was fitted, RFC 3339 UTC.
        population:
          type: string
          title: Population
          description: Which hosts it applies to.
        labels:
          type: string
          title: Labels
          description: How the labelled hosts were labelled.
        points:
          type: integer
          minimum: 0.0
          title: Points
          description: Labelled hosts in the fit.
        scam_sites:
          type: integer
          minimum: 0.0
          title: Scam Sites
          description: How many of them were scam or compromised sites.
        confidence:
          type: number
          title: Confidence
          description: The confidence of every band's interval.
        bands:
          items:
            $ref: '#/components/schemas/CalibrationBand'
          type: array
          title: Bands
      type: object
      required:
      - schema_version
      - version
      - fitted_at
      - population
      - labels
      - points
      - scam_sites
      - confidence
      - bands
      title: SiteCalibration
      description: 'GET /v1/calibration/site (1.4.0): how the domain verdict''s score maps to the probability `site.p_scam_site`

        serves, and what each band''s labelled hosts were (docs/b2b/PRECISION.md).'
    CalibrationBand:
      properties:
        score_from:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Score From
          description: The band's lowest score (inclusive).
        score_to:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Score To
          description: The band's highest score (exclusive, but 1.0 is in the top band).
        hosts:
          type: integer
          minimum: 0.0
          title: Hosts
          description: Labelled hosts whose score fell in this band.
        scam_sites:
          type: integer
          minimum: 0.0
          title: Scam Sites
          description: How many of them were scam or compromised sites.
        p_low:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: P Low
          description: 95% interval of the band's scam share, low end (Clopper-Pearson).
        p_high:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: P High
          description: 95% interval of the band's scam share, high end.
        p_scam_site:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: P Scam Site
          description: The probability served for a score in this band.
      additionalProperties: false
      type: object
      required:
      - score_from
      - score_to
      - hosts
      - scam_sites
      - p_low
      - p_high
      - p_scam_site
      title: CalibrationBand
    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