ivive.app Prediction API

openapi: 3.2.0
info:
  title: ivive.app Prediction 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: Prediction
paths:
  /api/prediction/values:
    post:
      tags:
      - Prediction
      summary: Estimate fu,p, fu,inc and logP from structure
      description: 'fu,p from a random forest on RDKit descriptors, with the range that held the measured value for half of held-out drugs; fu,inc from Kilford 2008 at the given incubation concentration. Also returns human plasma CL and Vss predicted from structure alone, as second opinions on the IVIVE and Schmitt results. Predicted values: confirm experimentally. Measured inputs always take precedence.'
      operationId: predict_values_api_prediction_values_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PredictionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/prediction/similarity:
    post:
      tags:
      - Prediction
      summary: Nearest known drugs, with how IVIVE fared on each
      description: Most similar reference drugs (Tanimoto, Morgan r2) with observed and IVIVE-predicted plasma CL.
      operationId: similar_drugs_api_prediction_similarity_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimilarityRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/prediction/measured-analogues:
    post:
      tags:
      - Prediction
      summary: Nearest ChEMBL compounds with measured fu,p or microsomal CLint
      description: 'Most similar ChEMBL 37 compounds (Tanimoto, Morgan r2, at least 0.7) with measured human plasma fu or human liver microsome CLint, each value with its ChEMBL document; empty when none is that close. Measurements on other compounds: shown for context, never used as this compound''s inputs.'
      operationId: measured_analogues_api_prediction_measured_analogues_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimilarityRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasuredAnaloguesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/prediction/structures:
    post:
      tags:
      - Prediction
      summary: Predict IVIVE inputs and clearance for many structures
      description: 'Up to 500 structures through the same models as a single prediction: descriptors, fu,p with its range, fu,inc, and the structure-only CL and Vss. A structure that cannot be parsed is reported in its own row and does not fail the request. No measured input is involved, so these are predictions throughout.'
      operationId: predict_structures_api_prediction_structures_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StructureBatchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructureBatchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/prediction/sdf:
    post:
      tags:
      - Prediction
      summary: Read an SDF file into structures
      description: Parses an uploaded SDF into name, SMILES and the file's own data fields, so a caller can review what was read before predicting. Unreadable molecules are listed by position.
      operationId: parse_sdf_api_prediction_sdf_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_parse_sdf_api_prediction_sdf_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SdfParseResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
