> ## 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 RevRelax run > Multi-stage geometry optimisation of up to 50 molecules: a cheap method first, then higher levels of theory, with optional solvent, frequencies, constraints or a transition-state search. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `maxMolecules`: 50, `maxAtoms`: 200, `maxAtomsCareful`: 100, `maxAtomsMeticulous`: 40, `maxSmilesLength`: 2000, `maxConstraints`: 20. How the engine works and how to read its results: [RevRelax documentation](/docs/revrelax). **Scope:** `runs:write`. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/engines/revrelax/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: 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/revrelax/runs: post: tags: - Engine runs summary: Start a RevRelax run description: >- Multi-stage geometry optimisation of up to 50 molecules: a cheap method first, then higher levels of theory, with optional solvent, frequencies, constraints or a transition-state search. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `maxMolecules`: 50, `maxAtoms`: 200, `maxAtomsCareful`: 100, `maxAtomsMeticulous`: 40, `maxSmilesLength`: 2000, `maxConstraints`: 20. How the engine works and how to read its results: [RevRelax documentation](/docs/revrelax). **Scope:** `runs:write`. operationId: engineRuns.revrelax 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: smiles: description: >- Molecules as SMILES, one per line (up to 50, each up to 2000 characters); text after a space on a line and lines starting with # are ignored. Give either this or the structure input file. type: string charge: description: >- Total charge, only for a one-molecule input; otherwise each molecule's own applies (CSV columns, or the structure file's formal charges). anyOf: - type: integer minimum: -10 maximum: 10 - type: 'null' multiplicity: description: Spin multiplicity, only for a one-molecule input. anyOf: - type: integer minimum: 1 maximum: 10 - type: 'null' settings: type: object properties: preset: type: string enum: - reckless - rapid - careful - meticulous description: >- Level of theory, final energy // optimisation steps. reckless: GFN2-xTB // GFN-FF (up to 200 atoms); rapid (default): r2SCAN-D4/vDZP // GFN2-xTB (up to 200 atoms); careful: ωB97X-3c // r2SCAN-D4/vDZP (GPU, up to 100 atoms); meticulous: ωB97M-D3BJ/def2-TZVPPD // ωB97X-3c // r2SCAN-D4/vDZP (GPU, up to 40 atoms). Atom counts include hydrogens. solvent: anyOf: - type: string enum: - water - methanol - ethanol - acetonitrile - acetone - dmso - chloroform - dichloromethane - thf - toluene - benzene - type: 'null' description: >- Implicit solvent for the energies; null (default) is the gas phase. optimize_in_solvent: type: boolean description: >- Also optimise the geometry in the solvent (default false); needs a solvent. frequencies: type: boolean description: >- Compute vibrational frequencies and thermochemistry (default false). transition_state: type: boolean description: >- Search for a transition state instead of a minimum (default false). Needs one 3D structure file, a preset other than reckless, and no constraints. constraints: maxItems: 20 type: array items: type: object properties: coordinate: type: string enum: - bond - angle - dihedral - freeze_atoms description: >- bond (2 atoms, Å), angle (3 atoms, degrees), dihedral (4 atoms, degrees), or freeze_atoms (any number of atoms held in place). atoms: minItems: 1 type: array items: type: integer minimum: 1 maximum: 9007199254740991 description: >- 1-based atom indices, as in the input structure. value: description: >- Value to hold the coordinate at; absent or null holds it where the input has it. Not allowed for freeze_atoms. type: - number - 'null' required: - coordinate - atoms additionalProperties: false description: >- Coordinates held during the optimisation (default none). Needs one 3D structure file, not SMILES. temperature_kelvin: type: number exclusiveMinimum: 0 maximum: 2000 description: >- Temperature for the thermochemistry (with frequencies); default 298.15 K. max_steps: type: integer minimum: 1 maximum: 1000 description: Maximum optimiser steps; default 250. additionalProperties: false description: >- Engine settings. Every key is optional; the engine fills absent ones with its defaults. additionalProperties: false inputs: type: object properties: structure: type: string description: >- Up to 50 molecules, each up to 200 atoms with hydrogens (100 for careful, 40 for meticulous): a CSV with a `smiles` column, a SMI file, or 3D structures as SDF, XYZ, MOL, MOL2 or PDB. Constraints and transition-state searches take one 3D structure. Alternative to parameters.smiles. A file id (`file_…`). Formats: csv, smi, sdf, xyz, mol, mol2, pdb; up to 10 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 additionalProperties: false examples: smiles-batch: summary: >- Three molecules from SMILES (one per line, with names), relaxed with the default rapid preset and energies in water. value: name: Solvent screen parameters: smiles: |- CCO ethanol CC(=O)O acetic_acid c1ccccc1O phenol settings: solvent: water inputs: {} file-frequencies: summary: >- One 3D structure with the careful preset, frequencies, and a dihedral held where the input has it. value: parameters: charge: 0 multiplicity: 1 settings: preset: careful frequencies: true constraints: - coordinate: dihedral atoms: - 1 - 2 - 3 - 4 inputs: structure: file_… transition-state: summary: A transition-state search from a guess structure. value: parameters: settings: preset: rapid transition_state: true frequencies: true inputs: structure: 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' 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. links: type: object propertyNames: type: string additionalProperties: type: string description: 'Related endpoints: self, inputs, 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 - 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.