openapi: 3.0.0
info:
  title: Scam IQ API
  description: AI-powered scam detection API for automated fraud prevention
  version: 1.0.0
  contact:
    name: Scam IQ Support
    url: https://scamiq.app/api
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://scamiq.app/api/v1
    description: Production server

paths:
  /scan:
    post:
      summary: Analyze text for scam indicators
      description: Analyzes provided text content for scam patterns, phishing attempts, and fraud indicators
      operationId: scanMessage
      tags:
        - Scam Detection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                  description: Text content to analyze for scam patterns
                  example: "Congratulations! You've won $1000. Click here to claim..."
                options:
                  type: object
                  properties:
                    detailed_analysis:
                      type: boolean
                      description: Include detailed breakdown of indicators
                      default: true
                    include_confidence:
                      type: boolean
                      description: Include confidence scores
                      default: true
                    language:
                      type: string
                      description: Language of the text (ISO 639-1)
                      default: "en"
      responses:
        '200':
          description: Successful analysis
          content:
            application/json:
              schema:
                type: object
                properties:
                  risk_level:
                    type: string
                    enum: [safe, low, medium, high]
                    description: Overall risk assessment
                  risk_score:
                    type: number
                    minimum: 0
                    maximum: 10
                    description: Numerical risk score
                  confidence:
                    type: number
                    minimum: 0
                    maximum: 1
                    description: Confidence in the assessment
                  processing_time_ms:
                    type: integer
                    description: Processing time in milliseconds
                  indicators:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: Type of scam indicator
                        description:
                          type: string
                          description: Human-readable description
                        weight:
                          type: number
                          description: Importance weight of this indicator
                        matches:
                          type: array
                          items:
                            type: string
                          description: Specific text that triggered this indicator
                  recommendation:
                    type: string
                    description: Recommended action based on analysis
                  metadata:
                    type: object
                    properties:
                      api_version:
                        type: string
                      model_version:
                        type: string
        '400':
          description: Bad request - invalid input
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

tags:
  - name: Scam Detection
    description: Operations for detecting scams and fraud