Collaborative Drug Discovery Inventory Samples 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 Inventory Samples API
  version: 1.0.0
servers:
- url: https://app.collaborativedrug.com/api/v1
security:
- ApiKeyAuth: []
tags:
- description: Inventory samples and their events
  name: Inventory Samples
paths:
  /vaults/{vault_id}/inventory_samples:
    get:
      description: List inventory samples in the vault. Supports pagination (`page_size`, `offset`), asynchronous retrieval (async=true), and filtering by batch, project, and creation/modification dates. Requires inventory fields to be enabled for the vault.
      operationId: getInventorySamples
      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, additionally return the owner of each sample 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 each sample's nested inventory events.
        in: query
        name: owner_id
        schema:
          type: boolean
      - description: Comma-separated batch ids to filter by.
        in: query
        name: batch_ids
        schema:
          type: string
      - description: Comma-separated inventory sample ids to filter by.
        in: query
        name: inventory_sample_ids
        schema:
          type: string
      - description: Comma-separated project ids to filter by.
        in: query
        name: projects
        schema:
          type: string
      - description: Only include samples created on or after this time.
        in: query
        name: created_after
        schema:
          format: date-time
          type: string
      - description: Only include samples created on or before this time.
        in: query
        name: created_before
        schema:
          format: date-time
          type: string
      - description: Only include samples modified on or after this time.
        in: query
        name: modified_after
        schema:
          format: date-time
          type: string
      - description: Only include samples 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/inventory_sample_object'
                    type: array
                  offset:
                    type: integer
                  page_size:
                    type: integer
                required:
                - count
                - objects
                type: object
          description: A page of inventory samples
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_apikey'
          description: Missing or invalid API key
      summary: Get inventory samples
      tags:
      - Inventory Samples
    post:
      description: Create an inventory sample for a batch.
      operationId: createInventorySample
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/inventory_sample_create'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventory_sample_object'
          description: The created inventory sample
        '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 an inventory sample
      tags:
      - Inventory Samples
  /vaults/{vault_id}/inventory_samples/{id}:
    delete:
      description: Delete an inventory sample. Samples that are associated with a protocol (readout rows) or a plate well cannot be deleted.
      operationId: deleteInventorySample
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - description: Numeric identifier of the inventory sample
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                type: object
          description: The inventory sample was deleted
        '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: The sample cannot be deleted (associated with a protocol or plate well)
      summary: Delete an inventory sample
      tags:
      - Inventory Samples
    get:
      description: Retrieve a single inventory sample.
      operationId: getInventorySample
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - description: Numeric identifier of the inventory sample
        in: path
        name: id
        required: true
        schema:
          type: integer
      - 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 sample's nested inventory events.
        in: query
        name: owner_id
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventory_sample_object'
          description: The inventory sample
        '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: Inventory sample not found, or vault is unauthorized
      summary: Get an inventory sample
      tags:
      - Inventory Samples
    put:
      description: Update an inventory sample. Only the supplied fields are changed. At most one inventory event may be added or updated per request.
      operationId: updateInventorySample
      parameters:
      - in: path
        name: vault_id
        required: true
        schema:
          $ref: '#/components/schemas/vault_id'
      - description: Numeric identifier of the inventory sample
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/inventory_sample_update'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inventory_sample_object'
          description: The updated inventory sample
        '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: Update an inventory sample
      tags:
      - Inventory Samples
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
    inventory_sample_object:
      description: 'An inventory sample: a tracked physical amount of a batch, with its current amount, location, custom fields, and event history.'
      properties:
        batch:
          description: Id of the batch this sample is an inventory of.
          type: integer
        batch_name:
          description: Name of the associated batch.
          type: string
        class:
          example: inventory sample
          type: string
        created_at:
          format: date-time
          type: string
        created_by_user_full_name:
          description: Full name of the user who created the sample.
          type: string
        current_amount:
          description: Current amount remaining for the sample.
          type: number
        depleted:
          description: Whether the sample has been depleted.
          type: boolean
        fields:
          additionalProperties: true
          description: Custom inventory sample field values, keyed by field name.
          type: object
        id:
          type: integer
        inventory_events:
          description: The event history (additions, withdrawals, etc.) for the sample.
          items:
            properties:
              class:
                example: inventory event
                type: string
              created_at:
                format: date-time
                type: string
              fields:
                additionalProperties: true
                description: Custom event field values, keyed by field name.
                type: object
              id:
                type: integer
              modified_at:
                format: date-time
                type: string
              owner:
                description: Full name of the user who owns the event. Always returned.
                type: string
              owner_id:
                description: The event 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
              updated_by_user_full_name:
                type: string
            type: object
          type: array
        location:
          description: Human-readable display path of the sample's location.
          type: string
        modified_at:
          format: date-time
          type: string
        name:
          description: Name (identifier) of the sample.
          type: string
        owner:
          description: Full name of the user who owns the sample. Always returned.
          type: string
        owner_id:
          description: The sample 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
        units:
          description: Units the sample amount is expressed in.
          type: string
        updated_by_user_full_name:
          description: Full name of the user who last modified the sample.
          type: string
      required:
      - id
      - class
      - created_at
      - modified_at
      - units
      - batch
      - batch_name
      - current_amount
      - depleted
      type: object
    inventory_sample_update:
      description: Attributes for updating an inventory sample. Only supplied fields are changed.
      example:
        depleted: false
        fields:
          Supplier: New Supplier Inc
        inventory_events:
        - id: 54321
          fields:
            Debit: 10
      properties:
        depleted:
          description: Mark the sample as depleted (`true`) or clear the depleted flag (`false`).
          type: boolean
        fields:
          additionalProperties: true
          description: Custom inventory sample field values, keyed by field name.
          type: object
        inventory_events:
          description: An inventory event to add or update. At most one event may be supplied per request. Include the event `id` to update an existing event; omit it to create a new one.
          items:
            properties:
              fields:
                additionalProperties: true
                description: Custom event field values, keyed by field name.
                type: object
              id:
                description: Id of the event to update. Omit to create a new event.
                type: integer
            type: object
          maxItems: 1
          type: array
        units:
          description: Units the sample amount is expressed in.
          enum:
          - g
          - kg
          - mg
          - µg
          - ng
          - mL
          - L
          - µL
          - M
          - mM
          - µM
          - nM
          - mol
          - mmol
          - µmol
          - nmol
          - pmol
          - count
          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
    inventory_sample_create:
      description: Attributes for creating an inventory sample.
      example:
        batch_id: 456
        units: mg
        fields:
          Supplier: Acme Chemicals
        inventory_events:
        - fields:
            Credit: 100
      properties:
        batch_id:
          description: Id of the batch this sample is an inventory of.
          type: integer
        fields:
          additionalProperties: true
          description: Custom inventory sample field values, keyed by field name.
          type: object
        inventory_events:
          description: Initial inventory event(s) for the sample. At most one event may be supplied per request.
          items:
            properties:
              fields:
                additionalProperties: true
                description: Custom event field values, keyed by field name.
                type: object
            type: object
          maxItems: 1
          type: array
        units:
          description: 'Units the sample amount is expressed in. One of: g, kg, mg, µg, ng, mL, L, µL, M, mM, µM, nM, mol, mmol, µmol, nmol, pmol, count.'
          enum:
          - g
          - kg
          - mg
          - µg
          - ng
          - mL
          - L
          - µL
          - M
          - mM
          - µM
          - nM
          - mol
          - mmol
          - µmol
          - nmol
          - pmol
          - count
          type: string
      required:
      - batch_id
      - units
      type: object
    vault_id:
      description: Numeric identifier of the vault
      type: integer
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-CDD-Token
      type: apiKey