> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revilico.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a RevOptimization run

> Generates molecules while steering the generator, stage by stage, towards goals you set: a property range (weight, solubility, polarity, rings…), similarity to reference molecules, a wanted or unwanted substructure, or strong docking into a protein. Each stage optimises one goal and starts from the generator the previous stage left. Can start from a model you trained with RevTrain.

Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits.

**Limits:** `maxStages`: 5, `maxStepsPerStage`: 1000, `maxMoleculesSampled`: 250000, `maxBatchSize`: 1024, `maxInputMolecules`: 1000.

How the engine works and how to read its results: [RevOptimization documentation](/docs/revoptimization).

**Scope:** `runs:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/engines/revoptimization/runs
openapi: 3.1.0
info:
  title: Revilico API
  version: 1.0.0
  description: >-
    Run Revilico's computational chemistry and biology engines from your own
    code: upload input files, start runs, follow them and read their results.
servers:
  - url: https://public-api.revilico.bio
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Who you are, your credits and what your runs have used.
  - name: Engines
    description: The engines you can run, their parameter schemas and examples.
  - name: Files
    description: 'Upload input files: create an upload, then PUT the bytes.'
  - name: Runs
    description: Start, follow and cancel engine runs.
  - name: Results and outputs
    description: 'Read what a run produced: results, files and outputs.'
  - name: Projects
    description: Group runs into the projects you see in the web app.
  - name: Sharing
    description: >-
      Share runs with people in your organization, as in the web app's Pipeline
      sharing.
  - name: Notes
    description: >-
      RevNotes: read, write and share the rich-text notes and note folders of
      the web app's RevNotes panel, in markdown or HTML.
  - name: Drive
    description: >-
      Your RevDrive files and shared drives, as in the web app: browse, read,
      use files as run inputs, save outputs, and organize. Ids: `dfile_…` and
      `dfld_…` in a personal Drive, `drive_…` for a shared drive, `sdfile_…` and
      `sdfld_…` in one.
  - name: Engine runs
    description: >-
      Start a run of one engine, with that engine's parameters and input files.
      Same endpoint as **Start a run**.
  - name: Health
    description: Service status. Needs no API key.
paths:
  /v1/engines/revoptimization/runs:
    post:
      tags:
        - Engine runs
      summary: Start a RevOptimization run
      description: >-
        Generates molecules while steering the generator, stage by stage,
        towards goals you set: a property range (weight, solubility, polarity,
        rings…), similarity to reference molecules, a wanted or unwanted
        substructure, or strong docking into a protein. Each stage optimises one
        goal and starts from the generator the previous stage left. Can start
        from a model you trained with RevTrain.


        Starts a run and returns it with status `queued`; poll GET
        /v1/runs/{runId} until it finishes. Runs spend credits.


        **Limits:** `maxStages`: 5, `maxStepsPerStage`: 1000,
        `maxMoleculesSampled`: 250000, `maxBatchSize`: 1024,
        `maxInputMolecules`: 1000.


        How the engine works and how to read its results: [RevOptimization
        documentation](/docs/revoptimization).


        **Scope:** `runs:write`.
      operationId: engineRuns.revoptimization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: A name for the run, shown in the web app.
                  type: string
                  maxLength: 200
                parameters:
                  type: object
                  properties:
                    generator:
                      default: reinvent
                      description: >-
                        How molecules are made. reinvent: from scratch, no input
                        molecules. libinvent: adds side groups to the given
                        scaffolds. linkinvent: joins two given fragments with a
                        new linker. mol2mol: makes variants of the given
                        molecules. pepinvent: fills the masked positions of the
                        given peptides.
                      type: string
                      enum:
                        - reinvent
                        - libinvent
                        - linkinvent
                        - mol2mol
                        - pepinvent
                    input_smiles:
                      default: []
                      description: >-
                        Input molecules, one per item; needed for every
                        generator except reinvent, which takes none. libinvent:
                        a scaffold with numbered attachment points, e.g.
                        [*:0]Cc1ccc(C[*:1])cc1. linkinvent: two fragments
                        separated by |, each with one * where the linker
                        attaches, e.g. Oc1cncc(*)c1|*c1ccoc1. mol2mol: the
                        SMILES of a starting molecule. pepinvent: a peptide in
                        CHUCKLES notation, amino acids separated by | and ? at
                        each position to fill.
                      maxItems: 1000
                      type: array
                      items:
                        type: string
                        pattern: ^[!-~]{1,1000}$
                    model:
                      description: >-
                        Built-in model to start from; defaults to the
                        generator's own (for mol2mol, mol2mol_similarity).
                        mol2mol has six: mol2mol_similarity (loosest
                        resemblance), mol2mol_medium_similarity,
                        mol2mol_high_similarity (closest analogs), mol2mol_mmp
                        (the small swaps medicinal chemists typically make),
                        mol2mol_scaffold (new core, same side groups) and
                        mol2mol_scaffold_generic (broader core changes).
                      type: string
                      enum:
                        - reinvent
                        - libinvent
                        - linkinvent
                        - mol2mol_similarity
                        - mol2mol_medium_similarity
                        - mol2mol_high_similarity
                        - mol2mol_mmp
                        - mol2mol_scaffold
                        - mol2mol_scaffold_generic
                        - pepinvent
                    trained_model_run:
                      description: >-
                        Instead of a built-in model: the run_… id of one of your
                        succeeded RevTrain runs, so optimisation starts from
                        molecules like your training set. Only for generator
                        reinvent or mol2mol, the same generator the model was
                        trained for.
                      type: string
                      pattern: >-
                        ^run_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                    batch_size:
                      default: 64
                      description: >-
                        Molecules generated and scored per learning step. Larger
                        batches learn more steadily and make each step slower
                        (docking especially).
                      type: integer
                      minimum: 1
                      maximum: 1024
                    diversity_filter:
                      default: none
                      description: >-
                        A diversity filter for the whole run (a stage's own
                        filter replaces it for that stage). Keeps the generator
                        exploring instead of repeating its best idea, by
                        lowering the score of molecules too like ones already
                        found. identical_murcko_scaffold: same ring framework;
                        identical_topological_scaffold: same framework ignoring
                        atom types; scaffold_similarity: frameworks that are
                        merely similar; penalize_same_smiles: the exact same
                        molecule. none: no filter.
                      type: string
                      enum:
                        - none
                        - identical_murcko_scaffold
                        - identical_topological_scaffold
                        - scaffold_similarity
                        - penalize_same_smiles
                    inception_smiles:
                      default: []
                      description: >-
                        reinvent only: known good molecules, one SMILES per
                        item, mixed into the first learning steps as examples so
                        the generator finds good regions faster. Leave empty to
                        start without examples.
                      maxItems: 1000
                      type: array
                      items:
                        type: string
                        pattern: ^[!-~]{1,1000}$
                    inception_memory_size:
                      default: 100
                      description: >-
                        With inception_smiles: how many of the best molecules
                        (examples and generated) are kept as examples.
                      type: integer
                      minimum: 1
                      maximum: 1000
                    inception_sample_size:
                      default: 10
                      description: >-
                        With inception_smiles: how many examples are mixed into
                        each step. More steers harder towards the examples and
                        explores less.
                      type: integer
                      minimum: 1
                      maximum: 100
                    sampling_strategy:
                      default: multinomial
                      description: >-
                        mol2mol only. multinomial samples with some randomness;
                        beamsearch takes the most likely molecules, less varied.
                      type: string
                      enum:
                        - multinomial
                        - beamsearch
                    distance_threshold:
                      default: 100
                      description: >-
                        mol2mol with multinomial sampling only. Molecules the
                        starting model finds less likely than this (negative
                        log-likelihood above it) get their score cut, which
                        keeps results closer to the inputs. Lower keeps them
                        closer.
                      type: integer
                      minimum: 1
                      maximum: 1000
                    stages:
                      minItems: 1
                      maxItems: 5
                      type: array
                      items:
                        type: object
                        properties:
                          objective:
                            oneOf:
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - molecular_weight
                                      - slogp
                                      - tpsa
                                      - hbond_donors
                                      - hbond_acceptors
                                      - rotatable_bonds
                                      - stereocenters
                                      - heavy_atoms
                                      - hetero_atoms
                                      - rings
                                      - aromatic_rings
                                      - aliphatic_rings
                                      - largest_ring_size
                                      - graph_length
                                      - fraction_sp3
                                      - sp_atoms
                                      - sp2_atoms
                                      - sp3_atoms
                                      - molecular_volume
                                      - linker_molecular_weight
                                      - linker_graph_length
                                      - linker_effective_length
                                      - linker_length_ratio
                                      - linker_hbond_acceptors
                                      - linker_hbond_donors
                                      - linker_rotatable_bonds
                                      - linker_sp_atoms
                                      - linker_sp2_atoms
                                      - linker_sp3_atoms
                                      - linker_rings
                                      - linker_aromatic_rings
                                      - linker_aliphatic_rings
                                    description: >-
                                      A computed property of the molecule. A
                                      molecule scores 1 when the value lies
                                      between low and high and less the further
                                      outside it is, except rotatable_bonds,
                                      stereocenters and linker_rotatable_bonds,
                                      where it scores 1 at or below low and 0 at
                                      or above high. Defaults for low and high:
                                      molecular_weight 150 to 600, slogp -1 to
                                      7, tpsa 0 to 200, hbond_donors 0 to 7,
                                      hbond_acceptors 0 to 12, rotatable_bonds 0
                                      to 15, stereocenters 0 to 6, heavy_atoms
                                      15 to 80, hetero_atoms 1 to 20, rings 0 to
                                      8, aromatic_rings 0 to 5, aliphatic_rings
                                      0 to 5, largest_ring_size 3 to 12,
                                      graph_length 3 to 60, fraction_sp3 0 to 1,
                                      sp_atoms 0 to 10, sp2_atoms 0 to 25,
                                      sp3_atoms 0 to 25, molecular_volume 100 to
                                      700, linker_molecular_weight 50 to 350,
                                      linker_graph_length 3 to 40,
                                      linker_effective_length 2 to 25,
                                      linker_length_ratio 0.1 to 1,
                                      linker_hbond_acceptors 0 to 6,
                                      linker_hbond_donors 0 to 4,
                                      linker_rotatable_bonds 0 to 10,
                                      linker_sp_atoms 0 to 10, linker_sp2_atoms
                                      0 to 20, linker_sp3_atoms 0 to 20,
                                      linker_rings 0 to 4, linker_aromatic_rings
                                      0 to 3, linker_aliphatic_rings 0 to 3, pmi
                                      0 to 1, group_count 0 to 10,
                                      tanimoto_similarity 0 to 1, docking -14 to
                                      -3. slogp: how fat-soluble the molecule
                                      is; tpsa: polar surface area in Å²;
                                      graph_length: the longest chain of bonds;
                                      fraction_sp3: share of carbons with only
                                      single bonds. linker_* types score only
                                      the new linker and need generator
                                      linkinvent.
                                  low:
                                    description: >-
                                      Lower end of the range that is scored (see
                                      type for what it means and the default).
                                    type: number
                                  high:
                                    description: >-
                                      Upper end of the range that is scored (see
                                      type for what it means and the default).
                                    type: number
                                required:
                                  - type
                                additionalProperties: false
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    const: pmi
                                    description: >-
                                      Molecule shape from its principal moments
                                      of inertia: about 0 for rod-like or flat,
                                      about 1 for ball-like. Scores 1 between
                                      low and high (default 0 to 1).
                                  low:
                                    description: >-
                                      Lower end of the range that is scored (see
                                      type for what it means and the default).
                                    type: number
                                  high:
                                    description: >-
                                      Upper end of the range that is scored (see
                                      type for what it means and the default).
                                    type: number
                                  property:
                                    default: npr1
                                    description: 'Which shape ratio to use: npr1 or npr2.'
                                    type: string
                                    enum:
                                      - npr1
                                      - npr2
                                required:
                                  - type
                                additionalProperties: false
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    const: group_count
                                    description: >-
                                      How many times a SMARTS pattern occurs in
                                      the molecule. Scores 1 when the count is
                                      between low and high (default 0 to 10).
                                  low:
                                    description: >-
                                      Lower end of the range that is scored (see
                                      type for what it means and the default).
                                    type: number
                                  high:
                                    description: >-
                                      Upper end of the range that is scored (see
                                      type for what it means and the default).
                                    type: number
                                  smarts:
                                    type: string
                                    pattern: ^[!#%*+,\-./0-9:<=>?@A-Z[\]^_a-z~]{1,500}$
                                    description: >-
                                      The SMARTS pattern to count. For now it
                                      can't contain parentheses or any of ; | &
                                      $ { } ` ' " \, so only molecules without
                                      branches (and patterns without groups) can
                                      be used.
                                required:
                                  - type
                                  - smarts
                                additionalProperties: false
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    const: tanimoto_similarity
                                    description: >-
                                      Fingerprint similarity (0 to 1) to the
                                      most similar reference molecule. Scores 0
                                      at or below low and 1 at or above high
                                      (default 0 to 1).
                                  low:
                                    description: >-
                                      Lower end of the range that is scored (see
                                      type for what it means and the default).
                                    type: number
                                  high:
                                    description: >-
                                      Upper end of the range that is scored (see
                                      type for what it means and the default).
                                    type: number
                                  reference_smiles:
                                    minItems: 1
                                    maxItems: 100
                                    type: array
                                    items:
                                      type: string
                                      pattern: >-
                                        ^[!#%*+,\-./0-9:<=>?@A-Z[\]^_a-z~]{1,500}$
                                    description: >-
                                      Reference molecules, one SMILES per item.
                                      For now it can't contain parentheses or
                                      any of ; | & $ { } ` ' " \, so only
                                      molecules without branches (and patterns
                                      without groups) can be used.
                                  fingerprint_radius:
                                    default: 1
                                    description: >-
                                      How far around each atom the fingerprint
                                      looks, in bonds. Higher compares larger
                                      pieces and makes the similarity stricter.
                                    type: integer
                                    minimum: 1
                                    maximum: 3
                                  use_counts:
                                    default: true
                                    description: >-
                                      Count how often each piece occurs rather
                                      than only whether it occurs.
                                    type: boolean
                                  use_pharmacophore_features:
                                    default: true
                                    description: >-
                                      Compare atoms by their role (hydrogen-bond
                                      donor, acceptor, aromatic…) rather than by
                                      element, so different atoms playing the
                                      same role count as similar.
                                    type: boolean
                                required:
                                  - type
                                  - reference_smiles
                                additionalProperties: false
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    const: docking
                                    description: >-
                                      Docks each molecule into a protein
                                      (AutoDock Vina on GPU) and scores the
                                      binding energy in kcal/mol, where more
                                      negative is better: 1 at or below low, 0
                                      at or above high (default -14 to -3).
                                      Needs the protein as an input file
                                      (stage_N_protein for this stage, or
                                      protein for every docking stage). Much
                                      slower than the other objectives.
                                  low:
                                    description: >-
                                      Lower end of the range that is scored (see
                                      type for what it means and the default).
                                    type: number
                                  high:
                                    description: >-
                                      Upper end of the range that is scored (see
                                      type for what it means and the default).
                                    type: number
                                  box_center:
                                    type: array
                                    prefixItems:
                                      - type: number
                                        minimum: -999
                                        maximum: 9999
                                      - type: number
                                        minimum: -999
                                        maximum: 9999
                                      - type: number
                                        minimum: -999
                                        maximum: 9999
                                    items: false
                                    minItems: 3
                                    maxItems: 3
                                    description: >-
                                      Centre of the search box in Å (x, y, z),
                                      in the coordinates of the protein file:
                                      usually the centre of the binding pocket.
                                  box_size:
                                    default:
                                      - 30
                                      - 30
                                      - 30
                                    description: >-
                                      Edge lengths of the search box in Å (x, y,
                                      z), 1 to 100. It must enclose the pocket;
                                      larger boxes search more space and dock
                                      more slowly.
                                    type: array
                                    prefixItems:
                                      - type: number
                                        minimum: 1
                                        maximum: 100
                                      - type: number
                                        minimum: 1
                                        maximum: 100
                                      - type: number
                                        minimum: 1
                                        maximum: 100
                                    items: false
                                    minItems: 3
                                    maxItems: 3
                                required:
                                  - type
                                  - box_center
                                additionalProperties: false
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    const: matching_substructure
                                    description: >-
                                      Favours molecules that contain a SMARTS
                                      pattern: a molecule without it scores 0.5,
                                      one with it 1.
                                  smarts:
                                    type: string
                                    pattern: ^[!#%*+,\-./0-9:<=>?@A-Z[\]^_a-z~]{1,500}$
                                    description: >-
                                      The SMARTS pattern. For now it can't
                                      contain parentheses or any of ; | & $ { }
                                      ` ' " \, so only molecules without
                                      branches (and patterns without groups) can
                                      be used.
                                  use_chirality:
                                    default: false
                                    description: >-
                                      Also require the 3D handedness (chirality)
                                      in the pattern to match.
                                    type: boolean
                                required:
                                  - type
                                  - smarts
                                additionalProperties: false
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    const: custom_alerts
                                    description: >-
                                      Rejects molecules that contain any of the
                                      SMARTS patterns: they score 0, the rest 1.
                                  smarts:
                                    minItems: 1
                                    maxItems: 100
                                    type: array
                                    items:
                                      type: string
                                      pattern: >-
                                        ^[!#%*+,\-./0-9:<=>?@A-Z[\]^_a-z~]{1,500}$
                                    description: >-
                                      Unwanted SMARTS patterns, one per item.
                                      For now it can't contain parentheses or
                                      any of ; | & $ { } ` ' " \, so only
                                      molecules without branches (and patterns
                                      without groups) can be used.
                                required:
                                  - type
                                  - smarts
                                additionalProperties: false
                            description: >-
                              What this stage optimises: one property or score
                              per stage. To optimise several things, give each
                              its own stage (they run in order, each starting
                              from the generator the previous one left).
                          min_steps:
                            default: 10
                            description: >-
                              Learning steps to run at least, even if
                              target_score is reached sooner.
                            type: integer
                            minimum: 1
                            maximum: 1000
                          max_steps:
                            default: 100
                            description: >-
                              Learning steps to run at most. Each step generates
                              batch_size molecules, scores them and nudges the
                              generator towards the better ones. More steps give
                              better-scoring molecules and take longer.
                            type: integer
                            minimum: 1
                            maximum: 1000
                          target_score:
                            default: 0.6
                            description: >-
                              The stage ends early once a step's average score
                              reaches this (after min_steps). Higher keeps
                              optimising longer.
                            type: number
                            minimum: 0
                            maximum: 1
                          diversity_filter:
                            default: none
                            description: >-
                              A diversity filter for this stage only. Keeps the
                              generator exploring instead of repeating its best
                              idea, by lowering the score of molecules too like
                              ones already found. identical_murcko_scaffold:
                              same ring framework;
                              identical_topological_scaffold: same framework
                              ignoring atom types; scaffold_similarity:
                              frameworks that are merely similar;
                              penalize_same_smiles: the exact same molecule.
                              none: no filter.
                            type: string
                            enum:
                              - none
                              - identical_murcko_scaffold
                              - identical_topological_scaffold
                              - scaffold_similarity
                              - penalize_same_smiles
                        required:
                          - objective
                        additionalProperties: false
                      description: >-
                        The optimisation goals, run in order (1 to 5), e.g.
                        first steer towards a molecular weight range, then
                        towards strong docking. Each stage optimises one
                        objective.
                  required:
                    - stages
                  additionalProperties: false
                inputs:
                  type: object
                  properties:
                    protein:
                      type: string
                      description: >-
                        Protein to dock into (PDB), used by every docking stage
                        that has no stage_N_protein of its own. Water, ligands
                        and other molecules should be removed; hydrogens are
                        added for you. A file id: an upload (`file_…`) or a
                        Drive file (`dfile_…`, `sdfile_…`). Formats: pdb; up to
                        20 MB.
                    stage_1_protein:
                      type: string
                      description: >-
                        Protein to dock into (PDB) in stage 1 only, when it
                        differs from protein. A file id: an upload (`file_…`) or
                        a Drive file (`dfile_…`, `sdfile_…`). Formats: pdb; up
                        to 20 MB.
                    stage_2_protein:
                      type: string
                      description: >-
                        Protein to dock into (PDB) in stage 2 only, when it
                        differs from protein. A file id: an upload (`file_…`) or
                        a Drive file (`dfile_…`, `sdfile_…`). Formats: pdb; up
                        to 20 MB.
                    stage_3_protein:
                      type: string
                      description: >-
                        Protein to dock into (PDB) in stage 3 only, when it
                        differs from protein. A file id: an upload (`file_…`) or
                        a Drive file (`dfile_…`, `sdfile_…`). Formats: pdb; up
                        to 20 MB.
                    stage_4_protein:
                      type: string
                      description: >-
                        Protein to dock into (PDB) in stage 4 only, when it
                        differs from protein. A file id: an upload (`file_…`) or
                        a Drive file (`dfile_…`, `sdfile_…`). Formats: pdb; up
                        to 20 MB.
                    stage_5_protein:
                      type: string
                      description: >-
                        Protein to dock into (PDB) in stage 5 only, when it
                        differs from protein. A file id: an upload (`file_…`) or
                        a Drive file (`dfile_…`, `sdfile_…`). Formats: pdb; up
                        to 20 MB.
                  additionalProperties: false
                budget:
                  description: Most credits the run may spend; it is stopped beyond that.
                  type: number
                  exclusiveMinimum: 0
                projectId:
                  description: >-
                    Add the run to this project (`proj_…`); needs editor or
                    owner on it.
                  type: string
              required:
                - parameters
              additionalProperties: false
            examples:
              properties:
                summary: >-
                  Generate molecules from scratch, steered first into a
                  molecular weight range and then towards moderate fat
                  solubility.
                value:
                  name: Oral-like library
                  parameters:
                    stages:
                      - objective:
                          type: molecular_weight
                          low: 300
                          high: 450
                      - objective:
                          type: slogp
                          low: 1
                          high: 3
                        max_steps: 200
                  inputs: {}
              docking:
                summary: >-
                  Steer towards drug-sized molecules, then towards strong
                  docking scores in a protein pocket.
                value:
                  name: Pocket binders
                  parameters:
                    batch_size: 32
                    diversity_filter: identical_murcko_scaffold
                    stages:
                      - objective:
                          type: molecular_weight
                          low: 250
                          high: 500
                        max_steps: 50
                      - objective:
                          type: docking
                          box_center:
                            - 12.5
                            - -4.2
                            - 30.1
                          box_size:
                            - 22
                            - 22
                            - 22
                        min_steps: 20
                        max_steps: 150
                        target_score: 0.7
                  inputs:
                    protein: file_…
              analogs-without-alerts:
                summary: >-
                  Make variants of a lead molecule (celecoxib) that keep a polar
                  surface area of 60 to 90 Å² and avoid azo and thiol groups.
                value:
                  parameters:
                    generator: mol2mol
                    model: mol2mol_medium_similarity
                    input_smiles:
                      - Cc1ccc(-c2cc(C(F)(F)F)nn2-c2ccc(S(N)(=O)=O)cc2)cc1
                    stages:
                      - objective:
                          type: tpsa
                          low: 60
                          high: 90
                      - objective:
                          type: custom_alerts
                          smarts:
                            - N=N
                            - '[SX2H]'
                        max_steps: 50
                  inputs: {}
              trained-model:
                summary: >-
                  Start from a model you fine-tuned on your own molecules with
                  RevTrain and steer it towards fewer rotatable bonds.
                value:
                  name: Series A, rigidified
                  parameters:
                    trained_model_run: run_00000000-0000-0000-0000-000000000000
                    stages:
                      - objective:
                          type: rotatable_bonds
                          low: 2
                          high: 8
                        max_steps: 300
                        target_score: 0.8
                  inputs: {}
      responses:
        '202':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/502'
components:
  schemas:
    Run:
      type: object
      properties:
        id:
          type: string
          description: Run id, `run_…`.
        engine:
          type: string
          description: Engine slug, e.g. `revredox`.
        name:
          type:
            - string
            - 'null'
        access:
          type: string
          enum:
            - owner
            - shared
            - project
          description: >-
            Why you can see the run: you started it, it was shared with you, or
            it is in a project you belong to. Only the owner can cancel it or
            read its inputs.
        owner:
          type: object
          properties:
            name:
              type:
                - string
                - 'null'
            email:
              type: string
          required:
            - name
            - email
          description: Who started the run.
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - failed
            - cancelled
          description: >-
            queued until the engine picks the run up; succeeded, failed and
            cancelled are final.
        statusReason:
          description: >-
            Why a cancelled run stopped: `user`, `insufficient_credits` or
            `budget_exceeded`. Null otherwise.
          type:
            - string
            - 'null'
        progress:
          type: number
          description: Progress the engine reports; 0 until it reports any.
        createdAt:
          type: string
          format: date-time
        startedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        endedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        budget:
          description: Most credits the run may spend, if one was set.
          type:
            - number
            - 'null'
        creditsUsed:
          type: number
          description: Credits charged to the run so far.
        error:
          anyOf:
            - type: object
              properties:
                message:
                  type: string
              required:
                - message
            - type: 'null'
          description: Set when status is failed.
        children:
          type: object
          properties:
            total:
              type: number
            queued:
              type: number
            running:
              type: number
            succeeded:
              type: number
            failed:
              type: number
            cancelled:
              type: number
          required:
            - total
            - queued
            - running
            - succeeded
            - failed
            - cancelled
          description: >-
            For engines that run each input as its own job: how many children
            are in each status. GET /v1/runs/{runId}/children lists them.
        links:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
          description: >-
            Related endpoints: self, inputs (owner only), results, outputs,
            files.
        warnings:
          description: >-
            Set when the run was created but a follow-up step, such as adding it
            to a project, failed.
          type: array
          items:
            type: string
      required:
        - id
        - engine
        - name
        - access
        - owner
        - status
        - statusReason
        - progress
        - createdAt
        - startedAt
        - endedAt
        - budget
        - creditsUsed
        - error
        - links
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - VALIDATION_FAILED
                - INVALID_ID
                - INVALID_PARAMETERS
                - INPUT_LIMIT_EXCEEDED
                - NOT_FOUND
                - FORBIDDEN
                - METHOD_NOT_ALLOWED
                - CONFLICT
                - PAYLOAD_TOO_LARGE
                - MISSING_CREDENTIALS
                - INVALID_CREDENTIALS
                - WRONG_ENVIRONMENT
                - CREDENTIALS_EXPIRED
                - CREDENTIALS_REVOKED
                - ACCOUNT_INACTIVE
                - API_ACCESS_NOT_ENABLED
                - INSUFFICIENT_SCOPE
                - SESSION_REQUIRED
                - TOO_MANY_AUTH_FAILURES
                - API_KEY_LIMIT_REACHED
                - ENGINE_NOT_ENABLED
                - DOCS_NOT_AVAILABLE
                - INSUFFICIENT_CREDITS
                - RUN_NOT_COMPLETE
                - ENGINE_SUBMIT_FAILED
                - RATE_LIMITED
                - SERVICE_UNAVAILABLE
                - INTERNAL_ERROR
              description: Stable within /v1; branch on this, not on the message.
            message:
              type: string
              description: Readable explanation, for people.
            details:
              description: >-
                Extra context, e.g. `issues` ({ path, message }[]) for
                validation errors.
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
          required:
            - code
            - message
      required:
        - error
  responses:
    '400':
      description: >-
        The request is malformed. `error.code` is one of `VALIDATION_FAILED`,
        `INVALID_ID`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: VALIDATION_FAILED
              message: The request is malformed.
    '401':
      description: >-
        The API key is missing or not valid. `error.code` is one of
        `MISSING_CREDENTIALS`, `INVALID_CREDENTIALS`, `WRONG_ENVIRONMENT`,
        `CREDENTIALS_EXPIRED`, `CREDENTIALS_REVOKED`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: MISSING_CREDENTIALS
              message: The API key is missing or not valid.
    '402':
      description: >-
        Your organization doesn't have enough credits. `error.code` is one of
        `INSUFFICIENT_CREDITS`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INSUFFICIENT_CREDITS
              message: Your organization doesn't have enough credits.
    '403':
      description: >-
        The key may not do this. `error.code` is one of `INSUFFICIENT_SCOPE`,
        `API_ACCESS_NOT_ENABLED`, `ENGINE_NOT_ENABLED`, `ACCOUNT_INACTIVE`,
        `FORBIDDEN`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INSUFFICIENT_SCOPE
              message: The key may not do this.
    '404':
      description: Not found, or not visible to you. `error.code` is one of `NOT_FOUND`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Not found, or not visible to you.
    '422':
      description: >-
        The parameters or input files don't fit the engine. `error.code` is one
        of `INVALID_PARAMETERS`, `INPUT_LIMIT_EXCEEDED`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_PARAMETERS
              message: The parameters or input files don't fit the engine.
    '500':
      description: >-
        Something went wrong on our side. `error.code` is one of
        `INTERNAL_ERROR`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: Something went wrong on our side.
    '502':
      description: >-
        The engine service rejected or failed the request. `error.code` is one
        of `ENGINE_SUBMIT_FAILED`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ENGINE_SUBMIT_FAILED
              message: The engine service rejected or failed the request.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key from the web app (**Settings → Developer**), sent as
        `Authorization: Bearer rvl_live_…`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.