openapi: 3.1.0
info:
  title: Thermo Fisher SampleManager LIMS REST API
  description: >-
    The Thermo Scientific SampleManager LIMS REST API enables secure connection
    between software applications and the SampleManager Laboratory Information
    Management System for simplified data exchange. Provides access to sample
    data, workflows, entity browsing, results, and laboratory operations.
    Supports token-based authentication with hardened session handling.
  version: 21.3.0
  contact:
    name: Thermo Fisher Scientific Digital Solutions
    url: https://www.thermofisher.com/us/en/home/digital-solutions/lab-informatics.html
  license:
    name: Proprietary
    url: https://www.thermofisher.com
servers:
  - url: https://{server}:{port}/smpwcfrestvgsm
    description: SampleManager LIMS REST API Server
    variables:
      server:
        description: The hostname of your SampleManager LIMS server.
        default: localhost
      port:
        description: The port the SampleManager WCF service runs on.
        default: "56105"
security:
  - bearerAuth: []
tags:
  - name: Samples
    description: Access and manage laboratory samples.
  - name: Entities
    description: Browse entity data from SampleManager.
  - name: Results
    description: Access test results and measurements.
  - name: Workflows
    description: Trigger and manage laboratory workflows.
  - name: Authentication
    description: Token-based authentication operations.
