Collaborative Drug Discovery Control Layouts API

openapi: 3.2.0
info:
  contact:
    url: https://support.collaborativedrug.com/hc/en-us/requests/new
  description: 'Collaborative Drug Discovery provides an API (Application Programming

    Interface) that can be used for secure programmatic access to your vault

    data.'
  license:
    name: Proprietary
    url: https://support.collaborativedrug.com/hc/en-us/requests/new
  title: CDD Control Layouts API
  version: 1.0.0
servers:
- url: https://app.collaborativedrug.com/api/v1
security:
- ApiKeyAuth: []
tags:
- description: Control well layouts for protocols and runs
  name: Control Layouts
paths:
  /vaults/{vault_id}/control_layouts:
    get:
      description: List the control layouts in the vault. Supports pagination via `page_size` and `offset`, and the usual `created_after`/`modified_after` filters.
      operationId: getControlLayouts
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - description: Maximum number of records to return (default 50, maximum 1000).
        in: query
        name: page_size
        schema:
          type: integer
      - description: Number of records to skip (for pagination).
        in: query
        name: offset
        schema:
          type: integer
      - description: If true, run the listing as an asynchronous export.
        in: query
        name: async
        schema:
          type: boolean
      - description: If true, return only the ids of the matching control layouts.
        in: query
        name: only_ids
        schema:
          type: boolean
      - description: Comma-separated project ids to filter by.
        in: query
        name: projects
        schema:
          type: string
      - description: Only include layouts created on or after this time.
        in: query
        name: created_after
        schema:
          format: date-time
          type: string
      - description: Only include layouts created on or before this time.
        in: query
        name: created_before
        schema:
          format: date-time
          type: string
      - description: Only include layouts modified on or after this time.
        in: query
        name: modified_after
        schema:
          format: date-time
          type: string
      - description: Only include layouts modified on or before this time.
        in: query
        name: modified_before
        schema:
          format: date-time
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  count:
                    type: integer
                  objects:
                    items:
                      $ref: '#/components/schemas/control_layout'
                    type: array
                  offset:
                    type: integer
                  page_size:
                    type: integer
                required:
                - count
                - objects
                type: object
          description: A page of control layouts
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
      summary: Get control layouts
      tags:
      - Control Layouts
    post:
      description: Create a control layout for a protocol or run. The layout dimensions are set with either `size` or `plate`, and the target with either `protocol` or `run`.
      operationId: createControlLayout
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/control_layout_create'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/control_layout'
          description: The created control layout
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Validation error
      summary: Create a control layout
      tags:
      - Control Layouts
  /vaults/{vault_id}/control_layouts/{id}:
    delete:
      description: Delete a control layout.
      operationId: deleteControlLayout
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - description: Numeric identifier of the control layout
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The control layout was deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Control layout not found, or vault is unauthorized
      summary: Delete a control layout
      tags:
      - Control Layouts
    get:
      description: Retrieve a single control layout.
      operationId: getControlLayout
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - description: Numeric identifier of the control layout
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/control_layout'
          description: The control layout
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Control layout not found, or vault is unauthorized
      summary: Get a control layout
      tags:
      - Control Layouts
components:
  schemas:
    error:
      description: A general error response containing an error message and HTTP status code
      properties:
        code:
          description: HTTP status code
          type: integer
          example: 404
        error:
          description: Human-readable error message
          type: string
          example: Resource not found
      type: object
    control_layout_create:
      description: Attributes for creating a control layout. Specify the target with exactly one of `protocol` or `run`, and the layout dimensions with exactly one of `size` or `plate`.
      allOf:
      - oneOf:
        - required:
          - protocol
        - required:
          - run
      - oneOf:
        - required:
          - size
        - required:
          - plate
      example:
        protocol: 321
        size: 96
        control_wells:
        - row: 0
          col: 0
          control_state: +
        - pos: H12
          control_state: '-'
      properties:
        control_wells:
          description: The wells to mark as controls.
          items:
            properties:
              col:
                description: Zero-based column index (use with `row`).
                type: integer
              control_state:
                description: 'Control type: `+` (positive), `-` (negative), `#` (reference molecule), or empty string (no control).'
                enum:
                - +
                - '-'
                - '#'
                - ''
                type: string
              pos:
                description: Well position in letter-number form (e.g. `A1`), as an alternative to `row`/`col`.
                type: string
              row:
                description: Zero-based row index (use with `col`).
                type: integer
            required:
            - control_state
            type: object
          type: array
        plate:
          description: Id of the plate the layout applies to (alternative to `size`).
          type: integer
        protocol:
          description: Id of the protocol to attach the layout to.
          type: integer
        run:
          description: Id of the run to attach the layout to.
          type: integer
        size:
          description: Number of wells in the layout (alternative to `plate`).
          type: integer
      type: object
    control_layout:
      description: A control layout describes which wells of a protocol or run are controls (positive, negative, or a reference molecule).
      properties:
        class:
          example: control layout
          type: string
        control_wells:
          description: The control wells defined by this layout.
          items:
            properties:
              col:
                description: Zero-based column index of the well.
                type: integer
              control_state:
                description: 'The control type of the well: `+` (positive control), `-` (negative control), `#` (reference molecule), or an empty string (not a control).'
                enum:
                - +
                - '-'
                - '#'
                - ''
                type: string
              row:
                description: Zero-based row index of the well.
                type: integer
            type: object
          type: array
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        modified_at:
          format: date-time
          type: string
        plate_id:
          description: Id of the plate this layout applies to, when plate-specific.
          type: integer
        protocol:
          description: Id of the protocol the layout belongs to (always present for run-scoped layouts as the run's protocol).
          type: integer
        run:
          description: Id of the run the layout belongs to, when run-scoped.
          type: integer
        size:
          description: Number of wells in the layout (plate size).
          type: integer
      required:
      - id
      - class
      - size
      - control_wells
      type: object
    error_apikey:
      description: Whenever the given API key doesn't allow access to the given vault or the vault doesn't exist
      properties:
        code:
          default: 401
          type: integer
        error:
          default: key not authorized for access to this vault
          type: string
      type: object
    vault_id:
      description: Numeric identifier of the vault
      type: integer
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-CDD-Token
      type: apiKey