Collaborative Drug Discovery Batches 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 Batches API
  version: 1.0.0
servers:
- url: https://app.collaborativedrug.com/api/v1
security:
- ApiKeyAuth: []
tags:
- description: Batches handling
  name: Batches
paths:
  /vaults/{vault_id}/batches:
    post:
      description: 'The body of the POST must contain a JSON structure specifying the molecule attributes. The structure is roughly the same format as what is returned by a GET call but with some restrictions and additions.

        Note that in a registration vault, POST batch is the only way to create a new molecule, since the registration of a new molecule must be accompanied by a first batch. In this case, the JSON describing the batch will include a "molecule" field with detailed information on the new molecule.'
      operationId: createBatch
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/batch_create'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
      summary: Create a batch
      tags:
      - Batches
  /vaults/{vault_id}/batches/query:
    post:
      description: Get the information from multiple batches. We still support the now deprecated GET queries on the enpoint 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: getBatches
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/batch_query'
              - $ref: '#/components/schemas/batch_query_only_id'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/batch'
                type: array
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
      summary: Get multiple batches
      tags:
      - Batches
  /vaults/{vault_id}/batches/{batch_id}:
    get:
      description: Get the information about a single batch
      operationId: getBatch
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - in: path
        name: batch_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: If true, omit structure representations for a smaller and faster response.
        in: query
        name: no_structures
        schema:
          type: boolean
      - description: If true, the full Batch details are still returned but the Molecule-level information is left out of the JSON results. (Only the IDs of the Molecules are still included.)
        in: query
        name: only_molecule_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 batch's nested molecule.
        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/batch'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
      summary: Get a single batch
      tags:
      - Batches
    put:
      description: 'See Create for valid fields. (An exception to this is the Molecule field - this PUT Batches call should not be used to update the chemical structure of the parent Molecule - use the PUT Molecules API call to achieve this.) Fields not specified in the JSON are not changed.


        To delete a Batch, simply submit with an empty projects array. (For safety/security purposes, Batches which have data associated with them cannot be deleted via this PUT Batches API call. Data (such as rows of readout data in a Protocol Run) must be removed prior to using the PUT Batches API call to delete a Batch.)


        Note that the ID for the batch is specified as part of the URL, not in the JSON (the JSON can contain an ID field as long as its value matches the URL).'
      operationId: updateBatch
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - in: path
        name: batch_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/batch_create'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
      summary: Update a batch
      tags:
      - Batches
