openapi: 3.1.0
info:
  title: MolTrace API
  description: AI-native scientific intelligence platform REST API.
  version: 1.0.0
  contact:
    email: api@moltrace.com
servers:
  - url: https://api.moltrace.com/v1
    description: Production
  - url: https://sandbox.api.moltrace.com/v1
    description: Sandbox
security:
  - BearerAuth: []
tags:
  - name: Analysis
    description: Spectral evidence upload, processing, and review workflows.
paths:
  /analyses:
    post:
      tags:
        - Analysis
      summary: Create analysis
      operationId: createAnalysis
      description: Upload a raw FID file or accepted source evidence file and trigger spectral analysis.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - fid_file
                - nucleus
                - instrument
              properties:
                project_id:
                  type: string
                  description: Existing project identifier to attach the analysis to.
                  examples:
                    - prj_01HZX9J8D7YF3A2R6R0Y9T2VQ4
                fid_file:
                  type: string
                  format: binary
                  description: Raw FID binary or accepted source evidence file.
                acqus_file:
                  type: string
                  format: binary
                  description: Bruker acquisition parameter file. Required for Bruker FID uploads.
                nucleus:
                  type: string
                  enum:
                    - 1H
                    - 13C
                    - 2D
                  description: NMR nucleus or experiment family.
                instrument:
                  type: string
                  enum:
                    - bruker
                    - agilent
                    - jcamp_dx
                  description: Source instrument or accepted interchange format.
                notes:
                  type: string
                  maxLength: 2000
                  description: Optional reviewer-visible context for the analysis record.
      responses:
        "201":
          description: Analysis created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Analysis"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "500":
          $ref: "#/components/responses/ServerError"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
  schemas:
    Analysis:
      type: object
      required:
        - id
        - status
        - created_at
      properties:
        id:
          type: string
          examples:
            - ana_01HZX9N4Y8B1VQ0F8C7M1Z2P3A
        status:
          $ref: "#/components/schemas/AnalysisStatus"
        created_at:
          type: string
          format: date-time
        confidence:
          type:
            - number
            - "null"
          minimum: 0
          maximum: 100
          description: Calibrated confidence score once processing completes.
        peaks:
          type: array
          items:
            $ref: "#/components/schemas/PeakSummary"
        report_url:
          type:
            - string
            - "null"
          format: uri
          description: Temporary report download URL when available.
    AnalysisStatus:
      type: string
      enum:
        - queued
        - processing
        - review_required
        - completed
        - failed
    PeakSummary:
      type: object
      properties:
        id:
          type: string
        shift_ppm:
          type: number
        assignment:
          type: string
        category:
          type: string
          enum:
            - compound
            - solvent
            - impurity
            - reference
            - unknown
        confidence:
          type: number
          minimum: 0
          maximum: 100
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        request_id:
          type: string
    ValidationError:
      allOf:
        - $ref: "#/components/schemas/Error"
        - type: object
          properties:
            fields:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ValidationFailed:
      description: Request validation failed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ValidationError"
    ServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"