{
  "openapi": "3.1.0",
  "info": {
    "title": "HumanizerAI API",
    "description": "Authenticated text detection and rewriting API. Scores estimate AI-like patterns; they do not prove authorship or guarantee results from other detectors.",
    "version": "1.0.0",
    "contact": {
      "name": "HumanizerAI Support",
      "url": "https://humanizerai.com/support",
      "email": "support@humanizerai.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://humanizerai.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://humanizerai.com/api/v1",
      "description": "Production API"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/detect": {
      "post": {
        "operationId": "detectAI",
        "summary": "Detect AI-generated content",
        "description": "Analyze text to determine if it was written by AI. Returns a score from 0-100 (higher = more likely AI) along with detailed metrics including perplexity, burstiness, and readability.",
        "tags": [
          "Detection"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DetectRequest"
              },
              "example": {
                "text": "Artificial intelligence has revolutionized numerous industries by enabling machines to perform tasks that previously required human intelligence."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Detection analysis completed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DetectResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing or invalid text",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - API access requires Pro or Business plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/humanize": {
      "post": {
        "operationId": "humanizeText",
        "summary": "Humanize AI-generated text",
        "description": "Rewrite text. Consumes credits based on word count. Intensities: light, medium, aggressive. Review the output for factual fidelity.",
        "tags": [
          "Humanization"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HumanizeRequest"
              },
              "example": {
                "text": "Artificial intelligence has revolutionized numerous industries by enabling machines to perform tasks that previously required human intelligence.",
                "intensity": "medium"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Text humanized successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanizeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing text or invalid intensity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - insufficient credits or plan doesn't include API access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InsufficientCreditsError"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/credits": {
      "get": {
        "operationId": "checkCredits",
        "summary": "Check remaining credits and plan",
        "responses": {
          "200": {
            "description": "Current balance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "credits": {
                      "type": "object",
                      "properties": {
                        "subscription": {
                          "type": "number"
                        },
                        "topUp": {
                          "type": "number"
                        },
                        "total": {
                          "type": "number"
                        }
                      }
                    },
                    "plan": {
                      "type": "string"
                    },
                    "billingCycleEnd": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "Requires Pro or Business"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "API key authentication. Use your API key as the bearer token. Keys start with 'hum_'."
      }
    },
    "schemas": {
      "DetectRequest": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "The text to analyze for AI detection. Maximum 10,000 words.",
            "minLength": 1
          }
        }
      },
      "DetectResponse": {
        "type": "object",
        "properties": {
          "score": {
            "type": "number",
            "description": "AI-like pattern score from 0 to 100; not a calibrated probability of authorship.",
            "minimum": 0,
            "maximum": 100,
            "example": 85
          },
          "metrics": {
            "type": "object",
            "description": "Detailed detection metrics",
            "properties": {
              "perplexity": {
                "type": "number",
                "description": "Text predictability score. Lower values indicate AI-like patterns.",
                "example": 42.5
              },
              "burstiness": {
                "type": "number",
                "description": "Sentence length variation. Human text typically has higher burstiness (0.8+).",
                "example": 0.35
              },
              "readability": {
                "type": "number",
                "description": "Flesch readability score. AI text tends to have unnaturally consistent scores.",
                "example": 65.2
              },
              "satPercent": {
                "type": "number",
                "description": "Percentage of advanced/SAT vocabulary words.",
                "example": 12.5
              },
              "simplicity": {
                "type": "number",
                "description": "Ratio of common words used.",
                "example": 78.3
              },
              "ngramScore": {
                "type": "number",
                "description": "N-gram pattern detection score. Higher values indicate AI fingerprints.",
                "example": 0.15
              },
              "averageSentenceLength": {
                "type": "number",
                "description": "Average number of words per sentence.",
                "example": 18.4
              }
            }
          },
          "verdict": {
            "type": "string",
            "description": "Human-readable verdict based on the score",
            "example": "likely_ai"
          },
          "wordsProcessed": {
            "type": "integer",
            "description": "Number of words analyzed",
            "example": 250
          }
        }
      },
      "HumanizeRequest": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "The AI-generated text to humanize. Maximum 10,000 words.",
            "minLength": 1
          },
          "intensity": {
            "type": "string",
            "description": "Humanization intensity level",
            "enum": [
              "light",
              "medium",
              "aggressive"
            ],
            "default": "medium"
          }
        }
      },
      "HumanizeResponse": {
        "type": "object",
        "properties": {
          "humanizedText": {
            "type": "string",
            "description": "The transformed text that sounds naturally human",
            "example": "AI has genuinely changed how we work across so many fields. Machines now handle stuff we thought only humans could do."
          },
          "score": {
            "type": "object",
            "description": "AI detection scores before and after humanization",
            "properties": {
              "before": {
                "type": "integer",
                "description": "AI score of the original text",
                "example": 85
              },
              "after": {
                "type": "integer",
                "description": "AI score after humanization",
                "example": 15
              }
            }
          },
          "wordsProcessed": {
            "type": "integer",
            "description": "Number of words processed (equals credits used)",
            "example": 250
          },
          "credits": {
            "type": "object",
            "description": "Updated credit balance after the operation",
            "properties": {
              "subscriptionRemaining": {
                "type": "integer",
                "description": "Words remaining in subscription allowance",
                "example": 49750
              },
              "topUpRemaining": {
                "type": "integer",
                "description": "Words remaining from top-up credits",
                "example": 0
              },
              "totalRemaining": {
                "type": "integer",
                "description": "Total words remaining (subscription + top-up)",
                "example": 49750
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer",
            "description": "HTTP status code",
            "example": 400
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Text is required"
          }
        }
      },
      "InsufficientCreditsError": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer",
            "example": 403
          },
          "message": {
            "type": "string",
            "example": "insufficient_credits"
          },
          "data": {
            "type": "object",
            "properties": {
              "required": {
                "type": "integer",
                "description": "Number of credits needed for this request",
                "example": 500
              },
              "totalAvailable": {
                "type": "integer",
                "description": "Total credits available",
                "example": 200
              },
              "subscriptionRemaining": {
                "type": "integer",
                "example": 150
              },
              "topUpRemaining": {
                "type": "integer",
                "example": 50
              },
              "plan": {
                "type": "string",
                "example": "pro"
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Detection",
      "description": "AI content detection endpoints"
    },
    {
      "name": "Humanization",
      "description": "AI text humanization endpoints"
    }
  ]
}