> ## 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 RevScreen run > Docks a library of small molecules (up to 10,000 per run) into a protein's binding pocket and ranks them by predicted binding strength: virtual screening with AutoDock Vina. static mode holds the protein rigid and is fast; flexible mode lets chosen pocket side chains move and can dock against several protein structures, at a much higher cost per molecule. Each molecule's best poses are kept as files. Progress is not reported while the run works: it shows started, then finished. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `maxMolecules`: 10000, `maxInlineSmiles`: 1000, `maxSmilesLength`: 500, `maxStaticBoxSize`: 30, `maxFlexibleBoxSize`: 80, `maxReceptors`: 10, `maxFlexibleResidues`: 20, `maxExhaustiveness`: 64. How the engine works and how to read its results: [RevScreen documentation](/docs/revscreen). **Scope:** `runs:write`. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/engines/revscreen/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/revscreen/runs: post: tags: - Engine runs summary: Start a RevScreen run description: >- Docks a library of small molecules (up to 10,000 per run) into a protein's binding pocket and ranks them by predicted binding strength: virtual screening with AutoDock Vina. static mode holds the protein rigid and is fast; flexible mode lets chosen pocket side chains move and can dock against several protein structures, at a much higher cost per molecule. Each molecule's best poses are kept as files. Progress is not reported while the run works: it shows started, then finished. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `maxMolecules`: 10000, `maxInlineSmiles`: 1000, `maxSmilesLength`: 500, `maxStaticBoxSize`: 30, `maxFlexibleBoxSize`: 80, `maxReceptors`: 10, `maxFlexibleResidues`: 20, `maxExhaustiveness`: 64. How the engine works and how to read its results: [RevScreen documentation](/docs/revscreen). **Scope:** `runs:write`. operationId: engineRuns.revscreen 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: mode: default: static description: >- static: the protein is held rigid; fast, the usual first pass over a large library (AutoDock Vina on GPU). flexible: chosen pocket side chains can move, and each molecule can be docked against several protein structures; much slower per molecule (GNINA), also reports a neural-network pose score and affinity. type: string enum: - static - flexible box: type: object properties: center: type: array prefixItems: - type: number minimum: -999.999 maximum: 9999.999 - type: number minimum: -999.999 maximum: 9999.999 - type: number minimum: -999.999 maximum: 9999.999 items: false minItems: 3 maxItems: 3 description: >- Centre of the search box as [x, y, z] in Å, in the protein file's own coordinates. Usually the middle of the binding pocket: a RevPocket box can be passed in as is. size: default: - 30 - 30 - 30 description: >- Edge lengths of the search box as [x, y, z] in Å (1 to 30 in static mode, 1 to 80 in flexible mode). Molecules are only placed inside the box: a bigger box finds poses further from the centre but makes the search slower and less thorough. type: array prefixItems: - type: number minimum: 1 maximum: 80 - type: number minimum: 1 maximum: 80 - type: number minimum: 1 maximum: 80 items: false minItems: 3 maxItems: 3 required: - center additionalProperties: false description: >- Where in the protein to dock. In flexible mode, the box for every receptor that does not set its own. receptors: description: >- flexible mode only, and required there: the protein structures to dock into, each with its movable residues. Every molecule is docked against every receptor, so run time grows with the count. In static mode, upload the protein as inputs.protein instead. minItems: 1 maxItems: 10 type: array items: type: object properties: protein: type: string pattern: ^file_[0-9a-fA-F-]{36}$ description: >- The protein structure (PDB file) for this receptor, as an uploaded file id. box: description: >- Search box for this receptor. Leave out to use the top-level box, e.g. when all structures are aligned to the same frame. type: object properties: center: type: array prefixItems: - type: number minimum: -999.999 maximum: 9999.999 - type: number minimum: -999.999 maximum: 9999.999 - type: number minimum: -999.999 maximum: 9999.999 items: false minItems: 3 maxItems: 3 description: >- Centre of the search box as [x, y, z] in Å, in the protein file's own coordinates. Usually the middle of the binding pocket: a RevPocket box can be passed in as is. size: default: - 30 - 30 - 30 description: >- Edge lengths of the search box as [x, y, z] in Å (1 to 30 in static mode, 1 to 80 in flexible mode). Molecules are only placed inside the box: a bigger box finds poses further from the centre but makes the search slower and less thorough. type: array prefixItems: - type: number minimum: 1 maximum: 80 - type: number minimum: 1 maximum: 80 - type: number minimum: 1 maximum: 80 items: false minItems: 3 maxItems: 3 required: - center additionalProperties: false flexible_residues: minItems: 1 maxItems: 20 type: array items: type: string pattern: ^[A-Za-z0-9]:-?\d{1,4}$ description: >- Pocket residues whose side chains may move during docking, as "chain:residue number", e.g. ["A:149", "A:240"]. Pick residues lining the pocket that are likely to shift when a molecule binds. Each one makes docking slower; 2 to 6 is typical. required: - protein - flexible_residues additionalProperties: false exhaustiveness: description: >- flexible mode only: how hard the search tries per molecule. Defaults to 8. Higher values find better poses more reliably and take proportionally longer. Static mode runs a fixed GPU search and does not use it. type: integer minimum: 1 maximum: 64 smiles: description: >- Molecules to dock as SMILES, one per entry, instead of a ligands file. Salts and solvents are stripped (the largest fragment is docked). For more than 1000 molecules, upload a ligands file. minItems: 1 maxItems: 1000 type: array items: type: string maxLength: 500 pattern: ^[A-Za-z0-9@+\-[\]()=#$%:/\\.*]+$ required: - box additionalProperties: false inputs: type: object properties: protein: type: string description: >- static mode: the protein to dock into, as a PDB file with one model. Water and other molecules can stay in; hydrogens are added. In flexible mode give each structure in parameters.receptors instead. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: pdb; up to 50 MB. ligands: type: string description: >- The molecules to dock, up to 10,000: a CSV whose first line is a header with a SMILES column (e.g. "smilesString"), an SDF, or a MOL2 file. Give this or parameters.smiles. A CSV must not have a column called name, id, title or identifier (rename it, e.g. compound_name): the engine then drops those molecules from the results. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: csv, sdf, mol2; up to 100 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: static-library: summary: >- Dock an uploaded library (a CSV with a smilesString column, or an SDF) into one protein's pocket and rank the molecules. value: name: EGFR fragment screen parameters: mode: static box: center: - 12.4 - -3.1 - 22.8 size: - 22 - 22 - 22 inputs: protein: file_… ligands: file_… static-smiles: summary: >- Dock a few molecules given inline as SMILES, with the default 30 Å box. value: name: Three known inhibitors parameters: mode: static box: center: - 12.4 - -3.1 - 22.8 smiles: - COCCOc1cc2ncnc(Nc3cccc(C#C)c3)c2cc1OCCOC - COc1cc2ncnc(Nc3ccc(F)c(Cl)c3)c2cc1OCCCN1CCOCC1 - CC(=O)Nc1ccc(O)cc1 inputs: protein: file_… flexible-two-structures: summary: >- Dock a library against two structures of the same protein, letting two pocket side chains move in each. value: name: Flexible pocket, two conformations parameters: mode: flexible box: center: - 12.4 - -3.1 - 22.8 size: - 24 - 24 - 24 receptors: - protein: file_00000000-0000-4000-8000-000000000001 flexible_residues: - A:790 - A:793 - protein: file_00000000-0000-4000-8000-000000000002 box: center: - 13 - -2.7 - 22.1 size: - 24 - 24 - 24 flexible_residues: - A:790 - A:793 exhaustiveness: 8 inputs: ligands: 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.