Collaborative Drug Discovery Searches 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 Searches API
  version: 1.0.0
servers:
- url: https://app.collaborativedrug.com/api/v1
security:
- ApiKeyAuth: []
tags:
- description: Saved searches
  name: Searches
paths:
  /vaults/{vault_id}/searches:
    get:
      description: Return a list of accessible saved searches for the given vault.
      operationId: all_saved_searches
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/saved_search_session'
                type: array
          description: List of saved searches, each including its full `search_criteria` (structure, keyword, and molecule/collection/protocol criteria) and `display_criteria`.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
      summary: List of all saved searches
      tags:
      - Searches
    post:
      description: Save a new search. The payload mirrors the output of the "List saved searches" endpoint, so you can copy that output (adjusting the name and supplying a single project) to recreate a search. A saved search with a name that already exists is rejected.
      operationId: createSavedSearch
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/search_create'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/saved_search_session'
          description: The saved search that was created
        '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, such as a duplicate name, no (or more than one) project, or an unknown structure search type
      summary: Create a saved search
      tags:
      - Searches
  /vaults/{vault_id}/searches/{search_id}:
    get:
      description: 'Unlike other calls, saved searches can only be performed asynchronously.


        Returns an export id and status.


        See Async Exports for how to check on the status of your call and retrieving the data once it has finished.'
      operationId: execute_search
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - in: path
        name: search_id
        required: true
        schema:
          type: integer
      - description: Comma separated list of the ids of the projects to search
        explode: false
        in: query
        name: projects
        required: false
        schema:
          items:
            type: integer
          type: array
        style: form
      - description: Comma separated list of the ids of the data sets to search
        explode: false
        in: query
        name: data_sets
        required: false
        schema:
          items:
            type: integer
          type: array
        style: form
      - description: Should it be zipped
        in: query
        name: zip
        required: false
        schema:
          default: false
          type: boolean
      - description: Format of the exported file
        in: query
        name: format
        required: false
        schema:
          default: csv
          enum:
          - csv
          - sdf
          - xls
          - xlsx
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/export'
          description: Export information
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
      summary: Execute a given search
      tags:
      - Searches
  /vaults/{vault_id}/searches/{search_id}/saved_sessions/{id}:
    delete:
      description: Delete a saved search. A user-facing saved search is a saved-search session (`saved_search_session_id` in the "List saved searches" response) backed by an underlying search (`search_id`).
      operationId: deleteSavedSearch
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - in: path
        name: search_id
        required: true
        schema:
          description: Numeric identifier of the underlying search
          type: integer
      - in: path
        name: id
        required: true
        schema:
          description: Numeric identifier of the saved-search session
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  message:
                    example: Object has been destroyed
                    type: string
                type: object
          description: The saved search 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: Couldn't find this saved search
      summary: Delete a saved search
      tags:
      - Searches
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
    saved_search_session:
      description: A saved search, including its full search criteria and display settings. Fields whose value is empty are omitted from the response.
      properties:
        display_criteria:
          additionalProperties: true
          description: Display/column settings saved with the search.
          properties:
            custom_displayed_header_ids:
              items: {}
              type: array
            displayed_header_ids:
              items: {}
              type: array
            header_group_order:
              items: {}
              type: array
            image_size:
              type: string
            max_column_width:
              type: integer
            plot_scale_type:
              type: string
            row_detail_level:
              type: string
            show_all_protocol_data:
              type: boolean
            show_dose_response_legend:
              type: boolean
            show_non_matching_readouts:
              type: boolean
          type: object
        executed_by:
          description: Names of users who have run the search.
          items:
            type: string
          type: array
        id:
          description: The saved search id.
          type: integer
        last_api_run_at:
          format: date-time
          type: string
        last_ui_run_at:
          format: date-time
          type: string
        name:
          type: string
        owner:
          description: The search owner's name.
          type: string
        projects:
          description: Projects the search is scoped to.
          items:
            additionalProperties: true
            type: object
          type: array
        saved_search_session_id:
          type: integer
        search_criteria:
          description: The full criteria that define the search.
          properties:
            collection_criteria:
              items:
                properties:
                  collection_id:
                    type: integer
                  junction:
                    enum:
                    - AND
                    - OR
                    - XOR
                    type: string
                  not_in:
                    type: boolean
                type: object
              type: array
            keyword_field:
              type: string
            keywords:
              type: string
            molecule_criteria:
              description: Molecule property criteria.
              items:
                additionalProperties: true
                type: object
              type: array
            protocol_criteria:
              items:
                $ref: '#/components/schemas/protocol_criterion'
              type: array
            sort_direction:
              enum:
              - ASC
              - DESC
              type: string
            structure:
              description: The query structure (SMILES/MOL), when a structure search is saved.
              type: string
            structure_criterion:
              $ref: '#/components/schemas/structure_criterion'
            structure_registration_type:
              enum:
              - structure
              - nucleotide_sequence
              - amino_acid_sequence
              type: string
            structure_search_type:
              type: string
            structure_similarity_threshold:
              type: number
          type: object
        visualization_session_id:
          type: integer
      required:
      - id
      - name
      - search_criteria
      type: object
    protocol_criterion:
      description: A single protocol-based filter, used in the `protocol_criteria` array to restrict results to molecules/batches that have (or lack) particular protocol readout data. Combine multiple criteria with the `junction` field.
      properties:
        protocol_id:
          description: Id of the protocol to filter on (provide this or `data_set_id`).
          type: integer
        data_set_id:
          description: Id of the data set to filter on (provide this or `protocol_id`).
          type: integer
        run_criterion:
          description: Which runs to consider.
          enum:
          - any
          - recent
          - run_date
          - run_id
          type: string
        run_id:
          description: Run id to match (when `run_criterion` is `run_id`).
          type: integer
        run_after:
          description: Include runs on/after this date (when `run_criterion` is `run_date`).
          format: date
          type: string
        run_before:
          description: Include runs on/before this date (when `run_criterion` is `run_date`).
          format: date
          type: string
        since_days_ago:
          description: Number of days back to include (when `run_criterion` is `recent`).
          type: integer
        readout_definition_id:
          description: Id of the readout definition to filter on.
          type: integer
        operator:
          description: Comparison operator applied to `readout_value`.
          enum:
          - '='
          - '!='
          - <
          - '>'
          - ≤
          - ≥
          - contains
          - does not contain
          - from
          type: string
        readout_value:
          description: Value to compare the readout against.
          type: string
        readout_value_maximum:
          description: Upper bound of a range (when `operator` is `from`).
          type: string
        calculation_error_type:
          description: Filter by calculation error type.
          type: string
        criterion_type:
          description: The kind of protocol criterion.
          enum:
          - data set or protocol
          - run date
          - protocol field
          type: string
        field:
          description: Protocol field name (when `criterion_type` is `protocol field`).
          type: string
        query:
          description: Protocol field search value (when `criterion_type` is `protocol field`).
          type: string
        protocol_condition_ids:
          description: Restrict to these protocol condition ids.
          items:
            type: integer
          type: array
        negated:
          default: false
          description: If true, exclude rather than include matches.
          type: boolean
        junction:
          default: AND
          description: How to combine this criterion with the previous one (ignored for the first criterion).
          enum:
          - AND
          - OR
          type: string
      type: object
    search_create:
      description: Payload to create (save) a search. The `search_criteria` and `display_criteria` mirror the structure returned by the "List saved searches" endpoint, so its output can be adapted into this request. Exactly one project must be supplied.
      type: object
      required:
      - name
      - projects
      properties:
        name:
          description: Name for the saved search.
          type: string
        projects:
          description: The single project the saved search is scoped to. Provide exactly one project, identified by its id or name (a bare id, a bare name, or an object with `id`/`name`).
          items:
            oneOf:
            - type: integer
            - type: string
            - properties:
                id:
                  type: integer
                name:
                  type: string
              type: object
          type: array
        search_criteria:
          description: The criteria that define the search. Any field left empty is ignored.
          properties:
            collection_criteria:
              items:
                properties:
                  collection_id:
                    type: integer
                  junction:
                    enum:
                    - AND
                    - OR
                    - XOR
                    type: string
                  not_in:
                    type: boolean
                type: object
              type: array
            molecule_criteria:
              description: Molecule property criteria.
              items:
                additionalProperties: true
                type: object
              type: array
            protocol_criteria:
              items:
                $ref: '#/components/schemas/protocol_criterion'
              type: array
            sort_direction:
              enum:
              - ASC
              - DESC
              type: string
            structure:
              description: The query structure (SMILES/MOL), for a structure search.
              type: string
            structure_criterion:
              $ref: '#/components/schemas/structure_criterion'
            structure_registration_type:
              enum:
              - structure
              - nucleotide_sequence
              - amino_acid_sequence
              type: string
            structure_search_type:
              description: Only applies alongside a `structure` (e.g. substructure, similarity, exact).
              type: string
            structure_similarity_threshold:
              type: number
          type: object
        display_criteria:
          additionalProperties: true
          description: Display/column settings to save with the search.
          properties:
            custom_displayed_header_ids:
              items: {}
              type: array
            displayed_header_ids:
              items: {}
              type: array
            header_group_order:
              items: {}
              type: array
            image_size:
              type: string
            max_column_width:
              type: integer
            plot_scale_type:
              type: string
            row_detail_level:
              type: string
            show_all_protocol_data:
              type: boolean
            show_dose_response_legend:
              type: boolean
            show_non_matching_readouts:
              type: boolean
          type: object
    export:
      properties:
        created_at:
          description: Timestamp in ISO-8601 UTC
          example: '2024-01-02T03:04:05Z'
          type: string
        id:
          example: 1
          type: integer
        modified_at:
          description: Timestamp in ISO-8601 UTC
          example: '2024-01-02T03:04:05Z'
          type: string
        queued_job_position:
          description: Position of the export's job in the processing queue. Only present while the export is in the `new` state.
          type: integer
        status:
          description: The export's state. While polling progress it moves `new` -> `started` -> `finished`; any value other than these three during polling means something went wrong. `canceled` is returned after a successful cancel.
          enum:
          - new
          - started
          - finished
          - downloaded
          - failed
          - canceled
          type: string
      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
    structure_criterion:
      description: A structure-property filter object. Each property is filtered by an optional `_minimum` and/or `_maximum` bound. Properties from different registration types (chemical, nucleotide, amino acid) cannot be mixed in one request. Only a representative subset of the available properties is listed below; all follow the same `<property>_minimum` / `<property>_maximum` convention.
      additionalProperties: true
      properties:
        heavy_atom_count_minimum:
          type: integer
        heavy_atom_count_maximum:
          type: integer
        cd_molweight_minimum:
          type: number
        cd_molweight_maximum:
          type: number
        exact_mass_minimum:
          type: number
        exact_mass_maximum:
          type: number
        log_p_minimum:
          type: number
        log_p_maximum:
          type: number
        log_d_minimum:
          type: number
        log_d_maximum:
          type: number
        log_s_minimum:
          type: number
        log_s_maximum:
          type: number
        num_aromatic_rings_minimum:
          type: integer
        num_aromatic_rings_maximum:
          type: integer
        num_h_bond_acceptors_minimum:
          type: integer
        num_h_bond_acceptors_maximum:
          type: integer
        num_h_bond_donors_minimum:
          type: integer
        num_h_bond_donors_maximum:
          type: integer
        num_rotatable_bonds_minimum:
          type: integer
        num_rotatable_bonds_maximum:
          type: integer
        num_rule_of_5_violations_minimum:
          type: integer
        num_rule_of_5_violations_maximum:
          type: integer
        topological_polar_surface_area_minimum:
          type: number
        topological_polar_surface_area_maximum:
          type: number
      type: object
    vault_id:
      description: Numeric identifier of the vault
      type: integer
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-CDD-Token
      type: apiKey