{
  "openapi": "3.1.0",
  "info": {
    "title": "HumanText API",
    "version": "1.0.0",
    "description": "REST API for AI text humanization, AI detection, and usage. Base URL: https://api.humantext.click",
    "contact": {
      "name": "HumanText Support",
      "email": "hello.humantext@gmail.com",
      "url": "https://humantext.click/docs"
    }
  },
  "servers": [
    {
      "url": "https://api.humantext.click",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "Humanize", "description": "Rewrite AI-generated text into natural writing" },
    { "name": "Detect", "description": "Score text for AI authorship" },
    { "name": "Usage", "description": "Account word allowance and plan tier" }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Dashboard API key. Example: Authorization: Bearer ht_live_..."
      }
    },
    "schemas": {
      "WordsRemaining": {
        "type": "object",
        "properties": {
          "included": { "type": "integer", "example": 124986 },
          "topup": { "type": "integer", "example": 0 },
          "total": { "type": "integer", "example": 124986 }
        }
      },
      "HumanizeRequest": {
        "type": "object",
        "required": ["text"],
        "properties": {
          "text": {
            "type": "string",
            "description": "AI-generated text to humanize",
            "example": "Artificial intelligence has revolutionized the way we approach content creation and digital communication."
          },
          "tone": {
            "type": "string",
            "description": "Optional writing tone",
            "example": "professional",
            "enum": ["professional", "casual", "academic", "friendly", "formal"]
          }
        }
      },
      "HumanizeResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "hum_a1b2c3d4e5f6" },
          "created": { "type": "integer", "example": 1778533901580 },
          "results": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["AI has changed how we create content and communicate online."]
          },
          "scores": {
            "oneOf": [
              { "type": "array", "items": { "type": "number" } },
              { "type": "null" }
            ]
          },
          "input_words": { "type": "integer", "example": 14 },
          "words_remaining": { "$ref": "#/components/schemas/WordsRemaining" }
        }
      },
      "DetectRequest": {
        "type": "object",
        "required": ["text"],
        "properties": {
          "text": {
            "type": "string",
            "example": "AI has rapidly transformed modern business. Many teams now depend on it every single day."
          },
          "include_sentences": {
            "type": "boolean",
            "default": false,
            "description": "When true, include per-sentence AI probabilities"
          }
        }
      },
      "DetectSentence": {
        "type": "object",
        "properties": {
          "text": { "type": "string" },
          "ai_prob": { "type": "number", "minimum": 0, "maximum": 1 }
        }
      },
      "DetectResponse": {
        "type": "object",
        "properties": {
          "scanId": { "type": "string" },
          "version": { "type": "string" },
          "ai_probability": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "0–1 where 1 = AI"
          },
          "predicted_class": {
            "type": "string",
            "enum": ["ai", "human", "mixed"]
          },
          "class_probabilities": {
            "type": "object",
            "additionalProperties": { "type": "number" }
          },
          "request_meta": { "type": "object", "additionalProperties": true },
          "language": { "type": "string" },
          "sentences": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/DetectSentence" }
          }
        }
      },
      "UsageResponse": {
        "type": "object",
        "properties": {
          "included_words": { "type": "integer", "example": 400000 },
          "words_used_this_cycle": { "type": "integer", "example": 18311 },
          "topup_balance": { "type": "integer", "example": 125000 },
          "tier": { "type": "string", "example": "api_premium" },
          "version": { "type": "string", "example": "v1.0" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    }
  },
  "security": [{ "BearerAuth": [] }],
  "paths": {
    "/v1/humanize": {
      "post": {
        "tags": ["Humanize"],
        "summary": "Humanize AI-generated text",
        "description": "Rewrite input text so it reads as naturally human. Billed per input word.",
        "operationId": "humanizeText",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/HumanizeRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Humanized output",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HumanizeResponse" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "402": {
            "description": "Insufficient word balance",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    },
    "/v1/detect": {
      "post": {
        "tags": ["Detect"],
        "summary": "Detect AI-authored text",
        "description": "Score a passage for AI authorship. ai_probability runs 0–1 where 1 = AI. Billed per input word.",
        "operationId": "detectAiText",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DetectRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Detection result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DetectResponse" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": ["Usage"],
        "summary": "Get account usage",
        "description": "Read remaining words, plan tier, and top-up balance for the authenticated API key.",
        "operationId": "getUsage",
        "responses": {
          "200": {
            "description": "Usage snapshot",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UsageResponse" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          }
        }
      }
    }
  }
}