components:
  schemas:
    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
    batch_query:
      properties:
        async:
          description: If true, do an asynchronous export. Use for large data sets.
          type: boolean
        batch_fields:
          description: Array of Batch field names to include in the resulting JSON. Defaults to all available fields.
          items:
            type: string
          type: array
        created_after:
          $ref: '#/components/schemas/date'
        collection_criteria:
          description: Array of collection criteria objects. Filters results to only include batches whose molecules match the collection criteria, 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 batches whose molecules belong to this collection instead of including them. Defaults to false.
                type: boolean
                default: false
          type: array
        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 Batch field names & values. Used to filter Batches 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
        modified_after:
          $ref: '#/components/schemas/date'
        modified_before:
          $ref: '#/components/schemas/date'
        molecule_batch_identifier:
          description: A Molecule-Batch ID used to query the Vault. Use this parameter to limit the number of Molecule UDF Fields to return
          type: string
        molecule_created_after:
          $ref: '#/components/schemas/date'
        molecule_created_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
        no_structures:
          default: false
          description: If true, omit structure representations for a smaller and faster response.
          type: boolean
        offset:
          type: integer
        only_ids:
          default: false
          description: If true, only return the ids of the molecules in the batch.
          type: boolean
        only_molecule_ids:
          default: false
          description: If true, the full Batch details are still returned but the Molecule-level information is left out of the JSON results. (Only the IDs of the Molecules are still included.)
          type: boolean
        owner_id:
          default: false
          description: If true, additionally return the owner of each batch 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 batch's nested molecule.
          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 batches with (or without) matching protocol readout data. Criteria are combined using each entry's `junction`.
          items:
            $ref: '#/components/schemas/protocol_criterion'
          type: array
        structure_criterion:
          $ref: '#/components/schemas/structure_criterion'
      type: object
    batch_create:
      properties:
        batch_fields:
          additionalProperties:
            type: string
          description: 'Only in registration vaults


            Each vault has its own settings on the minimum information required to create a new Batch (for a Vault Administrator, see Settings > Vault > Batch Fields, to change which Batch fields are required).


            {<batch_field_name>: <batch_field_value>, ... }

            '
          type: object
        molecule:
          oneOf:
          - description: Only in vaults with registration enabled. See the molecule endpoint in vaults without registration.
            properties:
              cxsmiles:
                type: string
              duplicate_resolution:
                description: "Originally, only tautomer resolution was enabled via the api. For this reason, tautomer_resolution is still an acceptable synonym for duplicate_resolution.\nIf a duplicate, ambiguous OR, or tautomeric structure is detected, this parameter allows to decide the action. New will always create a new molecule, first will pick the first\nmolecule matching.\n\nTo manage cases where duplicate, ambiguous OR, or tautomeric structures might be detected when registering new Molecules/Batches, use the \"duplicate_resolution\" parameter within the Molecule section of the JSON parameters.\n\n    first\n        \"duplicate_resolution\":\"first\"\n        results in a new Batch being registered for the first Molecule detected as a potential match\n    new\n        \"duplicate_resolution\":\"new\"\n        results in a new Molecule being registered\n    prompt\n        \"duplicate_resolution\":\"prompt\"\n        results in nothing being registered\n        potentially matching molecule IDs are returned\ni       The intent of the \"duplicate_resolution\":\"prompt\" parameter is to give you the Molecule IDs of the potentially matching structures… then, you can use the POST Batches without the structure, and match on the Molecule ID or Name to register the new Batch of any existing Molecule.\n"
                enum:
                - first
                - new
                - prompt
                type: string
              id:
                description: The id of an existing molecule
                type: integer
              name:
                type: string
              registration_type:
                enum:
                - CHEMICAL_STRUCTURE
                type: string
              smiles:
                type: string
              structure:
                type: string
            type: object
          - description: When registering a new amino acid
            properties:
              amino_acid:
                description: Amino acid code
                type: string
              registration_type:
                enum:
                - AMINO_ACID
                type: string
            type: object
          - description: When registering a new nucleotide
            properties:
              nucleotide:
                description: Nucleotide code
                type: string
              registration_type:
                enum:
                - NUCLEOTIDE
                type: string
            type: object
        name:
          example: Batch 1
          type: string
        projects:
          description: An array of project ids or names
          items:
            oneOf:
            - type: integer
            - type: string
          type: array
        salt_name:
          description: A two-letter code or Salt vendor string as listed in the All Available Salts table (https://app.collaborativedrug.com/support/salts).  The salt is determined automatically when the salt is included in the molecular structure.
          type: string
        solvent_of_crystallization_name:
          description: Name of the solvent of crystallization. List available at https://support.collaborativedrug.com/hc/en-us/articles/214359563-Salts-and-solvent-of-crystallization#solvents_of_crystallization
          type: string
        stoichiometry:
          description: Only in registration vaults
          properties:
            core_count:
              type: integer
            salt_count:
              type: integer
            solvent_of_crystallization_count:
              type: integer
          type: object
      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
    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
    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
    project_id_name:
      properties:
        id:
          example: 1
          type: integer
        name:
          example: Project 1
          type: string
      type: object
    batch_query_only_id:
      properties:
        batches:
          description: Comma separated list of batch ids. Cannot be used with other parameters
          items:
            type: integer
          type: array
      type: object
    batch:
      properties:
        batch_fields:
          additionalProperties:
            type: string
          type: object
        class:
          example: batch
          type: string
        created_at:
          format: date
          type: string
        formula_weight:
          type: number
        id:
          example: 42
          type: integer
        modified_at:
          format: date
          type: string
        molecule:
          properties:
            class:
              type: string
            created_at:
              format: date-time
              type: string
            id:
              type: integer
            modified_at:
              format: date-time
              type: string
            name:
              type: string
            owner:
              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:
                  type: string
                id:
                  type: integer
                last_name:
                  type: string
              type: object
            projects:
              items:
                $ref: '#/components/schemas/project_id_name'
              type: array
            registration_type:
              type: string
            synonyms:
              items:
                type: string
              type: array
          type: object
        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
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-CDD-Token
      type: apiKey