openapi: 3.0.3
info:
  title: Risk Score API
  version: v2.0
  description: Automated, signal-based domain risk indicator. No guarantees. No advice. No interpretation.
servers:
  - url: https://api.yourdomain.com
paths:
  /risk-score:
    post:
      summary: Calculate domain risk score
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  example: https://example.com
      responses:
        "200":
          description: Risk score response
          content:
            application/json:
              schema:
                type: object
                required: [riskScore, riskLevel, signals, version]
                properties:
                  riskScore:
                    type: integer
                    minimum: 0
                    maximum: 100
                    example: 42
                  riskLevel:
                    type: string
                    enum: [low, medium, high]
                    example: medium
                  signals:
                    type: array
                    items:
                      type: string
                    example:
                      - whois_redacted_or_privacy
                      - recent_rdap_record_update
                  version:
                    type: string
                    example: v2.0
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: invalid_url
        "401":
          description: Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: invalid_api_key
        "429":
          description: Quota exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: quota_exceeded
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
