Bewary Backtest API

openapi: 3.2.0
info:
  title: Bewary Backtest 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: Backtest
paths:
  /v1/backtest:
    post:
      tags:
      - Backtest
      summary: Backtest a list of known-bad entities
      description: 'Send the domains, links, phone numbers, emails and wallets you already know are bad, each with the date you

        learned it (optional): the report says what Bewary would have answered on that date, since when we had it and

        how many hours before you, and what we would have missed. Answered from our stored history only. Up to 10,000

        items and 2 MB, as CSV, NDJSON or JSON. The first 1,000 items each month are free, then 1 credit each. The upload

        is deleted when the report is written; the report after 7 days.'
      operationId: createBacktest
      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:
        '202':
          description: Queued; the report is at `report`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BacktestCreated'
        '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'
        '413':
          description: 'input_too_large: the upload is over the limit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'rate_limited: wait for Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BacktestIn'
          text/csv:
            schema:
              type: string
            example: 'type,value,reported_at

              domain,usps-redeliver.top,2026-10-28

              phone,+18005551234,2026-10-27T14:00:00Z

              '
          application/x-ndjson:
            schema:
              type: string
            example: '{"value": "usps-redeliver.top", "reported_at": "2026-10-28"}

              '
      x-backtest:
        free_items_per_month: 1000
        max_items: 10000
        credits_per_item_after: 1
  /v1/backtest/{backtest_id}:
    get:
      tags:
      - Backtest
      summary: A backtest's report
      description: Any key of the account that made it. Free.
      operationId: getBacktest
      parameters:
      - name: backtest_id
        in: path
        required: true
        schema:
          type: string
          description: The id POST /v1/backtest gave.
          title: Backtest Id
        description: The id POST /v1/backtest gave.
      - 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 status, and once done the summary and one result per item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BacktestReport'
        '401':
          description: 'unauthorized: missing, revoked or wrong key, or an option that needs a key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 'not_found: there is nothing at this path'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 'rate_limited: wait for Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Backtest
      summary: Delete a backtest and its report now
      operationId: deleteBacktest
      parameters:
      - name: backtest_id
        in: path
        required: true
        schema:
          type: string
          title: Backtest 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: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: 'unauthorized: missing, revoked or wrong key, or an option that needs a key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 'not_found: there is nothing at this path'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BacktestIn:
      description: The JSON form of a backtest upload; text/csv and application/x-ndjson carry the same three fields.
      properties:
        items:
          items:
            $ref: '#/components/schemas/BacktestItemIn'
          maxItems: 10000
          minItems: 1
          title: Items
          type: array
      required:
      - items
      title: BacktestIn
      type: object
    BacktestItemError:
      properties:
        index:
          type: integer
          title: Index
        error:
          $ref: '#/components/schemas/ItemError'
      type: object
      required:
      - index
      - error
      title: BacktestItemError
    BacktestReport:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          enum:
          - queued
          - running
          - done
          - failed
          title: Status
        created_at:
          type: string
          title: Created At
        finished_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Finished At
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
        items:
          type: integer
          title: Items
        valid:
          type: integer
          title: Valid
        free_items:
          type: integer
          title: Free Items
        credits:
          type: integer
          title: Credits
        history:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/HistoryStart'
            type: object
          - type: 'null'
          title: History
          description: Where our data for each type begins.
        summary:
          anyOf:
          - $ref: '#/components/schemas/BacktestSummary'
          - type: 'null'
        results:
          items:
            anyOf:
            - $ref: '#/components/schemas/BacktestResult'
            - $ref: '#/components/schemas/BacktestItemError'
          type: array
          title: Results
          description: In upload order; empty until the report is done.
      type: object
      required:
      - id
      - status
      - created_at
      - items
      - valid
      - free_items
      - credits
      - results
      title: BacktestReport
      description: 'GET /v1/backtest/{id}. Kept 7 days after it is ready; the upload itself is deleted when the report is

        written.'
    ItemError:
      properties:
        code:
          type: string
          enum:
          - invalid_input
          - unsupported_type
          title: Code
      type: object
      required:
      - code
      title: ItemError
    HistoryStart:
      properties:
        from:
          anyOf:
          - type: string
          - type: 'null'
          title: From
          description: Our earliest record for this type, RFC 3339 UTC.
      type: object
      title: HistoryStart
    BacktestCreated:
      properties:
        id:
          type: string
          title: Id
          description: bt_ + a ULID.
        status:
          type: string
          enum:
          - queued
          - running
          - done
          - failed
          title: Status
        items:
          type: integer
          title: Items
        valid:
          type: integer
          title: Valid
        invalid:
          type: integer
          title: Invalid
          description: 'Items that are not a value of their type: reported, never charged.'
        free_items:
          type: integer
          title: Free Items
          description: Items covered by this month's free allowance.
        credits:
          type: integer
          title: Credits
          description: 'Credits charged: one per valid item past the free allowance.'
        report:
          type: string
          title: Report
          description: Path of the report.
      type: object
      required:
      - id
      - status
      - items
      - valid
      - invalid
      - free_items
      - credits
      - report
      title: BacktestCreated
    BacktestItemIn:
      properties:
        type:
          anyOf:
          - enum:
            - domain
            - url
            - phone
            - email
            - wallet
            type: string
          - type: 'null'
          default: null
          description: Inferred from the value when absent.
          title: Type
        value:
          maxLength: 4000
          title: Value
          type: string
        reported_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: 'When you learned it was bad: RFC 3339 or YYYY-MM-DD (UTC).'
          title: Reported At
      required:
      - value
      title: BacktestItemIn
      type: object
    BacktestSummary:
      properties:
        items:
          type: integer
          title: Items
        valid:
          type: integer
          title: Valid
        invalid:
          type: integer
          title: Invalid
        outcomes:
          additionalProperties:
            type: integer
          type: object
          title: Outcomes
          description: Items by outcome.
        listed_now:
          type: integer
          title: Listed Now
          description: Items a lookup asserts now (listed or sanctioned).
        lead_hours:
          $ref: '#/components/schemas/BacktestLeads'
        by_type:
          additionalProperties:
            $ref: '#/components/schemas/BacktestTypeSummary'
          type: object
          title: By Type
      type: object
      required:
      - items
      - valid
      - invalid
      - outcomes
      - listed_now
      - lead_hours
      - by_type
      title: BacktestSummary
    BacktestTypeSummary:
      properties:
        items:
          type: integer
          title: Items
        outcomes:
          additionalProperties:
            type: integer
          type: object
          title: Outcomes
        listed_now:
          type: integer
          title: Listed Now
      type: object
      required:
      - items
      - outcomes
      - listed_now
      title: BacktestTypeSummary
    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
    BacktestResult:
      properties:
        index:
          type: integer
          title: Index
          description: The item's position in the upload.
        type:
          type: string
          enum:
          - domain
          - url
          - phone
          - email
          - wallet
          title: Type
        value:
          type: string
          title: Value
          description: As uploaded.
        normalized:
          type: string
          title: Normalized
          description: Our canonical form (the email's domain for an email).
        reported_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Reported At
          description: Your date, RFC 3339 UTC.
        outcome:
          type: string
          enum:
          - caught_before
          - caught_after
          - caught
          - flagged
          - missed
          - before_history
          title: Outcome
          description: 'caught_before: on your date we listed it. caught_after: we listed it only later. caught (no date): we listed it. flagged: only a caution or a caller-ID report. missed. before_history: your date is before our data for this type begins.'
        answer_then:
          anyOf:
          - type: string
            enum:
            - listed
            - sanctioned
            - frozen
            - caution
            - caller_id
            - not_listed
          - type: 'null'
          title: Answer Then
          description: What a lookup on your date answered.
        answer_now:
          type: string
          enum:
          - listed
          - sanctioned
          - frozen
          - caution
          - caller_id
          - not_listed
          title: Answer Now
          description: What a lookup answers now.
        first_seen:
          anyOf:
          - type: string
          - type: 'null'
          title: First Seen
          description: The earliest we saw it at all, a certificate included.
        first_listed:
          anyOf:
          - type: string
          - type: 'null'
          title: First Listed
          description: When we first asserted it (listed or sanctioned).
        lead_hours:
          anyOf:
          - type: number
          - type: 'null'
          title: Lead Hours
          description: 'Your date minus our listing, in hours: positive when we had it first, negative when we listed it later.'
        severity:
          anyOf:
          - type: string
            enum:
            - info
            - low
            - medium
            - high
            - critical
          - type: 'null'
          title: Severity
        reason_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason Code
          description: LISTED_BLOCKLIST, WALLET_SANCTIONED, WALLET_FROZEN_BY_ISSUER (1.9.0), LISTED_CAUTION or PHONE_REPORTED_CALLER_ID.
      type: object
      required:
      - index
      - type
      - value
      - normalized
      - outcome
      - answer_now
      title: BacktestResult
    BacktestLeads:
      properties:
        caught_before:
          anyOf:
          - $ref: '#/components/schemas/LeadStats'
          - type: 'null'
        caught_after:
          anyOf:
          - $ref: '#/components/schemas/LeadStats'
          - type: 'null'
      type: object
      title: BacktestLeads
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
      - error
      title: ErrorResponse
    LeadStats:
      properties:
        count:
          type: integer
          title: Count
        median:
          type: number
          title: Median
        p25:
          type: number
          title: P25
        p75:
          type: number
          title: P75
        max:
          type: number
          title: Max
      type: object
      required:
      - count
      - median
      - p25
      - p75
      - max
      title: LeadStats
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: An API key, bw_…
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key