components:
  schemas:
    SdfParseResponse:
      properties:
        molecules:
          items:
            $ref: '#/components/schemas/SdfMolecule'
          type: array
          title: Molecules
        errors:
          items:
            type: string
          type: array
          title: Errors
          description: One per unreadable position in the file.
        total:
          type: integer
          title: Total
          description: Molecules read, excluding the unreadable.
      type: object
      required:
      - molecules
      - total
      title: SdfParseResponse
    SdfMolecule:
      properties:
        index:
          type: integer
          title: Index
        name:
          type: string
          title: Name
        smiles:
          type: string
          title: Smiles
        properties:
          additionalProperties:
            type: string
          type: object
          title: Properties
          description: 'The file''s own data fields, returned unread: a measured value in the file beats a prediction.'
      type: object
      required:
      - index
      - name
      - smiles
      title: SdfMolecule
    StructurePrediction:
      properties:
        name:
          type: string
          title: Name
        smiles:
          type: string
          title: Smiles
        mw:
          anyOf:
          - type: number
          - type: 'null'
          title: Mw
        logp:
          anyOf:
          - type: number
          - type: 'null'
          title: Logp
        tpsa:
          anyOf:
          - type: number
          - type: 'null'
          title: Tpsa
        fu_p:
          anyOf:
          - $ref: '#/components/schemas/RangedValue'
          - type: 'null'
        fu_inc:
          anyOf:
          - type: number
          - type: 'null'
          title: Fu Inc
        cl:
          anyOf:
          - $ref: '#/components/schemas/StructureCL'
          - type: 'null'
        vdss:
          anyOf:
          - $ref: '#/components/schemas/StructureVdss'
          - type: 'null'
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Why this structure was skipped.
      type: object
      required:
      - name
      - smiles
      title: StructurePrediction
    RangedValue:
      properties:
        value:
          type: number
          title: Value
        low:
          type: number
          title: Low
          description: Lower end of the range holding the measured value for half of held-out drugs.
        high:
          type: number
          title: High
        coverage:
          type: number
          title: Coverage
      type: object
      required:
      - value
      - low
      - high
      - coverage
      title: RangedValue
    StructureCL:
      properties:
        value:
          type: number
          title: Value
          description: Plasma clearance, mL/min/kg.
        low:
          type: number
          title: Low
        high:
          type: number
          title: High
        coverage:
          type: number
          title: Coverage
        applicability:
          $ref: '#/components/schemas/Applicability'
      type: object
      required:
      - value
      - low
      - high
      - coverage
      - applicability
      title: StructureCL
      description: 'Human plasma CL predicted from structure alone: a second opinion, not an IVIVE input.'
    Neighbour:
      properties:
        name:
          type: string
          title: Name
        smiles:
          type: string
          title: Smiles
        similarity:
          type: number
          title: Similarity
        cl_obs:
          type: number
          title: Cl Obs
          description: Observed plasma CL, mL/min/kg.
        cl_pred_ws:
          anyOf:
          - type: number
          - type: 'null'
          title: Cl Pred Ws
          description: IVIVE plasma CL from the drug's measured inputs, well-stirred; null without measured CLint.
        cl_pred_pt:
          anyOf:
          - type: number
          - type: 'null'
          title: Cl Pred Pt
          description: Same, parallel-tube.
        source:
          type: string
          title: Source
      type: object
      required:
      - name
      - smiles
      - similarity
      - cl_obs
      - cl_pred_ws
      - cl_pred_pt
      - source
      title: Neighbour
    KnownAnimalPK:
      properties:
        name:
          type: string
          title: Name
        cl_rat:
          anyOf:
          - type: number
          - type: 'null'
          title: Cl Rat
        cl_dog:
          anyOf:
          - type: number
          - type: 'null'
          title: Cl Dog
        cl_monkey:
          anyOf:
          - type: number
          - type: 'null'
          title: Cl Monkey
        fu_p_rat:
          anyOf:
          - type: number
          - type: 'null'
          title: Fu P Rat
        cl_human:
          anyOf:
          - type: number
          - type: 'null'
          title: Cl Human
          description: Published human plasma CL, mL/min/kg, where the compilation has one
        source:
          type: string
          title: Source
      type: object
      required:
      - name
      - source
      title: KnownAnimalPK
      description: 'Published animal clearance for a drug already in the literature.


        A lookup, not a prediction, and it only ever matches a known drug. `cl_human` is carried

        because that is the catch: if this matched, the human answer is already published.'
    StructureBatchRequest:
      properties:
        molecules:
          items:
            $ref: '#/components/schemas/NamedStructure'
          type: array
          maxItems: 500
          minItems: 1
          title: Molecules
        assay_type:
          type: string
          enum:
          - microsomes
          - hepatocytes
          title: Assay Type
          default: microsomes
        concentration:
          type: number
          maximum: 10.0
          exclusiveMinimum: 0.0
          title: Concentration
          default: 1.0
      type: object
      required:
      - molecules
      title: StructureBatchRequest
      description: Structures to predict for. Validation is per row, so one bad SMILES keeps the rest.
    Body_parse_sdf_api_prediction_sdf_post:
      properties:
        file:
          type: string
          format: binary
          title: File
      type: object
      required:
      - file
      title: Body_parse_sdf_api_prediction_sdf_post
    StructureVdss:
      properties:
        value:
          type: number
          title: Value
          description: Volume of distribution at steady state, L/kg.
        low:
          type: number
          title: Low
        high:
          type: number
          title: High
        coverage:
          type: number
          title: Coverage
        applicability:
          $ref: '#/components/schemas/Applicability'
      type: object
      required:
      - value
      - low
      - high
      - coverage
      - applicability
      title: StructureVdss
      description: 'Human Vss predicted from structure alone: a second opinion on the Schmitt 2008 result.'
    PredictionRequest:
      properties:
        smiles:
          type: string
          maxLength: 2000
          title: Smiles
          description: Structure as SMILES.
        assay_type:
          type: string
          enum:
          - microsomes
          - hepatocytes
          title: Assay Type
          description: 'Incubation fu,inc is predicted for: microsomes or hepatocytes.'
          default: microsomes
        concentration:
          type: number
          maximum: 10.0
          exclusiveMinimum: 0.0
          title: Concentration
          description: 'Incubation concentration: mg microsomal protein/mL, or 10⁶ hepatocytes/mL.'
          default: 1.0
      type: object
      required:
      - smiles
      title: PredictionRequest
    MeasuredAnalogue:
      properties:
        chembl_id:
          type: string
          title: Chembl Id
        name:
          type: string
          title: Name
          description: ChEMBL preferred name; blank for most research compounds.
          default: ''
        smiles:
          type: string
          title: Smiles
        similarity:
          type: number
          title: Similarity
        fu_p:
          anyOf:
          - $ref: '#/components/schemas/MeasuredValue'
          - type: 'null'
          description: Human plasma fu.
        clint:
          anyOf:
          - $ref: '#/components/schemas/MeasuredValue'
          - type: 'null'
          description: Human liver microsome CLint, µL/min/mg protein.
      type: object
      required:
      - chembl_id
      - smiles
      - similarity
      title: MeasuredAnalogue
    StructureBatchResponse:
      properties:
        molecules:
          items:
            $ref: '#/components/schemas/StructurePrediction'
          type: array
          title: Molecules
        n_predicted:
          type: integer
          title: N Predicted
        n_skipped:
          type: integer
          title: N Skipped
      type: object
      required:
      - molecules
      - n_predicted
      - n_skipped
      title: StructureBatchResponse
    PredictionResponse:
      properties:
        fu_p:
          $ref: '#/components/schemas/RangedValue'
          description: Random forest on RDKit descriptors, ~3,600 structures.
        fu_inc:
          type: number
          title: Fu Inc
          description: Kilford 2008 / Hallifax & Houston 2006 from RDKit logP.
        logp:
          type: number
          title: Logp
          description: RDKit Crippen logP.
        applicability:
          $ref: '#/components/schemas/Applicability'
        ionizable:
          items:
            type: string
            enum:
            - acid
            - base
          type: array
          title: Ionizable
          description: 'Groups mostly charged at pH 7.4, from substructure patterns (carboxylic acid, tetrazole, aliphatic amine, amidine). The pKa is not predicted: this only says that treating the compound as neutral in Vss is probably wrong.'
        known_animal_pk:
          anyOf:
          - $ref: '#/components/schemas/KnownAnimalPK'
          - type: 'null'
          description: 'Published rat/dog/monkey in-vivo plasma CL, if this structure is a drug in the PKSmart animal compilation. A literature lookup, not a prediction: a novel compound never matches, and anything that does has a published human CL too.'
        structure_cl:
          $ref: '#/components/schemas/StructureCL'
          description: Human plasma CL from an extra-trees model on the same descriptors, trained on ~1,200 drugs with observed IV clearance. Independent of every IVIVE input, so it is a check on the mechanistic result rather than a part of it. Human only.
        structure_vdss:
          $ref: '#/components/schemas/StructureVdss'
          description: Human Vss from gradient boosting on the same descriptors, trained on ~1,200 drugs with observed IV Vss. A second opinion on the Schmitt 2008 path, which it beats on unseen structures while covering human only.
      type: object
      required:
      - fu_p
      - fu_inc
      - logp
      - applicability
      - structure_cl
      - structure_vdss
      title: PredictionResponse
    NamedStructure:
      properties:
        name:
          type: string
          maxLength: 255
          title: Name
          default: ''
        smiles:
          type: string
          maxLength: 2000
          title: Smiles
      type: object
      required:
      - smiles
      title: NamedStructure
    SimilarityResponse:
      properties:
        neighbours:
          items:
            $ref: '#/components/schemas/Neighbour'
          type: array
          title: Neighbours
      type: object
      required:
      - neighbours
      title: SimilarityResponse
      description: 'Values passed on from public datasets; sources and licences: https://ivive.app/sources.'
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Applicability:
      properties:
        max_similarity:
          type: number
          title: Max Similarity
          description: Tanimoto (Morgan r2) to the nearest fu,p training structure.
        status:
          type: string
          enum:
          - in_domain
          - borderline
          - out_of_domain
          title: Status
      type: object
      required:
      - max_similarity
      - status
      title: Applicability
    SimilarityRequest:
      properties:
        smiles:
          type: string
          maxLength: 2000
          title: Smiles
          description: Structure as SMILES.
        n:
          type: integer
          maximum: 10.0
          minimum: 1.0
          title: N
          description: How many reference drugs to return, nearest first.
          default: 3
      type: object
      required:
      - smiles
      title: SimilarityRequest
    MeasuredAnaloguesResponse:
      properties:
        analogues:
          items:
            $ref: '#/components/schemas/MeasuredAnalogue'
          type: array
          title: Analogues
      type: object
      required:
      - analogues
      title: MeasuredAnaloguesResponse
      description: 'Measured values from ChEMBL 37, CC BY-SA 3.0; sources and licences: https://ivive.app/sources.'
    MeasuredValue:
      properties:
        value:
          type: number
          title: Value
          description: Median over the compound's ChEMBL measurements.
        relation:
          type: string
          title: Relation
          description: '''<'' or ''>'' when every measurement was a bound; '''' otherwise.'
          default: ''
        n:
          type: integer
          title: N
          description: Measurements behind the median.
        document:
          type: string
          title: Document
          description: ChEMBL document of the measurement nearest the median.
      type: object
      required:
      - value
      - n
      - document
      title: MeasuredValue
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/auth/login