paths:
  /mobile/login:
    post:
      operationId: login
      summary: Login
      description: >-
        Authenticates a user and returns a session token for subsequent
        API calls. Token must be included in the Authorization header.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful. Returns session token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /mobile/logout:
    post:
      operationId: logout
      summary: Logout
      description: Invalidates the current session token.
      tags:
        - Authentication
      responses:
        '200':
          description: Logout successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized or token already expired.

  /mobile/browses/{entity}:
    get:
      operationId: browseEntity
      summary: Browse Entity
      description: >-
        Returns a list of records for the specified SampleManager entity
        (e.g., SAMPLE, TEST, RESULT, CUSTOMER). Supports filtering and sorting.
      tags:
        - Entities
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
          description: >-
            The SampleManager entity name (e.g., SAMPLE, TEST, RESULT,
            CUSTOMER, BATCH_HEADER, ANALYSIS).
        - name: criteria
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filter criteria using SampleManager query syntax
            (e.g., STATUS='A' AND SAMPLED_DATE > '2026-01-01').
        - name: orderby
          in: query
          required: false
          schema:
            type: string
          description: Field name to sort results by.
        - name: ascending
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Sort direction.
        - name: pagesize
          in: query
          required: false
          schema:
            type: integer
            default: 50
          description: Number of records per page.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: Page number (1-based).
      responses:
        '200':
          description: Entity records returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowseResponse'
        '401':
          description: Unauthorized.
        '404':
          description: Entity not found.

  /mobile/browses/{entity}/{id}:
    get:
      operationId: getEntityById
      summary: Get Entity By ID
      description: >-
        Returns a single record for the specified entity and record identity.
      tags:
        - Entities
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
          description: The SampleManager entity name.
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The record identity (primary key value).
      responses:
        '200':
          description: Entity record returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityRecord'
        '401':
          description: Unauthorized.
        '404':
          description: Record not found.

  /mobile/samples:
    get:
      operationId: getSamples
      summary: Get Samples
      description: >-
        Returns a list of laboratory samples accessible to the authenticated user.
        Supports filtering by status, date range, and other criteria.
      tags:
        - Samples
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [A, C, X, L]
          description: >-
            Sample status filter (A=Authorized, C=Completed, X=Cancelled, L=Login pending).
        - name: from_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filter samples from this date (YYYY-MM-DD).
        - name: to_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filter samples to this date (YYYY-MM-DD).
        - name: pagesize
          in: query
          required: false
          schema:
            type: integer
            default: 50
          description: Number of records per page.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: Page number.
      responses:
        '200':
          description: Sample list returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleListResponse'
        '401':
          description: Unauthorized.

  /mobile/samples/{sampleId}:
    get:
      operationId: getSampleById
      summary: Get Sample By ID
      description: Returns details for a specific laboratory sample.
      tags:
        - Samples
      parameters:
        - name: sampleId
          in: path
          required: true
          schema:
            type: string
          description: The sample identity/barcode.
      responses:
        '200':
          description: Sample details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sample'
        '401':
          description: Unauthorized.
        '404':
          description: Sample not found.

  /mobile/samples/{sampleId}/results:
    get:
      operationId: getSampleResults
      summary: Get Sample Results
      description: >-
        Returns all test results associated with a specific sample.
      tags:
        - Results
      parameters:
        - name: sampleId
          in: path
          required: true
          schema:
            type: string
          description: The sample identity/barcode.
      responses:
        '200':
          description: Sample results returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultListResponse'
        '401':
          description: Unauthorized.
        '404':
          description: Sample not found.

  /mobile/results:
    post:
      operationId: submitResults
      summary: Submit Results
      description: >-
        Submits test results for one or more samples. Triggers result
        entry workflows and validation in SampleManager.
      tags:
        - Results
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResultSubmitRequest'
      responses:
        '200':
          description: Results submitted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid result data.
        '401':
          description: Unauthorized.

  /mobile/workflows/{workflowName}/trigger:
    post:
      operationId: triggerWorkflow
      summary: Trigger Workflow
      description: >-
        Triggers a named workflow in SampleManager, passing optional
        parameters to the workflow.
      tags:
        - Workflows
      parameters:
        - name: workflowName
          in: path
          required: true
          schema:
            type: string
          description: The name of the SampleManager workflow to trigger.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowTriggerRequest'
      responses:
        '200':
          description: Workflow triggered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowTriggerResponse'
        '400':
          description: Invalid workflow parameters.
        '401':
          description: Unauthorized.
        '404':
          description: Workflow not found.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Session token obtained from the /mobile/login endpoint.
        Pass as "Bearer {token}" in the Authorization header.
  schemas:
    LoginRequest:
      type: object
      required: [username, password]
      properties:
        username:
          type: string
          description: SampleManager username.
        password:
          type: string
          description: SampleManager password.
        instance:
          type: string
          description: SampleManager instance name (if multiple instances).

    LoginResponse:
      type: object
      properties:
        token:
          type: string
          description: Session token for subsequent API calls.
        expires:
          type: string
          format: date-time
          description: Token expiration timestamp.
        username:
          type: string
          description: Authenticated username.

    BrowseResponse:
      type: object
      properties:
        total:
          type: integer
          description: Total number of matching records.
        page:
          type: integer
          description: Current page number.
        pagesize:
          type: integer
          description: Records per page.
        records:
          type: array
          items:
            $ref: '#/components/schemas/EntityRecord'

    EntityRecord:
      type: object
      description: A generic SampleManager entity record. Field names depend on the entity type.
      additionalProperties: true
      properties:
        identity:
          type: string
          description: The primary key of the record.

    Sample:
      type: object
      properties:
        identity:
          type: string
          description: Sample identity/barcode.
        description:
          type: string
          description: Sample description.
        status:
          type: string
          description: Sample status code.
        sampled_date:
          type: string
          format: date
          description: Date the sample was collected.
        customer:
          type: string
          description: Customer identity associated with the sample.
        product:
          type: string
          description: Product identity associated with the sample.
        analysis:
          type: string
          description: Analysis assigned to the sample.
        due_date:
          type: string
          format: date
          description: Due date for sample results.

    SampleListResponse:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        pagesize:
          type: integer
        samples:
          type: array
          items:
            $ref: '#/components/schemas/Sample'

    Result:
      type: object
      properties:
        sample_id:
          type: string
          description: Parent sample identity.
        test:
          type: string
          description: Test identity.
        component:
          type: string
          description: Component being measured.
        result_value:
          type: string
          description: The result value (string to support text and numeric results).
        units:
          type: string
          description: Unit of measurement.
        status:
          type: string
          description: Result status code.
        entered_on:
          type: string
          format: date-time
          description: When the result was entered.
        entered_by:
          type: string
          description: User who entered the result.

    ResultListResponse:
      type: object
      properties:
        total:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Result'

    ResultSubmitRequest:
      type: object
      properties:
        sample_id:
          type: string
          description: Target sample identity.
        results:
          type: array
          items:
            type: object
            properties:
              test:
                type: string
              component:
                type: string
              result_value:
                type: string
              units:
                type: string

    WorkflowTriggerRequest:
      type: object
      description: Optional parameters to pass to the workflow.
      additionalProperties: true

    WorkflowTriggerResponse:
      type: object
      properties:
        success:
          type: boolean
        workflow_id:
          type: string
          description: Identifier of the triggered workflow instance.
        message:
          type: string

    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string