{
  "openapi": "3.1.0",
  "info": {
    "title": "Autheona Trust Verification API",
    "description": "REST API for real-time email validation, trust verification, and risk assessment. Verify email addresses, detect typos, block disposable domains, check MX records, and calculate risk scores.",
    "version": "1.0.0",
    "contact": {
      "name": "Autheona Support",
      "url": "https://autheona.com/support"
    }
  },
  "servers": [
    {
      "url": "https://api.autheona.com/v1",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/intelligence": {
      "post": {
        "tags": ["User Trust"],
        "summary": "Verify user trust",
        "description": "Performs real-time verification of a user's trustworthiness based on their email address. Returns validation results, risk assessment data, and velocity tracking information.",
        "operationId": "verifyUserTrust",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrustVerificationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification completed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrustVerificationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your access token for API authentication"
      }
    },
    "schemas": {
      "TrustVerificationRequest": {
        "type": "object",
        "required": ["email_address"],
        "properties": {
          "email_address": {
            "type": "string",
            "description": "The email address to be validated/analyzed",
            "example": "user@example.com"
          },
          "custom_policy": {
            "$ref": "#/components/schemas/CustomPolicy",
            "description": "Optional custom validation rules for testing (not required for standard usage)"
          }
        }
      },
      "CustomPolicy": {
        "type": "object",
        "description": "Custom validation policy for testing environments",
        "properties": {
          "parent_rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PolicyRule"
            },
            "description": "List of validation rules to apply"
          },
          "stop_on_block": {
            "type": "boolean",
            "description": "Whether to stop processing when a block action is triggered",
            "example": true
          },
          "version": {
            "type": "string",
            "description": "Policy version",
            "example": "1.0"
          }
        }
      },
      "PolicyRule": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": ["allow", "block", "ignore"],
            "description": "Action to take when rule matches"
          },
          "field": {
            "type": "string",
            "description": "Field to evaluate"
          },
          "operator": {
            "type": "string",
            "description": "Comparison operator",
            "example": "=="
          },
          "target": {
            "type": "object",
            "description": "Target value to compare against"
          }
        }
      },
      "TrustVerificationResponse": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": ["allow", "block", "ignore"],
            "description": "The final verification verdict"
          },
          "email": {
            "$ref": "#/components/schemas/EmailAnalysis"
          },
          "velocity_by_email": {
            "$ref": "#/components/schemas/VelocityData"
          }
        }
      },
      "EmailAnalysis": {
        "type": "object",
        "properties": {
          "normalized": {
            "$ref": "#/components/schemas/NormalizedEmails"
          },
          "details": {
            "$ref": "#/components/schemas/EmailDetails"
          }
        }
      },
      "NormalizedEmails": {
        "type": "object",
        "description": "Various normalized versions of the email address",
        "properties": {
          "base": {
            "type": "string",
            "description": "The normalized base email address",
            "example": "john.doe@example.com"
          },
          "without_plus_addressing": {
            "type": ["string", "null"],
            "description": "Email address with plus addressing removed"
          },
          "without_dot_variations": {
            "type": ["string", "null"],
            "description": "Email address with dot variations removed (Gmail only)"
          },
          "without_punycode": {
            "type": ["string", "null"],
            "description": "Email address with punycode converted to Unicode"
          },
          "without_typo_mismatch": {
            "type": ["string", "null"],
            "description": "Email address with common typos corrected"
          }
        }
      },
      "EmailDetails": {
        "type": "object",
        "description": "Detailed analysis of the email address",
        "properties": {
          "deliverability": {
            "type": "string",
            "enum": ["deliverable", "undeliverable", "unknown"],
            "description": "Email deliverability status"
          },
          "local": {
            "$ref": "#/components/schemas/EmailLocalDetails"
          },
          "domain": {
            "$ref": "#/components/schemas/EmailDomainDetails"
          }
        }
      },
      "EmailLocalDetails": {
        "type": "object",
        "description": "Analysis of the email local part (before @)",
        "properties": {
          "fraud_pattern": {
            "type": ["string", "null"],
            "description": "Detected fraud pattern identifier (e.g., high_entropy:0.95)"
          },
          "mixed_script": {
            "type": ["string", "null"],
            "description": "Detected mixed script characters"
          },
          "has_fraud_pattern": {
            "type": "boolean",
            "description": "Indicates if a fraud pattern was detected"
          },
          "has_mixed_script": {
            "type": "boolean",
            "description": "Indicates if mixed scripts were detected"
          },
          "has_dot_variation": {
            "type": "boolean",
            "description": "Indicates if the local part contains dots"
          },
          "has_plus_addressing": {
            "type": "boolean",
            "description": "Indicates if plus addressing is used"
          },
          "has_special_characters": {
            "type": "boolean",
            "description": "Indicates if special characters are present"
          },
          "has_numeric": {
            "type": "boolean",
            "description": "Indicates if numeric characters are present"
          },
          "has_hyphen": {
            "type": "boolean",
            "description": "Indicates if hyphens are present"
          },
          "has_underscore": {
            "type": "boolean",
            "description": "Indicates if underscores are present"
          },
          "is_quoted": {
            "type": "boolean",
            "description": "Indicates if the local part is quoted"
          }
        }
      },
      "EmailDomainDetails": {
        "type": "object",
        "description": "Analysis of the email domain part (after @)",
        "properties": {
          "category": {
            "type": "string",
            "enum": ["business", "free", "education", "government", "disposable", "unknown"],
            "description": "Domain category classification"
          },
          "free_provider": {
            "type": ["string", "null"],
            "description": "The punycode representation of the domain if applicable"
          },
          "punycode_value": {
            "type": ["string", "null"],
            "description": "The punycode representation of the domain if applicable"
          },
          "has_valid_tld": {
            "type": "boolean",
            "description": "Indicates if the top-level domain is valid"
          },
          "has_website": {
            "type": "boolean",
            "description": "Indicates if the domain has an active website"
          },
          "has_punycode": {
            "type": "boolean",
            "description": "Indicates if the domain contains punycode"
          },
          "has_typo_mismatch": {
            "type": "boolean",
            "description": "Indicates if a typo was detected in the domain"
          },
          "is_ipv4": {
            "type": "boolean",
            "description": "Indicates if the domain is an IPv4 address"
          },
          "is_ipv6": {
            "type": "boolean",
            "description": "Indicates if the domain is an IPv6 address"
          },
          "is_only_numeric": {
            "type": "boolean",
            "description": "Indicates if the domain contains only numeric characters"
          },
          "is_single_label": {
            "type": "boolean",
            "description": "Indicates if the domain has only one label (no subdomains)"
          },
          "subdomain": {
            "$ref": "#/components/schemas/SubdomainDetails"
          }
        }
      },
      "SubdomainDetails": {
        "type": "object",
        "description": "Subdomain analysis details",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Number of subdomain levels"
          },
          "has_hyphen": {
            "type": "boolean",
            "description": "Indicates if subdomain contains hyphens"
          },
          "has_numeric": {
            "type": "boolean",
            "description": "Indicates if subdomain contains numeric characters"
          },
          "has_uuid": {
            "type": "boolean",
            "description": "Indicates if subdomain contains a UUID pattern"
          },
          "has_wildcard": {
            "type": "boolean",
            "description": "Indicates if subdomain contains a wildcard pattern"
          }
        }
      },
      "VelocityData": {
        "type": "object",
        "description": "Velocity tracking data for fraud detection",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VelocityItem"
            },
            "description": "List of historical email occurrences"
          },
          "count": {
            "type": "integer",
            "description": "Total count of occurrences"
          }
        }
      },
      "VelocityItem": {
        "type": "object",
        "properties": {
          "base_email": {
            "type": "string",
            "description": "The base email address for this occurrence"
          },
          "created_at": {
            "type": "integer",
            "description": "Unix timestamp of when this occurrence was recorded"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          },
          "code": {
            "type": "integer",
            "description": "HTTP status code"
          }
        }
      }
    }
  }
}