openapi: 3.1.0
info:
  title: Scispot ELN Sequences API
  description: The Scispot REST API provides programmatic access to all features of the Scispot laboratory data platform. Scispot is an API-first Electronic Lab Notebook (ELN) and Laboratory Information Management System (LIMS) designed for modern life science and biotech labs. The API enables programmatic management of Labsheets (structured LIMS data), ELN protocols and experiments, Manifests (plates, boxes, racks), and biological Sequences. Every GUI action in Scispot is available through the API, supporting automation, computational biology workflows, instrument integration, and data pipeline development. Authenticated via personal API tokens with role-based access control (RBAC).
  version: 1.0.0
  contact:
    name: Scispot Developer Support
    url: https://docs.scispot.com/
  termsOfService: https://www.scispot.com/terms
servers:
- url: https://api.scispot.com/v1
  description: Scispot Production API
security:
- ApiKeyAuth: []
tags:
- name: Sequences
  description: Biological sequence management for DNA, RNA, and protein sequences
paths:
  /sequences:
    get:
      operationId: listSequences
      summary: List Sequences
      description: Retrieve a list of all biological sequences in the workspace. Sequences include DNA, RNA, and protein sequences with associated metadata, annotations, and links to experimental records.
      tags:
      - Sequences
      parameters:
      - name: type
        in: query
        description: Filter by sequence type
        required: false
        schema:
          type: string
          enum:
          - dna
          - rna
          - protein
          - chemical
      - name: page
        in: query
        description: Page number for pagination
        required: false
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        description: Number of sequences per page
        required: false
        schema:
          type: integer
          maximum: 100
          default: 20
      responses:
        '200':
          description: List of sequences
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SequenceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSequence
      summary: Create Sequence
      description: Add a new biological sequence to the workspace. Supports DNA, RNA, protein, and chemical structure sequences with full annotation support.
      tags:
      - Sequences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SequenceInput'
      responses:
        '201':
          description: Sequence created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sequence'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sequences/{sequenceId}:
    get:
      operationId: getSequence
      summary: Get Sequence
      description: Retrieve a single biological sequence by its unique identifier.
      tags:
      - Sequences
      parameters:
      - name: sequenceId
        in: path
        description: Unique identifier of the sequence
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Sequence details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sequence'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateSequence
      summary: Update Sequence
      description: Update an existing biological sequence record.
      tags:
      - Sequences
      parameters:
      - name: sequenceId
        in: path
        description: Unique identifier of the sequence
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SequenceInput'
      responses:
        '200':
          description: Sequence updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sequence'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Sequence:
      type: object
      properties:
        id:
          type: string
          description: Unique sequence identifier
        name:
          type: string
          description: Sequence name or identifier
        type:
          type: string
          enum:
          - dna
          - rna
          - protein
          - chemical
          description: Sequence type
        sequence:
          type: string
          description: Raw sequence string
        length:
          type: integer
          description: Sequence length
        annotations:
          type: array
          description: Sequence annotations and features
          items:
            type: object
            properties:
              name:
                type: string
              start:
                type: integer
              end:
                type: integer
              type:
                type: string
              strand:
                type: string
                enum:
                - forward
                - reverse
        metadata:
          type: object
          description: Additional metadata
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    SequenceListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Sequence'
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
    SequenceInput:
      type: object
      properties:
        name:
          type: string
          description: Sequence name or identifier
        type:
          type: string
          enum:
          - dna
          - rna
          - protein
          - chemical
        sequence:
          type: string
          description: Raw sequence string
        annotations:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              start:
                type: integer
              end:
                type: integer
              type:
                type: string
        metadata:
          type: object
          additionalProperties: true
      required:
      - name
      - type
      - sequence
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Human-readable error message
        code:
          type: integer
          description: Error code
  responses:
    Unauthorized:
      description: API key missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters or body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apiKey
      description: Personal API token generated from Scispot Account Settings > Personal Tokens. All API requests require this header.