openapi: 3.0.3
info:
  title: FTIRFUN FTIR Search And AI Analysis API
  description: FTIR.fun API for spectral-library search and AI-only review of existing
    FTIR reports. It accepts FTIR spectrum files, peak-position lists, or existing
    search reports and returns ranked candidates or downstream analysis results. Results
    are screening candidates and analytical interpretations, not accredited laboratory
    certifications.
  version: 1.0.0
paths:
  /v1/search:
    post:
      summary: Search the FTIR spectral library
      description: '光谱谱库检索。


        - 传 **file_base64 + filename** → 解析文件,全谱匹配(精度高,psim 相似度)

        - 传 **peaks** → 纯峰位匹配(精度较低,score 是峰匹配综合分)

        - 两者都传 → 优先走全谱模式'
      operationId: searchFtirSpectrum
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /ftir/identify_material:
    post:
      summary: Identify an unknown material from an FTIR spectrum
      operationId: ftirIdentifyMaterial
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CanonicalFtirRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /ftir/match_library_topk:
    post:
      summary: Return the top-k FTIR library matches
      operationId: ftirMatchLibraryTopK
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CanonicalFtirRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /ftir/explain_peaks:
    post:
      summary: Explain FTIR peaks with current peak-group evidence
      operationId: ftirExplainPeaks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CanonicalFtirRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /ftir/assign_functional_groups:
    post:
      summary: Assign likely functional groups to FTIR peaks
      operationId: ftirAssignFunctionalGroups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CanonicalFtirRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /ftir/analyze_spectrum:
    post:
      summary: Run the current canonical FTIR analysis flow
      operationId: ftirAnalyzeSpectrum
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CanonicalFtirRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /ftir/analyze_existing_results:
    post:
      summary: Analyze reported FTIR search results and peak tables
      operationId: ftirAnalyzeExistingResults
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExistingResultsAnalysisRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExistingResultsAnalysisResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /parse-spectrum:
    post:
      summary: Parse any supported FTIR spectrum file into unified representation
      description: '将任意支持格式的光谱文件解析为统一表示。


        支持两种输入方式（二选一）：

        - multipart/form-data: 上传文件 (`file` 字段)

        - application/json: base64 编码 (`file_base64` + `filename`)


        支持格式：CSV, TXT, TSV, Excel (.xls/.xlsx), JCAMP-DX (.jdx/.dx),

        Bruker OPUS (.0~.9, .opus), Thermo SPC (.spc), PerkinElmer SPA (.spa), JSON.'
      operationId: parseSpectrum
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_parseSpectrum'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseSpectrumResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /stats:
    get:
      summary: API call statistics dashboard
      description: 调用统计仪表盘 —— 展示各平台/端点的 API 调用数据。
      operationId: getStats
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Getstats
  /health:
    get:
      summary: Health check
      operationId: getHealth
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Gethealth
components:
  schemas:
    Body_parseSpectrum:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
          nullable: true
        json_body:
          $ref: '#/components/schemas/ParseSpectrumJsonRequest'
          nullable: true
      type: object
      title: Body_parseSpectrum
    CanonicalFtirRequest:
      properties:
        spectrum:
          $ref: '#/components/schemas/CanonicalSpectrumInput'
        task_context:
          $ref: '#/components/schemas/TaskContextInput'
          nullable: true
        options:
          $ref: '#/components/schemas/SearchOptionsInput'
          nullable: true
        file_base64:
          type: string
          title: File Base64
          description: Optional base64-encoded FTIR spectrum file for full-spectrum
            identification.
          nullable: true
        filename:
          type: string
          title: Filename
          description: Original filename used for format detection.
          default: spectrum.0
      type: object
      required:
      - spectrum
      title: CanonicalFtirRequest
    CanonicalSpectrumInput:
      properties:
        type:
          type: string
          const: ftir
          title: Type
          description: Spectrum type. Must be ftir.
          default: ftir
        x_unit:
          type: string
          title: X Unit
          description: Wavenumber unit.
          default: cm-1
        y_unit:
          type: string
          title: Y Unit
          description: Intensity unit.
          default: absorbance
        peaks:
          items:
            type: number
          type: array
          title: Peaks
          description: FTIR peak positions in cm^-1.
          nullable: true
        raw_curve:
          type: string
          title: Raw Curve
          description: Optional raw curve payload marker or serialized content for
            future-compatible callers.
          nullable: true
      type: object
      title: CanonicalSpectrumInput
    ExistingResultsAnalysisRequest:
      properties:
        report_text:
          type: string
          title: Report Text
          description: Plain text copied from an existing instrument or library report.
            The text must include both reported search results and the sample peak
            table.
          nullable: true
        report_file_base64:
          type: string
          title: Report File Base64
          description: 'Optional base64-encoded report file. Supported formats: PDF,
            DOC, DOCX, TXT, CSV, PNG, JPG, JPEG, WEBP, GIF, BMP, TIF, TIFF.'
          nullable: true
        report_filename:
          type: string
          title: Report Filename
          description: Original report filename used to detect the report format.
          default: report.txt
        user_background_text:
          type: string
          title: User Background Text
          description: Optional user-supplied sample background. This is treated only
            as soft context, not as evidence.
          nullable: true
      type: object
      title: ExistingResultsAnalysisRequest
    ExistingResultsAnalysisResponse:
      properties:
        success:
          type: boolean
          title: Success
        analysis_mode:
          type: string
          title: Analysis Mode
        message:
          type: string
          title: Message
          nullable: true
        input_requirements:
          additionalProperties: true
          type: object
          title: Input Requirements
        missing_requirements:
          items:
            type: string
          type: array
          title: Missing Requirements
        missing_requirement_messages:
          items:
            type: string
          type: array
          title: Missing Requirement Messages
        extracted_report:
          additionalProperties: true
          type: object
          title: Extracted Report
          nullable: true
        task_context:
          additionalProperties: true
          type: object
          title: Task Context
          nullable: true
        summary:
          type: string
          title: Summary
          nullable: true
        report_view:
          additionalProperties: true
          type: object
          title: Report View
          nullable: true
        final_decision:
          additionalProperties: true
          type: object
          title: Final Decision
          nullable: true
        direct_evidence:
          additionalProperties: true
          type: object
          title: Direct Evidence
          nullable: true
        related_literature:
          additionalProperties: true
          type: object
          title: Related Literature
          nullable: true
        error:
          type: string
          title: Error
          nullable: true
      type: object
      required:
      - success
      - analysis_mode
      - input_requirements
      - missing_requirements
      - missing_requirement_messages
      title: ExistingResultsAnalysisResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ParseSpectrumJsonRequest:
      properties:
        file_base64:
          type: string
          title: File Base64
          description: Base64-encoded spectrum file content.
        filename:
          type: string
          title: Filename
          description: Original filename for format detection.
          default: spectrum.0
      type: object
      required:
      - file_base64
      title: ParseSpectrumJsonRequest
      description: base64 方式的解析请求。
    ParseSpectrumResponse:
      properties:
        peaks:
          items:
            type: number
          type: array
          title: Peaks
          description: Detected peak wavenumbers (cm⁻¹), descending.
        spectrum:
          items:
            additionalProperties:
              type: number
            type: object
          type: array
          title: Spectrum
          description: Full or downsampled spectral curve.
        status:
          type: string
          title: Status
          description: '''ok'' for success, ''error'' for failure.'
          default: ok
        error:
          type: string
          title: Error
          description: Error message when status is 'error'.
          nullable: true
      type: object
      title: ParseSpectrumResponse
      description: 统一的光谱解析响应，严格 4 字段。
    SearchOptionsInput:
      properties:
        top_k:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: Top K
          description: Number of ranked matches to return.
          default: 15
        tolerance_cm1:
          type: integer
          maximum: 30.0
          minimum: 1.0
          title: Tolerance Cm1
          description: Peak-only search tolerance in cm^-1.
          default: 8
      type: object
      title: SearchOptionsInput
    SearchRequest:
      properties:
        file_base64:
          type: string
          title: File Base64
          description: Base64-encoded FTIR spectrum file. Supports common instrument
            files and CSV-like text files.
          nullable: true
        filename:
          type: string
          title: Filename
          description: Original filename used for format detection.
          default: spectrum.0
        peaks:
          items:
            type: number
          type: array
          title: Peaks
          description: FTIR peak positions in cm^-1.
          nullable: true
        top_k:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: Top K
          description: Number of ranked matches to return.
          default: 10
        tolerance:
          type: integer
          maximum: 30.0
          minimum: 1.0
          title: Tolerance
          description: Peak-only search tolerance in cm^-1.
          default: 8
      type: object
      title: SearchRequest
    SearchResponse:
      properties:
        success:
          type: boolean
          title: Success
        search_mode:
          type: string
          title: Search Mode
          description: full_spectrum | peak_only
        search_mode_label:
          type: string
          title: Search Mode Label
          description: full_spectrum | peak_only
          nullable: true
        summary:
          type: string
          title: Summary
          nullable: true
        n_matches:
          type: integer
          title: N Matches
        matches:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Matches
        result:
          additionalProperties: true
          type: object
          title: Result
          nullable: true
        evidence:
          items:
            type: string
          type: array
          title: Evidence
          nullable: true
        peak_explanations:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Peak Explanations
          nullable: true
        confidence:
          type: number
          title: Confidence
          nullable: true
        confidence_source:
          type: string
          title: Confidence Source
          nullable: true
        confidence_calibrated:
          type: boolean
          title: Confidence Calibrated
          nullable: true
        uncertainty:
          type: string
          title: Uncertainty
          nullable: true
        method:
          type: string
          title: Method
          nullable: true
        task_context:
          additionalProperties: true
          type: object
          title: Task Context
          nullable: true
        options:
          additionalProperties: true
          type: object
          title: Options
          nullable: true
        spectrum:
          additionalProperties: true
          type: object
          title: Spectrum
          nullable: true
        error:
          type: string
          title: Error
          nullable: true
        n_points:
          type: integer
          title: N Points
          nullable: true
        n_peaks_detected:
          type: integer
          title: N Peaks Detected
          nullable: true
        file_format:
          type: string
          title: File Format
          nullable: true
      type: object
      required:
      - success
      - search_mode
      - n_matches
      - matches
      title: SearchResponse
    TaskContextInput:
      properties:
        goal:
          type: string
          title: Goal
          description: identification | explanation | matching | functional_groups
          nullable: true
        sample_type:
          type: string
          title: Sample Type
          description: Sample type label from the caller.
          nullable: true
      type: object
      title: TaskContextInput
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
servers:
- url: https://ftir.fun
