openapi: 3.0.3
info:
  title: FileDiffs REST API
  description: Secure, high-throughput REST API to compare PDFs, Word docs, Excel sheets, PowerPoint presentation decks, raw text files, and visual images.
  version: 1.0.0
servers:
  - url: https://api.filediffs.com
    description: Production API Server
  - url: http://localhost:3000
    description: Local Sandbox Server
paths:
  /api/v1/compare:
    post:
      summary: Compare two files or images
      description: Uploads two target documents or images to compute highlights, line alignment matches, or visual pixel-by-pixel changes.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                left:
                  type: string
                  format: binary
                  description: The original base file (file1) to compare.
                right:
                  type: string
                  format: binary
                  description: The modified compare file (file2) to evaluate.
                output:
                  type: string
                  enum: [json, html]
                  default: json
                  description: Desired formatting wrapper response type.
                format:
                  type: string
                  enum: [auto, text, pdf, docx, xlsx, pptx, image]
                  default: auto
                  description: Override automatic file type detection.
                granularity:
                  type: string
                  enum: [auto, word, character]
                  default: auto
                  description: Choose character-level comparison highlights for typography similarity or word-level fallback.
              required:
                - left
                - right
      responses:
        '200':
          description: Comparison completed successfully.
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Maximum requests allowed per minute window.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining allowed requests in current window.
            X-Usage-Tier:
              schema:
                type: string
              description: Tier associated with active authorization key (sandbox vs active).
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                    example: true
                  linesChanged:
                    type: integer
                    example: 2
                  viewerUrl:
                    type: string
                    example: http://localhost:3000/viewer/comp_abc123
                  diffs:
                    type: object
                    properties:
                      leftLines:
                        type: array
                        items:
                          type: string
                      rightLines:
                        type: array
                        items:
                          type: string
  /api/v1/compare/batch:
    post:
      summary: Batch compare raw text payloads
      description: Compare multiple text blocks or database field contents in parallel. Designed exclusively for high-throughput raw string arrays.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                comparisons:
                  type: array
                  description: Collection of text block tuples to check.
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        example: record_101
                      left:
                        type: array
                        items:
                          type: string
                      right:
                        type: array
                        items:
                          type: string
                    required:
                      - id
                      - left
                      - right
              required:
                - comparisons
      responses:
        '200':
          description: Batch comparisons completed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                    example: true
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: record_101
                        linesChanged:
                          type: integer
                          example: 1
                        diffs:
                          type: object
  /api/v1/validate:
    get:
      summary: Validate credentials and tier metadata
      description: Returns active authorization metadata associated with the specified API key query parameter.
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      parameters:
        - name: apiKey
          in: query
          required: true
          schema:
            type: string
          description: Developer auth token.
      responses:
        '200':
          description: Token check valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                    example: true
                  tier:
                    type: string
                    example: Premium
                  status:
                    type: string
                    example: active
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apiKey