ivive.app Ivive API

openapi: 3.2.0
info:
  title: .app Ivive API
  description: 'Calculations for early drug discovery: IVIVE hepatic clearance with its observed-CL band,

    structure-based predictions, species scaling.


    **No key needed** for single-compound endpoints, up to 120/minute per address.

    Batches need a login; a free account takes up to 25 compounds. For a key or more volume, write to

    hello@ivive.app.


    Results are research estimates, not for clinical, regulatory or dosing decisions. Structures and

    inputs are processed in memory and not stored. The same calculations are available to LLMs as an

    MCP server at `/mcp/`.


    Reference drugs and published animal PK come from public datasets, ChEMBL among them, under

    CC BY-SA 3.0 and other open licences: https://ivive.app/sources.'
  version: 1.0.0
servers:
- url: https://api.ivive.app
  description: Production
- url: /
  description: This server
tags:
- name: ivive
paths:
  /api/ivive/clhep:
    post:
      tags:
      - ivive
      summary: Calculate hepatic clearance (CLhep)
      description: 'Converts in-vitro CLint (µL/min/mg protein or µL/min/10⁶ cells) to in-vivo hepatic clearance (mL/min/kg) using the Well-stirred or Parallel-tube IVIVE model. Supports assay_type: ''microsomes'' (MPPGL × 1e-3, default) or ''hepatocytes'' (HPGL × 1e-3). CLint is divided by fu_mic; fu_b = fu_p / rb (default rb=1.0). Output is blood clearance (Obach 1999 eq.3/6). Also returns the scaling intermediates, and for human compounds in domain the range holding observed plasma CL for 50% of calibration drugs (the prediction itself is not corrected). With correction_id, also the lab-corrected plasma CL and a band from the lab''s own compounds. With clint_censored, clint is read as the assay''s limit of quantification and every clearance output is an upper bound (no band).'
      operationId: calculate_clhep_api_ivive_clhep_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CLhepRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CLhepResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/ivive/batch:
    post:
      tags:
      - ivive
      summary: Calculate CLhep for many compounds at once
      description: Up to 500 compounds through the same path as /ivive/clhep, sharing one species, assay, model and lab correction. A compound whose numbers cannot be used is reported in its own row and does not fail the request, so a spreadsheet with a few bad cells still returns everything else.
      operationId: calculate_batch_api_ivive_batch_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/ivive/target-clint:
    post:
      tags:
      - ivive
      summary: CLint needed to reach a target clearance
      description: 'Inverts the IVIVE model: given the clearance a compound must come in under, returns the in-vitro CLint that would produce it at these binding values. Hepatic clearance cannot exceed liver blood flow, so a target at or above Qh × Rb is rejected with that ceiling.'
      operationId: target_clint_api_ivive_target_clint_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TargetClintRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TargetClintResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/ivive/sensitivity:
    post:
      tags:
      - ivive
      summary: How much each input moves the answer
      description: Varies one input at a time between a low and a high value, holding the others at the entered values, and returns the plasma CL at each end. Ranges default to the scatter these inputs carry in practice; pass a predicted value's own range to see what it costs. This is input uncertainty, separate from the observed-CL band, which is method error.
      operationId: sensitivity_api_ivive_sensitivity_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SensitivityRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SensitivityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
