{
 "openapi": "3.1.0",
 "info": {
  "title": "tells",
  "version": "0.5.0",
  "description": "Find the phrases that make writing read as AI-written, and fix only those sentences. Checking is free and needs no key. A flagged phrase is not proof that AI wrote a text.",
  "license": {
   "name": "MIT",
   "identifier": "MIT"
  },
  "contact": {
   "name": "Nexugen",
   "url": "https://nexugen.app"
  }
 },
 "servers": [
  {
   "url": "https://tells.nexugen.app"
  }
 ],
 "paths": {
  "/v1/lint": {
   "post": {
    "operationId": "checkText",
    "summary": "Check text for AI tells",
    "description": "Returns each flagged phrase with character offsets, its rule, why it stands out and what to write instead, plus the human signals present and missing.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "text"
        ],
        "properties": {
         "text": {
          "type": "string",
          "description": "The text to check."
         },
         "register": {
          "type": "string",
          "enum": [
           "auto",
           "casual",
           "professional",
           "technical",
           "marketing"
          ],
          "default": "auto",
          "description": "Kind of writing. auto guesses from the text."
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Check result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/LintResult"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/rewrite": {
   "post": {
    "operationId": "fixText",
    "summary": "Fix only the flagged sentences",
    "description": "Rewrites only the flagged sentences, keeping every fact. A few free tries a day per address; more with a free key. With a voice profile, rewrites the draft in that style.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "text"
        ],
        "properties": {
         "text": {
          "type": "string"
         },
         "register": {
          "type": "string",
          "enum": [
           "auto",
           "casual",
           "professional",
           "technical",
           "marketing"
          ],
          "default": "auto",
          "description": "Kind of writing. auto guesses from the text."
         },
         "voice": {
          "type": "object",
          "description": "Profile from buildVoice."
         },
         "polish": {
          "type": "boolean"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Rewrite result",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/RewriteResult"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/voice": {
   "post": {
    "operationId": "buildVoice",
    "summary": "Learn a writing style from samples",
    "description": "At least 5 samples and 600 words. Nothing is stored. Returns a profile to pass to fixText as voice.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "samples"
        ],
        "properties": {
         "samples": {
          "type": "array",
          "items": {
           "type": "string"
          }
         },
         "name": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Voice profile",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/keys": {
   "post": {
    "operationId": "getFreeKey",
    "summary": "Get a free key for more rewrites a day",
    "responses": {
     "200": {
      "description": "Key",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "key": {
           "type": "string"
          },
          "dailyRewrites": {
           "type": "integer"
          },
          "note": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/rules": {
   "get": {
    "operationId": "listRules",
    "summary": "Every rule tells checks",
    "responses": {
     "200": {
      "description": "Rules",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "object",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       }
      }
     }
    }
   },
   "Finding": {
    "type": "object",
    "properties": {
     "ruleId": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "severity": {
      "type": "string",
      "enum": [
       "error",
       "warning",
       "info"
      ]
     },
     "start": {
      "type": "integer"
     },
     "end": {
      "type": "integer"
     },
     "line": {
      "type": "integer"
     },
     "column": {
      "type": "integer"
     },
     "match": {
      "type": "string",
      "description": "The flagged phrase."
     },
     "fix": {
      "type": "string",
      "description": "What to write instead."
     }
    }
   },
   "LintResult": {
    "type": "object",
    "properties": {
     "findings": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Finding"
      }
     },
     "words": {
      "type": "integer"
     },
     "score": {
      "type": "number"
     },
     "grade": {
      "type": "string"
     },
     "register": {
      "type": "string"
     },
     "human": {
      "type": "object",
      "additionalProperties": true,
      "description": "Human signals present and missing, and the human-pattern score."
     }
    }
   },
   "RewriteResult": {
    "type": "object",
    "properties": {
     "text": {
      "type": "string"
     },
     "changes": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "before": {
         "type": "string"
        },
        "after": {
         "type": "string"
        }
       }
      }
     },
     "suggestions": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "placeholder": {
         "type": "string"
        },
        "sentence": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "securitySchemes": {
   "freeKey": {
    "type": "http",
    "scheme": "bearer",
    "description": "Optional free key from POST /v1/keys."
   }
  }
 }
}