openapi: 3.2.0
info:
  title: RowGuard CSV validation API
  version: 0.1.0
  termsOfService: https://rapidapi.com/terms
  description: Find CSV import errors before writing to your database. Send CSV text and a schema; get record-level errors, duplicate detection and optional valid rows. UTF-8 CSV only, at most 1,000 data rows, 50 columns, 256 KiB JSON body. No document storage, no AI calls. Email validation checks syntax only. No guarantee that output is safe for spreadsheet export. The production origin and public RapidAPI listing are verified; independent customer validation is pending.
servers:
- url: https://rowguard-api.rowguard-api.workers.dev
  description: Production origin. Validation requests are accepted only from the RapidAPI gateway.
tags:
- name: CSV validation
paths:
  /v1/validate:
    post:
      operationId: validateCsv
      summary: Validate a CSV before import
      tags:
      - CSV validation
      security:
      - RapidAPIKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidationRequest'
            example:
              csv: 'sku,email,quantity

                A-1,ana@example.com,3

                A-1,invalid-email,-1

                B-2,luis@example.com,5'
              schema:
              - name: sku
                required: true
                unique: true
              - name: email
                type: email
                required: true
              - name: quantity
                type: integer
                min: 0
              include_data: true
      responses:
        '200':
          description: Validation completed. Check valid and summary; invalid file data is still HTTP 200.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '400':
          description: Invalid UTF-8 JSON or interrupted body
          headers:
            X-Request-Id:
              schema:
                type: string
            Retry-After:
              description: Present on 429 and temporary dependency failure.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid gateway authentication
          headers:
            X-Request-Id:
              schema:
                type: string
            Retry-After:
              description: Present on 429 and temporary dependency failure.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '408':
          description: Body upload timeout
          headers:
            X-Request-Id:
              schema:
                type: string
            Retry-After:
              description: Present on 429 and temporary dependency failure.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '413':
          description: Body, record, row or column limit exceeded
          headers:
            X-Request-Id:
              schema:
                type: string
            Retry-After:
              description: Present on 429 and temporary dependency failure.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '415':
          description: Unsupported content type, charset or compression
          headers:
            X-Request-Id:
              schema:
                type: string
            Retry-After:
              description: Present on 429 and temporary dependency failure.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Invalid request schema, empty CSV or malformed CSV quoting
          headers:
            X-Request-Id:
              schema:
                type: string
            Retry-After:
              description: Present on 429 and temporary dependency failure.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Request burst limit exceeded
          headers:
            X-Request-Id:
              schema:
                type: string
            Retry-After:
              description: Present on 429 and temporary dependency failure.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Unexpected internal error
          headers:
            X-Request-Id:
              schema:
                type: string
            Retry-After:
              description: Present on 429 and temporary dependency failure.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Configuration or rate-limit dependency unavailable
          headers:
            X-Request-Id:
              schema:
                type: string
            Retry-After:
              description: Present on 429 and temporary dependency failure.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    ApiError:
      type: object
      required:
      - error
      - request_id
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
        request_id:
          type: string
          format: uuid
    ValidationResult:
      type: object
      required:
      - version
      - valid
      - summary
      - columns
      - errors
      - meta
      - request_id
      properties:
        version:
          type: string
        request_id:
          type: string
          format: uuid
        valid:
          type: boolean
          description: True when the file has no validation errors. Warnings do not make it false.
        summary:
          type: object
          required:
          - total_rows
          - checked_rows
          - valid_rows
          - invalid_rows
          - error_count
          - warning_count
          - errors_truncated
          - header_valid
          properties:
            total_rows:
              type: integer
            checked_rows:
              type: integer
            valid_rows:
              type: integer
            invalid_rows:
              type: integer
            error_count:
              type: integer
            warning_count:
              type: integer
            errors_truncated:
              type: boolean
            header_valid:
              type: boolean
        columns:
          type: array
          items:
            type: string
        errors:
          type: array
          maxItems: 200
          items:
            type: object
            required:
            - code
            - message
            - row
            - column
            - end_line
            - severity
            properties:
              code:
                type: string
              message:
                type: string
              row:
                type:
                - integer
                - 'null'
                description: 'Logical CSV record number: header 1, first data record 2. Blank lines are skipped.'
              column:
                type:
                - string
                - 'null'
              end_line:
                type:
                - integer
                - 'null'
                description: Physical line where this record ends, including embedded newlines.
              severity:
                type: string
                enum:
                - error
                - warning
        data:
          type: array
          description: Only present when include_data=true. Contains rows with no errors. All duplicate occurrences are excluded.
          items:
            type: object
            required:
            - row
            - data
            properties:
              row:
                type: integer
              data:
                type: object
                additionalProperties:
                  type: string
        meta:
          type: object
          properties:
            delimiter:
              type: string
            trim:
              type: boolean
            formula_policy:
              type: string
              enum:
              - reject
              - warn
            all_values_are_strings:
              const: true
    ValidationRequest:
      type: object
      properties:
        csv:
          type: string
          minLength: 1
          maxLength: 262144
        schema:
          minItems: 1
          maxItems: 50
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                default: string
                type: string
                enum:
                - string
                - integer
                - number
                - boolean
                - date
                - email
              required:
                default: false
                type: boolean
              unique:
                default: false
                type: boolean
              enum:
                minItems: 1
                maxItems: 100
                type: array
                items:
                  type: string
                  maxLength: 4096
              min:
                type: number
              max:
                type: number
              max_length:
                type: integer
                minimum: 1
                maximum: 4096
            required:
            - name
            additionalProperties: false
        delimiter:
          default: ','
          type: string
          enum:
          - ','
          - ;
          - "\t"
          - '|'
        trim:
          default: true
          type: boolean
        allow_extra_columns:
          default: false
          type: boolean
        formula_policy:
          default: reject
          type: string
          enum:
          - reject
          - warn
        include_data:
          default: false
          type: boolean
        max_errors:
          default: 100
          type: integer
          minimum: 1
          maximum: 200
      required:
      - csv
      - schema
      additionalProperties: false
  securitySchemes:
    RapidAPIKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
      description: Use the subscription key at the RapidAPI gateway and include X-RapidAPI-Host. The origin accepts only gateway-authenticated requests; never distribute its proxy secret.