components:
  schemas:
    BatchRow:
      properties:
        name:
          type: string
          title: Name
        result:
          anyOf:
          - $ref: '#/components/schemas/CLhepResponse'
          - type: 'null'
          description: Null when the row could not be calculated.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Why this row was skipped; null when it succeeded.
      type: object
      required:
      - name
      title: BatchRow
    ObservedBand:
      properties:
        low:
          type: number
          title: Low
          description: Lower bound of observed plasma CL (mL/min/kg).
        high:
          type: number
          title: High
          description: Upper bound of observed plasma CL (mL/min/kg).
        coverage:
          type: number
          title: Coverage
          description: Fraction of calibration compounds whose observed CL fell inside (0.5).
        basis:
          type: string
          enum:
          - reference
          - lab
          title: Basis
          description: 'reference: 301 human drugs, around the uncorrected prediction; lab: the correction''s compounds, around the corrected prediction.'
        n:
          type: integer
          title: N
          description: Number of calibration compounds.
      type: object
      required:
      - low
      - high
      - coverage
      - basis
      - n
      title: ObservedBand
    TargetClintResponse:
      properties:
        clint:
          type: number
          title: Clint
          description: In-vitro CLint that reaches the target, in the assay's units.
        unit:
          type: string
          title: Unit
          description: µL/min/mg protein, or µL/min/10⁶ cells.
        target_clp:
          type: number
          title: Target Clp
        qh:
          type: number
          title: Qh
          description: 'Hepatic blood flow (mL/min/kg): the ceiling on hepatic CL.'
        max_clp:
          type: number
          title: Max Clp
          description: Highest plasma CL hepatic metabolism can reach here (Qh × Rb).
      type: object
      required:
      - clint
      - unit
      - target_clp
      - qh
      - max_clp
      title: TargetClintResponse
    CLhepRequest:
      properties:
        clint:
          type: number
          minimum: 0.0
          title: Clint
          description: 'Intrinsic clearance (µL/min/mg microsomal protein). Use ge=0: zero clearance is physiologically valid.'
        fu_mic:
          type: number
          maximum: 1.0
          exclusiveMinimum: 0.0
          title: Fu Mic
          description: Unbound fraction in microsomes (0–1). Corrects for non-specific microsomal binding.
        fu_p:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Fu P
          description: Unbound fraction in plasma (0–1). Plasma protein binding correction.
        rb:
          type: number
          maximum: 50.0
          exclusiveMinimum: 0.0
          title: Rb
          description: Blood-to-plasma concentration ratio. fu_b = fu_p / Rb. Output is blood clearance.
          default: 1.0
        species:
          type: string
          enum:
          - human
          - rat
          - dog
          title: Species
          description: Species for physiological parameters (Qh, MPPGL, liver weight).
        model:
          type: string
          enum:
          - well-stirred
          - parallel-tube
          title: Model
          description: IVIVE model. well-stirred (venous equilibrium) or parallel-tube (sinusoidal perfusion).
          default: well-stirred
        assay_type:
          type: string
          enum:
          - microsomes
          - hepatocytes
          title: Assay Type
          description: 'Assay type for CLint scaling. microsomes: uses MPPGL (mg/g) × 1e-3; hepatocytes: uses HPGL (×10⁶ cells/g) × 1e-3.'
          default: microsomes
        correction_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Correction Id
          description: Saved lab correction (/api/correction-equations) to apply. Must match species and assay_type. Corrects predicted plasma CL and replaces the reference band with one from the lab's compounds.
        clint_censored:
          type: boolean
          title: Clint Censored
          description: 'Set when the assay reported CLint below its limit of quantification and `clint` is that limit rather than a measurement. CLint then lies in [0, clint), so every clearance output is an upper bound: `upper_bound` is true, no observed-CL band is returned, and the clint_below_loq flag fires.'
          default: false
      type: object
      required:
      - clint
      - fu_mic
      - fu_p
      - species
      title: CLhepRequest
    VariedInput:
      properties:
        input:
          type: string
          enum:
          - clint
          - fu_mic
          - fu_p
          title: Input
        low:
          type: number
          title: Low
        high:
          type: number
          title: High
        clp_low:
          type: number
          title: Clp Low
          description: Plasma CL with this input at its low end (mL/min/kg).
        clp_high:
          type: number
          title: Clp High
        fold:
          type: number
          title: Fold
          description: 'clp_high / clp_low: how far this input alone moves the answer.'
      type: object
      required:
      - input
      - low
      - high
      - clp_low
      - clp_high
      - fold
      title: VariedInput
    SensitivityRequest:
      properties:
        clint:
          type: number
          minimum: 0.0
          title: Clint
          description: 'Intrinsic clearance (µL/min/mg microsomal protein). Use ge=0: zero clearance is physiologically valid.'
        fu_mic:
          type: number
          maximum: 1.0
          exclusiveMinimum: 0.0
          title: Fu Mic
          description: Unbound fraction in microsomes (0–1). Corrects for non-specific microsomal binding.
        fu_p:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Fu P
          description: Unbound fraction in plasma (0–1). Plasma protein binding correction.
        rb:
          type: number
          maximum: 50.0
          exclusiveMinimum: 0.0
          title: Rb
          description: Blood-to-plasma concentration ratio. fu_b = fu_p / Rb. Output is blood clearance.
          default: 1.0
        species:
          type: string
          enum:
          - human
          - rat
          - dog
          title: Species
          description: Species for physiological parameters (Qh, MPPGL, liver weight).
        model:
          type: string
          enum:
          - well-stirred
          - parallel-tube
          title: Model
          description: IVIVE model. well-stirred (venous equilibrium) or parallel-tube (sinusoidal perfusion).
          default: well-stirred
        assay_type:
          type: string
          enum:
          - microsomes
          - hepatocytes
          title: Assay Type
          description: 'Assay type for CLint scaling. microsomes: uses MPPGL (mg/g) × 1e-3; hepatocytes: uses HPGL (×10⁶ cells/g) × 1e-3.'
          default: microsomes
        correction_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Correction Id
          description: Saved lab correction (/api/correction-equations) to apply. Must match species and assay_type. Corrects predicted plasma CL and replaces the reference band with one from the lab's compounds.
        clint_censored:
          type: boolean
          title: Clint Censored
          description: 'Set when the assay reported CLint below its limit of quantification and `clint` is that limit rather than a measurement. CLint then lies in [0, clint), so every clearance output is an upper bound: `upper_bound` is true, no observed-CL band is returned, and the clint_below_loq flag fires.'
          default: false
        clint_range:
          anyOf:
          - $ref: '#/components/schemas/InputRange'
          - type: 'null'
          description: 'CLint range in the assay''s units, e.g. {"low": 10, "high": 40}.'
        fu_mic_range:
          anyOf:
          - $ref: '#/components/schemas/InputRange'
          - type: 'null'
          description: 'fu,mic range (0–1), e.g. {"low": 0.5, "high": 0.9}.'
        fu_p_range:
          anyOf:
          - $ref: '#/components/schemas/InputRange'
          - type: 'null'
          description: A predicted fu,p carries its 50% range; pass it to see what it costs.
      type: object
      required:
      - clint
      - fu_mic
      - fu_p
      - species
      title: SensitivityRequest
      description: The same inputs as a calculation, plus the range to vary each over.
    InputRange:
      properties:
        low:
          type: number
          exclusiveMinimum: 0.0
          title: Low
          description: Low end, in the input's own units, e.g. 0.05 for fu,p.
        high:
          type: number
          exclusiveMinimum: 0.0
          title: High
          description: High end, in the input's own units, e.g. 0.2 for fu,p.
      type: object
      required:
      - low
      - high
      title: InputRange
    CLhepResponse:
      properties:
        clhep:
          type: number
          title: Clhep
          description: Predicted hepatic clearance (mL/min/kg).
        eh:
          type: number
          title: Eh
          description: Hepatic extraction ratio (0–1). EH = CLhep / Qh.
        classification:
          type: string
          title: Classification
          description: 'Clearance class: ''high'' (EH>0.7), ''medium'' (0.3≤EH≤0.7), ''low'' (EH<0.3).'
        model_used:
          type: string
          title: Model Used
          description: Model actually applied (reflects default when omitted in request).
        species:
          type: string
          title: Species
          description: Species used for physiological parameters.
        clint_scaled:
          type: number
          title: Clint Scaled
          description: CLint scaled to the whole liver (mL/min/kg), before fu_mic.
        clint_u:
          type: number
          title: Clint U
          description: Unbound scaled CLint = clint_scaled / fu_mic (mL/min/kg).
        fu_b:
          type: number
          title: Fu B
          description: Unbound fraction in blood = fu_p / Rb.
        qh:
          type: number
          title: Qh
          description: Hepatic blood flow (mL/min/kg).
        clp:
          type: number
          title: Clp
          description: Predicted plasma clearance = CLhep × Rb (mL/min/kg). Uncorrected.
        clp_corrected:
          anyOf:
          - type: number
          - type: 'null'
          title: Clp Corrected
          description: Plasma CL after the lab correction (mL/min/kg). Null without correction_id.
        band:
          anyOf:
          - $ref: '#/components/schemas/ObservedBand'
          - type: 'null'
          description: Range holding observed plasma CL for 50% of calibration compounds at this prediction. Null outside the calibration domain (see flags).
        upper_bound:
          type: boolean
          title: Upper Bound
          description: 'True when clint_censored was set: clhep, eh, clp and clp_corrected are upper bounds, not estimates.'
          default: false
        flags:
          items:
            $ref: '#/components/schemas/DomainFlag'
          type: array
          title: Flags
          description: Applicability-domain warnings.
      type: object
      required:
      - clhep
      - eh
      - classification
      - model_used
      - species
      - clint_scaled
      - clint_u
      - fu_b
      - qh
      - clp
      title: CLhepResponse
    DomainFlag:
      properties:
        code:
          type: string
          title: Code
          description: fu_p_below_0.01 | renal_possible | species_not_calibrated | outside_correction_range | clint_below_loq
        message:
          type: string
          title: Message
      type: object
      required:
      - code
      - message
      title: DomainFlag
    SensitivityResponse:
      properties:
        inputs:
          items:
            $ref: '#/components/schemas/VariedInput'
          type: array
          title: Inputs
          description: Widest effect first.
        clp:
          type: number
          title: Clp
          description: Plasma CL at the entered values, for reference.
      type: object
      required:
      - inputs
      - clp
      title: SensitivityResponse
    TargetClintRequest:
      properties:
        target_clp:
          type: number
          exclusiveMinimum: 0.0
          title: Target Clp
          description: Plasma clearance to aim for (mL/min/kg). Must be below hepatic blood flow × Rb.
        fu_mic:
          type: number
          maximum: 1.0
          exclusiveMinimum: 0.0
          title: Fu Mic
          description: Unbound fraction in the incubation (0–1) the CLint would be measured at.
        fu_p:
          type: number
          maximum: 1.0
          exclusiveMinimum: 0.0
          title: Fu P
          description: Unbound fraction in plasma (0–1).
        rb:
          type: number
          maximum: 50.0
          exclusiveMinimum: 0.0
          title: Rb
          description: Blood-to-plasma concentration ratio; raises the plasma CL ceiling (Qh × Rb).
          default: 1.0
        species:
          type: string
          enum:
          - human
          - rat
          - dog
          title: Species
          description: Species whose liver blood flow and scaling factors apply.
        model:
          type: string
          enum:
          - well-stirred
          - parallel-tube
          title: Model
          description: IVIVE liver model to invert.
          default: well-stirred
        assay_type:
          type: string
          enum:
          - microsomes
          - hepatocytes
          title: Assay Type
          description: Assay the CLint is for; sets its units (µL/min/mg protein or µL/min/10⁶ cells).
          default: microsomes
      type: object
      required:
      - target_clp
      - fu_mic
      - fu_p
      - species
      title: TargetClintRequest
    BatchResponse:
      properties:
        rows:
          items:
            $ref: '#/components/schemas/BatchRow'
          type: array
          title: Rows
          description: One per input compound, in the order given.
        n_calculated:
          type: integer
          title: N Calculated
        n_skipped:
          type: integer
          title: N Skipped
      type: object
      required:
      - rows
      - n_calculated
      - n_skipped
      title: BatchResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    BatchRequest:
      properties:
        compounds:
          items:
            $ref: '#/components/schemas/BatchCompound'
          type: array
          maxItems: 500
          minItems: 1
          title: Compounds
        species:
          type: string
          enum:
          - human
          - rat
          - dog
          title: Species
        model:
          type: string
          enum:
          - well-stirred
          - parallel-tube
          title: Model
          default: well-stirred
        assay_type:
          type: string
          enum:
          - microsomes
          - hepatocytes
          title: Assay Type
          default: microsomes
        correction_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Correction Id
      type: object
      required:
      - compounds
      - species
      title: BatchRequest
    BatchCompound:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        clint:
          type: number
          title: Clint
        fu_mic:
          type: number
          title: Fu Mic
        fu_p:
          type: number
          title: Fu P
        rb:
          type: number
          title: Rb
          default: 1.0
        clint_censored:
          type: boolean
          title: Clint Censored
          default: false
      type: object
      required:
      - name
      - clint
      - fu_mic
      - fu_p
      title: BatchCompound
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/auth/login