Collaborative Drug Discovery Molecules 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 Molecules API
  version: 1.0.0
servers:
- url: https://app.collaborativedrug.com/api/v1
security:
- ApiKeyAuth: []
tags:
- description: Molecules handling
  name: Molecules
paths:
  /vaults/{vault_id}/molecules:
    post:
      description: Create a molecule. This is only permitted in vaults that are NOT using a registration system; in registration vaults, register molecules by creating batches instead. To read or search molecules, use `POST /molecules/query`.
      operationId: createMolecule
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/molecule_create'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/molecule'
          description: The created molecule
        '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, or molecule creation is not allowed in this vault
      summary: Create a molecule
      tags:
      - Molecules
  /vaults/{vault_id}/molecules/query:
    post:
      description: Get the information from multiple molecules. We still support the now deprecated GET queries on the endpoint without 'query' in it and passing query parameters in the URL. It is highly recommended that you switch your applications to the POST queries described here.
      operationId: getMolecules
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/molecule_query'
              - $ref: '#/components/schemas/molecule_query_only_id'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/molecule'
                type: array
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
      summary: Get multiple molecules
      tags:
      - Molecules
  /vaults/{vault_id}/molecules/{id}:
    get:
      description: Retrieve a single molecule by id. For querying multiple molecules or searching by structure, use `POST /molecules/query`.
      operationId: getMolecule
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - description: Numeric identifier of the molecule
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: Comma-separated public dataset ids. Defaults to all data sets.
        in: query
        name: data_sets
        schema:
          type: string
      - description: If true, include the original structure in the response. This is independent of no_structures.
        in: query
        name: include_original_structures
        schema:
          type: boolean
      - description: Exclude structure representations (smiles, inchi, molfile, etc.).
        in: query
        name: no_structures
        schema:
          type: boolean
      - description: Return only the molecule's batch ids instead of full batch objects.
        in: query
        name: only_batch_ids
        schema:
          type: boolean
      - description: If true, additionally return the owner as an `owner_id` object with the owner's id, first name and last name. This is added alongside the `owner` full-name string, which is always returned and is left unchanged. Omitting the parameter, or passing false, returns exactly the default response with no `owner_id` key. Also applied to the molecule's nested batches.
        in: query
        name: owner_id
        schema:
          type: boolean
      - description: Comma-separated project ids. Defaults to all available projects.
        in: query
        name: projects
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/molecule'
          description: The molecule
        '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: Molecule not found, or vault is unauthorized
      summary: Get a molecule
      tags:
      - Molecules
    put:
      description: Update a molecule. Only the supplied fields are changed; array fields (synonyms, projects, collections) replace the existing values.
      operationId: updateMolecule
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - description: Numeric identifier of the molecule
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/molecule_update'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/molecule'
          description: The updated molecule
        '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: Molecule not found, or vault is unauthorized
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Validation error
      summary: Update a molecule
      tags:
      - Molecules
  /vaults/{vault_id}/molecules/{id}/image:
    get:
      description: 'Request a rendered image of a molecule''s structure. Image generation is asynchronous: this returns an export object whose progress you poll with `GET /export_progress/{export_id}`, then download the image with `GET /exports/{export_id}` once it is finished.'
      operationId: getMoleculeImage
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - description: Numeric identifier of the molecule
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: Image width in pixels.
        in: query
        name: width
        schema:
          type: integer
      - description: Image height in pixels.
        in: query
        name: height
        schema:
          type: integer
      - description: Image format.
        in: query
        name: format
        schema:
          default: svg
          enum:
          - svg
          - png
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/export'
          description: The export to poll for the generated image
        '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: Molecule not found, or vault is unauthorized
      summary: Get a molecule image
      tags:
      - Molecules
