> ## 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 RevMut-PMX run > Predicts whether a single amino-acid change in a protein makes a ligand bind more or less tightly, as a change in binding free energy (kcal/mol, negative = tighter) with its statistical error. It simulates the protein with and without the ligand while gradually turning the old residue into the new one (pmx + GROMACS). Needs the protein structure and the ligand posed in its binding site. Runs take hours on many GPUs at once, and cannot be cancelled once submitted. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `mutationsPerRun`: 1, `maxSimulationLengthNs`: 50, `maxProteinMegabytes`: 20. How the engine works and how to read its results: [RevMut-PMX documentation](/docs/revmut-pmx). **Scope:** `runs:write`. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/engines/revmut-pmx/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/revmut-pmx/runs: post: tags: - Engine runs summary: Start a RevMut-PMX run description: >- Predicts whether a single amino-acid change in a protein makes a ligand bind more or less tightly, as a change in binding free energy (kcal/mol, negative = tighter) with its statistical error. It simulates the protein with and without the ligand while gradually turning the old residue into the new one (pmx + GROMACS). Needs the protein structure and the ligand posed in its binding site. Runs take hours on many GPUs at once, and cannot be cancelled once submitted. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `mutationsPerRun`: 1, `maxSimulationLengthNs`: 50, `maxProteinMegabytes`: 20. How the engine works and how to read its results: [RevMut-PMX documentation](/docs/revmut-pmx). **Scope:** `runs:write`. operationId: engineRuns.revmut-pmx 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: mutation: type: object properties: chain: description: >- Chain id of the residue, as in the structure file (column 22 of the ATOM lines). Required when the structure has more than one chain; leave out for a single chain. type: string pattern: ^[A-Za-z0-9]$ position: type: integer minimum: -999 maximum: 9999 description: >- Residue number as written in the structure file (not the position in the sequence). Residues with an insertion code (e.g. 52A) cannot be chosen. from: type: string enum: - A - R - 'N' - D - C - Q - E - G - H - I - L - K - M - F - P - S - T - W - 'Y' - V description: >- One-letter code of the amino acid at that position now. Checked against the structure before the run starts. to: type: string enum: - A - R - 'N' - D - C - Q - E - G - H - I - L - K - M - F - P - S - T - W - 'Y' - V description: One-letter code of the amino acid to put there. required: - position - from - to additionalProperties: false description: >- The single amino-acid change to evaluate, e.g. { chain: "A", position: 45, from: "Y", to: "F" } for A:Y45F. One mutation per run. lambda_schedule: default: simple description: >- How many intermediate steps the residue is changed in. simple: 11, for most mutations. charge_changing: 17, when the mutation adds, removes or flips a charge (D, E, K, R). large_mutation: 21, for big size changes (e.g. G or A to W). Each step runs twice (with and without the ligand) as its own GPU job, so more steps cost proportionally more credits. type: string enum: - simple - charge_changing - large_mutation force_field: default: amber99sb-star-ildn-mut description: >- The physics model for the protein. amber99sb-star-ildn-mut is the recommended default; charmm36m-mut is the CHARMM alternative. The ligand is always described with GAFF2 when given as SDF/MOL2. type: string enum: - amber99sb-star-ildn-mut - charmm36m-mut water_model: default: tip3p description: The water model the protein is surrounded with. type: string enum: - tip3p - spce box_type: default: dodecahedron description: >- Shape of the water box. dodecahedron needs the least water for the same padding, so it is the cheapest. type: string enum: - dodecahedron - cubic - octahedron box_distance_nm: default: 1.2 description: >- Minimum distance, in nanometres, from the protein to the edge of the water box. Larger adds water and makes every step slower. type: number minimum: 0.8 maximum: 3 ion_concentration_m: default: 0.15 description: >- Salt (NaCl) concentration in mol/L. 0.15 is physiological; 0 only adds the ions needed to make the system neutral. type: number minimum: 0 maximum: 1 simulation_length_ns: default: 5 description: >- Simulated time per step, in nanoseconds. Longer lowers the statistical error but run time and credits grow in proportion. type: number minimum: 0.5 maximum: 50 ligand_charge: default: 0 description: >- Net charge of the ligand (sum of its formal charges, e.g. -1 for a carboxylate). Only used when the ligand is given as SDF/MOL2; a wrong value makes the ligand preparation fail or describes it wrongly. type: integer minimum: -5 maximum: 5 required: - mutation additionalProperties: false inputs: type: object properties: protein: type: string description: >- The protein structure (PDB), before the mutation. Only standard amino acids and, optionally, crystal water: remove the ligand, ions and other molecules (the ligand goes in its own input). Hydrogens are rebuilt, so they may be left out. Missing residues or atoms inside a chain make the preparation fail. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: pdb; up to 20 MB. ligand: type: string description: >- The ligand (small molecule) in its binding pose, in the same coordinate frame as the protein (e.g. a docked pose), as SDF or MOL2 with all hydrogens. It is prepared automatically; set parameters.ligand_charge to its net charge. Give either this or ligand_gro + ligand_itp. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: sdf, mol2; up to 5 MB. ligand_gro: type: string description: >- Instead of ligand: the ligand already prepared for GROMACS, its coordinates (GRO) in the protein frame. Needs ligand_itp. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: gro; up to 5 MB. ligand_itp: type: string description: >- Instead of ligand: the ligand's GROMACS topology (ITP) matching ligand_gro, e.g. from ACPYPE or CGenFF. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: itp; up to 5 MB. ligand_prm: type: string description: >- Optional with ligand_gro + ligand_itp: a separate parameter file (PRM) the topology includes. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: prm; up to 5 MB. required: - protein 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 - inputs additionalProperties: false examples: binding-change: summary: >- Does replacing tyrosine 45 of chain A with phenylalanine change how tightly a docked ligand binds? The ligand is prepared automatically from its SDF. value: name: A:Y45F with inhibitor parameters: mutation: chain: A position: 45 from: 'Y' to: F inputs: protein: file_… ligand: file_… charge-change: summary: >- A mutation that removes a charge (aspartate to asparagine) with a negatively charged ligand: more intermediate steps and the ligand charge set. value: name: B:D102N parameters: mutation: chain: B position: 102 from: D to: 'N' lambda_schedule: charge_changing ligand_charge: -1 inputs: protein: file_… ligand: file_… own-ligand-topology: summary: >- Use a ligand already prepared for GROMACS (coordinates + topology) instead of preparing it from an SDF. value: parameters: mutation: position: 88 from: L to: A simulation_length_ns: 10 inputs: protein: file_… ligand_gro: file_… ligand_itp: file_… 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.