openapi: 3.0.3
info:
  title: detectip.ai Bot Detection API
  description: >
    Explainable bot detection built on deep network fingerprinting (JA4/JA4H/JA4T/QUIC),
    behavioral telemetry, IP intelligence and a self-calibrating risk model.
    Add the collector tag to your page, then fetch a verdict by session token.
  version: "1.0.0"
  contact:
    name: detectip.ai
    url: https://detectip.ai
servers:
  - url: https://detectip.ai
security:
  - ApiKeyAuth: []
paths:
  /api/v1/verdict:
    get:
      summary: Get an explainable bot-vs-human verdict for a session
      parameters:
        - name: token
          in: query
          required: true
          schema: { type: string }
          description: The session token captured by the collector tag.
      responses:
        "200":
          description: Verdict
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Verdict" }
        "401": { description: Missing or invalid API key }
        "402": { description: Monthly quota exceeded }
        "404": { description: No captured session for token }
        "429": { description: Rate limit exceeded }
  /api/v1/usage:
    get:
      summary: Current month usage and quota for the calling tenant
      responses:
        "200":
          description: Usage
          content:
            application/json:
              schema:
                type: object
                properties:
                  tier: { type: string }
                  used: { type: integer }
                  limit: { type: integer }
                  remaining: { type: integer }
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    Signal:
      type: object
      properties:
        name: { type: string, example: non_browser_tls_stack }
        layer: { type: string, example: tls }
        llr: { type: number, format: float, example: 1.7 }
        detail: { type: string }
    Verdict:
      type: object
      properties:
        token: { type: string }
        score: { type: integer, minimum: 0, maximum: 100, example: 96 }
        band:
          type: string
          enum: [human, suspicious, automated, known-bot]
        action:
          type: string
          enum: [allow, challenge, block]
          description: Recommended enforcement for this client.
        hard_rule_hit: { type: string }
        signals:
          type: array
          items: { $ref: "#/components/schemas/Signal" }