components:
  schemas:
    molecule_create:
      additionalProperties: true
      description: Attributes for creating a molecule. Creating molecules directly is only allowed in vaults that are NOT using a registration system; in registration vaults, register molecules by creating batches instead.
      example:
        name: My compound
        structure: CC(=O)Oc1ccccc1C(=O)O
        synonyms:
        - Aspirin
        projects:
        - 12
        molecule_fields:
          Solubility: High
      properties:
        collections:
          description: Collections to add the molecule to (ids or names).
          items:
            oneOf:
            - type: integer
            - type: string
          type: array
        duplicate_resolution:
          description: How to handle a structure that duplicates an existing molecule. `new` registers a new molecule; `prompt` fails with the duplicate details so the caller can decide. Must match `tautomer_resolution` if both are given.
          enum:
          - new
          - prompt
          type: string
        molecule_fields:
          additionalProperties: true
          description: Custom molecule field values, keyed by field name. The legacy alias `udfs` is also accepted.
          type: object
        name:
          description: Name of the molecule.
          type: string
        projects:
          description: Projects the molecule belongs to (ids or names).
          items:
            oneOf:
            - type: integer
            - type: string
          type: array
        registration_form:
          description: The registration form to use (id or name). Defaults to the vault default.
          oneOf:
          - type: integer
          - type: string
        registration_type:
          description: The kind of entity being registered (e.g. CHEMICAL_STRUCTURE).
          type: string
        structure:
          description: The chemical structure, as SMILES or a molfile. For amino-acid, nucleotide, or mixture molecules use the corresponding structure representation accepted for that registration type.
          type: string
        synonyms:
          description: Alternative names for the molecule.
          items:
            type: string
          type: array
        tautomer_resolution:
          description: How to handle a structure that is a tautomer of an existing molecule.
          enum:
          - new
          - prompt
          type: string
      required:
      - name
      type: object
    molecule:
      properties:
        batches:
          description: Array of batches belonging to this molecule
          items:
            properties:
              batch_fields:
                additionalProperties:
                  type: string
                type: object
              class:
                example: batch
                type: string
              created_at:
                format: date-time
                type: string
              formula_weight:
                type: number
              id:
                example: 42
                type: integer
              modified_at:
                format: date-time
                type: string
              molecule_batch_identifier:
                example: DEMO-1000211-001
                type: string
              name:
                example: Batch 1
                type: string
              owner:
                example: Charlie Weatherall
                type: string
              owner_id:
                description: The batch owner as an object. Present only when the request asks for it with owner_id=true; the `owner` full-name string above is always returned either way.
                properties:
                  first_name:
                    example: Charlie
                    type: string
                  id:
                    example: 12345
                    type: integer
                  last_name:
                    example: Weatherall
                    type: string
                type: object
              projects:
                items:
                  $ref: '#/components/schemas/project_id_name'
                type: array
              salt_name:
                type: string
              solvent_of_crystallization_name:
                type: string
              stoichiometry:
                properties:
                  core_count:
                    type: integer
                  salt_count:
                    type: integer
                  solvent_of_crystallization_count:
                    type: integer
                type: object
            type: object
          type: array
        class:
          example: molecule
          type: string
        created_at:
          format: date-time
          type: string
        id:
          example: 1000211
          type: integer
        modified_at:
          format: date-time
          type: string
        molecule_fields:
          additionalProperties:
            type: string
          type: object
        name:
          example: Aspirin
          type: string
        owner:
          example: Charlie Weatherall
          type: string
        owner_id:
          description: The molecule owner as an object. Present only when the request asks for it with owner_id=true; the `owner` full-name string above is always returned either way.
          properties:
            first_name:
              example: Charlie
              type: string
            id:
              example: 12345
              type: integer
            last_name:
              example: Weatherall
              type: string
          type: object
        projects:
          items:
            $ref: '#/components/schemas/project_id_name'
          type: array
        registration_type:
          description: The registration type of the molecule
          enum:
          - chemical_structure
          - amino_acid
          - nucleotide
          - mixture
          - other
          example: chemical_structure
          type: string
        smiles:
          description: SMILES representation of the molecule structure
          example: CC(=O)OC1=CC=CC=C1C(=O)O
          type: string
        synonyms:
          items:
            type: string
          type: array
      type: object
    date:
      description: 'An ISO 8601 date, or date and time — see [Date and time formats](#date-and-time-formats). Timestamps on this field have one-second precision.

        '
      format: date
      type: string
    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
    vault_id:
      description: Numeric identifier of the vault
      type: integer
    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
    molecule_update:
      additionalProperties: true
      description: Attributes for updating a molecule. Only the supplied fields are changed. Array fields (`synonyms`, `projects`, `collections`) replace the existing values.
      example:
        name: Renamed compound
        synonyms:
        - Aspirin
        - 2-Acetoxybenzoic acid
        molecule_fields:
          Solubility: Medium
      properties:
        collections:
          description: Collections the molecule belongs to (ids or names). Replaces existing.
          items:
            oneOf:
            - type: integer
            - type: string
          type: array
        molecule_fields:
          additionalProperties: true
          description: Custom molecule field values, keyed by field name. The legacy alias `udfs` is also accepted.
          type: object
        name:
          description: Name of the molecule.
          type: string
        projects:
          description: Projects the molecule belongs to (ids or names). Replaces existing.
          items:
            oneOf:
            - type: integer
            - type: string
          type: array
        structure:
          description: Updated chemical structure, as SMILES or a molfile.
          type: string
        synonyms:
          description: Alternative names for the molecule. Replaces existing.
          items:
            type: string
          type: array
      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
    molecule_query:
      properties:
        async:
          description: If true, do an asynchronous export. Use for large data sets.
          type: boolean
        batch_created_after:
          $ref: '#/components/schemas/date'
        batch_created_before:
          $ref: '#/components/schemas/date'
        batch_field_after_date:
          $ref: '#/components/schemas/date'
        batch_field_after_name:
          description: Name of the batch date field to filter on (used with batch_field_after_date).
          type: string
        batch_field_before_date:
          $ref: '#/components/schemas/date'
        batch_field_before_name:
          description: Name of the batch date field to filter on (used with batch_field_before_date).
          type: string
        batch_fields:
          description: Array of Batch field names to include in the resulting JSON. Defaults to all available fields.
          items:
            type: string
          type: array
        collection_criteria:
          description: Array of collection criteria objects. Filters results based on collection membership with support for AND/OR/XOR junctions and exclusion (NOT IN) logic.
          items:
            type: object
            required:
            - collection_id
            properties:
              collection_id:
                description: The ID of the collection to filter by.
                type: integer
              junction:
                description: How to combine this criterion with the previous one. The first criterion's junction is ignored. Defaults to "AND".
                type: string
                enum:
                - AND
                - OR
                - XOR
                default: AND
              not_in:
                description: If true, excludes molecules that belong to this collection instead of including them. Defaults to false.
                type: boolean
                default: false
          type: array
        created_after:
          $ref: '#/components/schemas/date'
        created_before:
          $ref: '#/components/schemas/date'
        data_sets:
          description: Array of public dataset ids. Defaults to all data sets.
          items:
            type: integer
          type: array
        fields_search:
          description: Array of Molecule field names & values. Used to filter Molecules returned based on query values
          items:
            oneOf:
            - properties:
                name:
                  description: Name of the field to search
                  type: string
                text_value:
                  description: Text value to search for
                  type: string
              type: object
            - properties:
                name:
                  description: Name of the field to search
                  type: string
                number_value:
                  description: Number value to search for
                  type: number
              type: object
            - properties:
                date_value:
                  $ref: '#/components/schemas/date'
                name:
                  description: Name of the field to search
                  type: string
              type: object
          type: array
        include_original_structures:
          default: false
          description: If true, include the original structure in the response. This is independent of no_structures.
          type: boolean
        inchikey:
          description: Filter molecules by InChIKey.
          type: string
        modified_after:
          $ref: '#/components/schemas/date'
        modified_before:
          $ref: '#/components/schemas/date'
        molecule_fields:
          description: Array of Molecule field names to include in the resulting JSON. Defaults to all available fields.
          items:
            type: string
          type: array
        names:
          description: Array of molecule names or synonyms to search for.
          items:
            type: string
          type: array
        no_structures:
          default: false
          description: If true, omit structure representations for a smaller and faster response.
          type: boolean
        offset:
          type: integer
        only_batch_ids:
          default: false
          description: If true, the full Molecule details are still returned but the Batch-level information is left out of the JSON results. (Only the IDs of the Batches are still included.)
          type: boolean
        only_ids:
          default: false
          description: If true, only return the ids of the molecules.
          type: boolean
        owner_id:
          default: false
          description: If true, additionally return the owner of each molecule as an `owner_id` object with the owner's id, first name and last name. This is added alongside the `owner` full-name string, which is always returned and is left unchanged. Omitting this property, or passing false, returns exactly the default response with no `owner_id` key. Also applied to each molecule's nested batches.
          type: boolean
        page_size:
          default: 50
          description: Requested page size (maximum value 1000).
          type: integer
        projects:
          description: Array of project ids. Defaults to all available projects.
          items:
            type: integer
          type: array
        protocol_criteria:
          description: Array of protocol-based filters restricting results to molecules with (or without) matching protocol readout data. Criteria are combined using each entry's `junction`.
          items:
            $ref: '#/components/schemas/protocol_criterion'
          type: array
        structure:
          description: A SMILES or MOL string to search for.
          type: string
        structure_criterion:
          $ref: '#/components/schemas/structure_criterion'
        structure_search_type:
          description: The type of structure search to perform. Options are 'exact', 'substructure', 'similarity', or 'exact_with_stereo'.
          enum:
          - exact
          - substructure
          - similarity
          - exact_with_stereo
          type: string
        structure_similarity_threshold:
          description: Similarity threshold for similarity searches (0 to 1). Only used when structure_search_type is 'similarity'.
          maximum: 1
          minimum: 0
          type: number
      type: object
    project_id_name:
      properties:
        id:
          example: 1
          type: integer
        name:
          example: Project 1
          type: string
      type: object
    molecule_query_only_id:
      properties:
        molecules:
          description: Comma separated list of molecule ids. Cannot be used with other parameters
          items:
            type: integer
          type: array
      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
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-CDD-Token
      type: apiKey