openapi: 3.0.3
info:
  title: 7AZZANI API
  description: |
    Enterprise-grade API platform for security scanning, performance testing, and web utilities.
    
    ## Authentication
    All API requests require an API key passed in the Authorization header:
    ```
    Authorization: Bearer 7AZ_your_api_key_here
    ```
    
    ## Rate Limits
    - 10 requests per second
    - 100 requests per minute
    - Unlimited daily requests
    
    Rate limit headers are included in all responses.
  version: 1.0.0
  contact:
    email: support@7azzani.com
    url: https://7azzani.com/support/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://7azzani.com
    description: Production server
  - url: http://localhost:8000
    description: Development server

tags:
  - name: Security Scanner
    description: Website vulnerability scanning
  - name: Speed Test
    description: Network speed testing
  - name: URL Shortener
    description: URL shortening service
  - name: Domain Lookup
    description: WHOIS and DNS lookup
  - name: QR Code
    description: QR code generation

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Get your key from /api/dashboard/

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Human-readable error message
      required:
        - error
        - message

    ScanRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: URL to scan
          example: https://example.com
        scan_type:
          type: string
          enum: [quick, standard, deep]
          default: quick
          description: Scan depth level
      required:
        - url

    ScanResponse:
      type: object
      properties:
        scan_id:
          type: string
          format: uuid
          description: Unique scan identifier
        url:
          type: string
          format: uri
        status:
          type: string
          enum: [pending, scanning, completed, failed]
        status_url:
          type: string
          description: URL to check scan status

    ScanStatus:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [pending, scanning, completed, failed]
        progress:
          type: integer
          minimum: 0
          maximum: 100
        completed:
          type: boolean
        failed:
          type: boolean
        duration:
          type: number
          description: Scan duration in seconds

    ScanReport:
      type: object
      properties:
        scan_id:
          type: string
          format: uuid
        url:
          type: string
        score:
          type: integer
          minimum: 0
          maximum: 100
          description: Security score
        vulnerabilities:
          type: array
          items:
            $ref: '#/components/schemas/Vulnerability'
        recommendations:
          type: array
          items:
            type: string

    Vulnerability:
      type: object
      properties:
        title:
          type: string
        severity:
          type: string
          enum: [critical, high, medium, low, info]
        description:
          type: string
        remediation:
          type: string

    SpeedTestRequest:
      type: object
      properties:
        server_id:
          type: integer
          description: Optional server ID for testing

    SpeedTestResult:
      type: object
      properties:
        test_id:
          type: string
          format: uuid
        download_speed:
          type: number
          description: Download speed in Mbps
        upload_speed:
          type: number
          description: Upload speed in Mbps
        ping:
          type: number
          description: Latency in milliseconds
        jitter:
          type: number
          description: Jitter in milliseconds
        server_location:
          type: string
        timestamp:
          type: string
          format: date-time

    ShortenRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Long URL to shorten
        custom_code:
          type: string
          description: Optional custom short code
      required:
        - url

    ShortenResponse:
      type: object
      properties:
        short_url:
          type: string
          format: uri
        short_code:
          type: string
        original_url:
          type: string
          format: uri
        created_at:
          type: string
          format: date-time

    LookupRequest:
      type: object
      properties:
        domain:
          type: string
          description: Domain to lookup
          example: example.com
        lookup_type:
          type: string
          enum: [whois, dns, all]
          default: all
      required:
        - domain

    LookupResponse:
      type: object
      properties:
        domain:
          type: string
        whois:
          type: object
          description: WHOIS information
        dns_records:
          type: object
          description: DNS records
        created_at:
          type: string
          format: date-time

    QRPreviewRequest:
      type: object
      properties:
        qr_type:
          type: string
          enum: [url, text, email, phone, wifi, vcard]
        content:
          type: string
          description: Content to encode
        style:
          type: object
          properties:
            color:
              type: string
              default: "#000000"
            background:
              type: string
              default: "#FFFFFF"
            logo_url:
              type: string
              format: uri
      required:
        - qr_type
        - content

    QRPreviewResponse:
      type: object
      properties:
        preview_url:
          type: string
          format: uri
        qr_code_base64:
          type: string
          description: Base64-encoded QR code image

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Authentication required
            message: Please provide a valid API key in the Authorization header

    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              message:
                type: string
              retry_after:
                type: integer
          example:
            error: Rate limit exceeded
            message: Maximum 10 requests per second
            retry_after: 1

security:
  - BearerAuth: []

paths:
  /api/scans/:
    get:
      tags:
        - Security Scanner
      summary: List all scans
      description: Retrieve a list of all security scans for the authenticated user
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, scanning, completed, failed]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: List of scans
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScanResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/scans/quick_scan/:
    post:
      tags:
        - Security Scanner
      summary: Start a quick security scan
      description: Initiate a security scan for the specified URL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanRequest'
      responses:
        '201':
          description: Scan initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /api/scans/{scan_id}/status/:
    get:
      tags:
        - Security Scanner
      summary: Get scan status
      parameters:
        - name: scan_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Scan status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanStatus'
        '404':
          description: Scan not found

  /api/scans/{scan_id}/report/:
    get:
      tags:
        - Security Scanner
      summary: Get scan report
      description: Retrieve the detailed vulnerability report for a completed scan
      parameters:
        - name: scan_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Scan report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanReport'
        '400':
          description: Scan not completed yet
        '404':
          description: Report not available

  /speedtest/api/v1/run/:
    post:
      tags:
        - Speed Test
      summary: Run speed test
      description: Initiate a network speed test
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeedTestRequest'
      responses:
        '200':
          description: Speed test result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeedTestResult'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /speedtest/api/v1/history/:
    get:
      tags:
        - Speed Test
      summary: Get speed test history
      description: Retrieve historical speed test results
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: List of speed test results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpeedTestResult'

  /shrinkit/api/shorten/:
    post:
      tags:
        - URL Shortener
      summary: Create short URL
      description: Shorten a long URL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShortenRequest'
      responses:
        '201':
          description: Short URL created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortenResponse'
        '400':
          description: Invalid URL
        '401':
          $ref: '#/components/responses/Unauthorized'

  /lookup/api/lookup/:
    post:
      tags:
        - Domain Lookup
      summary: Domain lookup
      description: Perform WHOIS and DNS lookup for a domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupRequest'
      responses:
        '200':
          description: Lookup results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupResponse'
        '400':
          description: Invalid domain
        '401':
          $ref: '#/components/responses/Unauthorized'

  /qr/api/preview/:
    post:
      tags:
        - QR Code
      summary: Generate QR code preview
      description: Generate a QR code preview image
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QRPreviewRequest'
      responses:
        '200':
          description: QR code preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QRPreviewResponse'
        '400':
          description: Invalid request
        '401':
          $ref: '#/components/responses/Unauthorized'
