TextGears Readability API

openapi: 3.2.0
info:
  title: TextGears Readability API
  description: TextGears is a grammar checking and text analysis REST API providing spelling corrections, grammar error detection, readability scoring, language detection, text summarization, and custom dictionary management across 11 languages. The service processes over 10.8 million API requests daily with distributed infrastructure across Estonia, Singapore, and the United States.
  version: 1.0.0
  contact:
    url: https://textgears.com
  termsOfService: https://textgears.com/terms
  license:
    name: Commercial
    url: https://textgears.com
servers:
- url: https://api.textgears.com
  description: Auto-routing (recommended)
- url: https://eu.api.textgears.com
  description: Europe
- url: https://us.api.textgears.com
  description: United States
- url: https://sg.api.textgears.com
  description: Asia (Singapore)
security:
- apiKeyQuery: []
- apiKeyHeader: []
tags:
- name: Readability
  description: Text readability scoring and analysis
paths:
  /readability:
    post:
      operationId: checkReadability
      summary: Check readability
      description: Calculates readability metrics using multiple algorithms including Flesch-Kincaid, Gunning Fog, Coleman-Liau, and SMOG, plus emotion analysis and word counts.
      tags:
      - Readability
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BaseRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/BaseRequest'
      responses:
        '200':
          description: Readability analysis result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadabilityResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
  /analyze:
    post:
      operationId: analyzeText
      summary: Analyze text
      description: Combines grammar checking with readability metrics and text statistics in a single request.
      tags:
      - Readability
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CheckRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/CheckRequest'
      responses:
        '200':
          description: Combined text analysis result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    GrammarError:
      type: object
      properties:
        id:
          type: string
          description: Unique error identifier
        offset:
          type: integer
          description: Character offset of the error in the original text
        length:
          type: integer
          description: Length of the error span in characters
        bad:
          type: string
          description: The erroneous text
        better:
          type: array
          items:
            type: string
          description: Suggested corrections
        type:
          type: string
          description: Error type classification
          enum:
          - grammar
          - spelling
          - punctuation
          - style
        description:
          type: string
          description: Human-readable error description
    CheckRequest:
      allOf:
      - $ref: '#/components/schemas/BaseRequest'
      - type: object
        properties:
          rules:
            type: array
            items:
              type: string
            description: Specific grammar rules to apply or exclude
    BaseRequest:
      type: object
      required:
      - text
      properties:
        text:
          type: string
          description: UTF-8 encoded text to analyze
        language:
          type: string
          description: Language code (BCP 47 format)
          default: en-US
          example: en-US
          enum:
          - en-US
          - en-GB
          - en-ZA
          - en-AU
          - en-NZ
          - fr-FR
          - de-DE
          - de-AT
          - de-CH
          - pt-PT
          - pt-BR
          - it-IT
          - ar-AR
          - ru-RU
          - es-ES
          - ja-JP
          - zh-CN
          - el-GR
        key:
          type: string
          description: API authentication key (if not provided via header or query param)
        ai:
          type: boolean
          description: Enable AI-enhanced analysis
          default: false
        whitelist:
          type: array
          items:
            type: string
          description: Words or phrases to exclude from error detection
        dictionary_id:
          type: string
          description: Custom dictionary identifier to use for exception lookup
    ReadabilityResponse:
      type: object
      properties:
        status:
          type: boolean
        response:
          type: object
          properties:
            stats:
              type: object
              description: Text statistics
              properties:
                fleschKincaid:
                  type: object
                  properties:
                    readingEase:
                      type: number
                    grade:
                      type: number
                gunningFog:
                  type: number
                colemanLiau:
                  type: number
                smog:
                  type: number
                wordCount:
                  type: integer
                sentenceCount:
                  type: integer
                characterCount:
                  type: integer
            emotion:
              type: object
              description: Emotion analysis results
    ErrorResponse:
      type: object
      properties:
        status:
          type: boolean
          example: false
        error_code:
          type: integer
          description: Error code
          enum:
          - 500
          - 501
          - 600
          - 606
          - 607
        description:
          type: string
          description: Human-readable error description
    AnalyzeResponse:
      type: object
      properties:
        status:
          type: boolean
        response:
          type: object
          properties:
            errors:
              type: array
              items:
                $ref: '#/components/schemas/GrammarError'
            stats:
              type: object
              description: Text statistics and readability metrics
  responses:
    ErrorResponse:
      description: API error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidKey:
              summary: Invalid API key
              value:
                status: false
                error_code: 600
                description: Invalid key
            rateLimitExceeded:
              summary: Rate limit exceeded
              value:
                status: false
                error_code: 607
                description: Request limit exceeded
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: key
      description: API key passed as a query parameter
    apiKeyHeader:
      type: http
      scheme: basic
      description: API key passed as HTTP Basic Authorization header value