> ## 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 RevCryptic run > Cryptic pocket discovery: builds a conformational ensemble of a protein, finds the pockets that open across it and ranks them by crypticity, druggability and persistence (Lacuna), with Vina boxes, Boltz constraints and site PDBs per pocket. Optionally builds a cosolvent MD system around the receptor (CoSolvKit). Minutes for the default settings. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `maxConformers`: 100, `maxPockets`: 50, `maxCosolvents`: 10. **Scope:** `runs:write`. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/engines/revcryptic/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/revcryptic/runs: post: tags: - Engine runs summary: Start a RevCryptic run description: >- Cryptic pocket discovery: builds a conformational ensemble of a protein, finds the pockets that open across it and ranks them by crypticity, druggability and persistence (Lacuna), with Vina boxes, Boltz constraints and site PDBs per pocket. Optionally builds a cosolvent MD system around the receptor (CoSolvKit). Minutes for the default settings. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `maxConformers`: 100, `maxPockets`: 50, `maxCosolvents`: 10. **Scope:** `runs:write`. operationId: engineRuns.revcryptic 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: stage: default: pockets description: >- pockets: cryptic pocket discovery (Lacuna). both: pocket discovery, then a CoSolvKit cosolvent system aligned on a chosen pocket. cosolvent: the cosolvent system only, for the whole receptor. md: run cosolvent MD on a GPU, on the system a completed cosolvent run already built -- it takes `md.source_pipeline_id` (a finished `cosolvent` or `both` run that set `cosolvent.execute`) instead of a receptor, and is the stage that produces a trajectory. type: string enum: - pockets - both - cosolvent - md accession: description: >- A PDB ID or UniProt accession to fetch the receptor from, instead of the structure input file. type: string pattern: >- ^([0-9][A-Za-z0-9]{3}|[A-NR-Za-nr-z][0-9][A-Za-z0-9]{3}[0-9]|[OPQopq][0-9][A-Za-z0-9]{3}[0-9])$ pockets: description: Pocket discovery options (stages pockets and both). type: object properties: conformers: default: 20 description: Conformers in the generated ensemble. type: integer minimum: 2 maximum: 100 backend: default: auto description: >- How the ensemble is made. auto: normal-mode analysis (seconds). nma: the same, explicitly. openmm: a short CPU MD ensemble; slower (an hour or more), more realistic openings. type: string enum: - auto - nma - openmm detector: default: alpha description: >- Pocket detection per conformer: alpha spheres or a surface grid. type: string enum: - alpha - surface - surface-fusion rank_by: default: learned description: How pockets are ranked. type: string enum: - learned - crypticity - druggability - balanced - persistence top: default: 10 description: Pockets to report. type: integer minimum: 1 maximum: 50 min_druggability: default: 0 description: Drop pockets below this druggability (0–1). type: number minimum: 0 maximum: 1 min_persistence: default: 0 description: >- Drop pockets open in less than this fraction of conformers (0–1). type: number minimum: 0 maximum: 1 min_crypticity: default: 0 description: Drop pockets below this crypticity (0–1). type: number minimum: 0 maximum: 1 homodimer: default: false description: >- Treat the receptor as a homodimer (symmetric pockets). type: boolean no_sequence: default: false description: Skip the sequence-based features in ranking. type: boolean emit_vina_boxes: default: true description: Write an AutoDock Vina box per pocket. type: boolean emit_boltz_constraints: default: true description: Write a Boltz pocket constraint per pocket. type: boolean emit_pocket_pdbs: default: true description: Write a site PDB per pocket. type: boolean emit_conformers: default: false description: Also keep the ensemble conformers. type: boolean ensemble: description: >- Score the conformers of a finished cosolvent MD run instead of generating an ensemble. Overrides conformers and backend. type: object properties: source_pipeline_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: >- A finished md run of this engine, whose trajectory becomes the ensemble. max_frames: default: 50 description: >- Frames to score. The trajectory is strided evenly to this many, so the whole run is sampled rather than its first frames. type: integer minimum: 2 maximum: 200 selection: default: protein description: >- mdtraj atom selection kept in each frame. The default drops the water and probes, which Lacuna cannot match to the receptor. type: string minLength: 1 maxLength: 200 required: - source_pipeline_id additionalProperties: false additionalProperties: false cosolvent: description: >- Cosolvent system options; required for stages both and cosolvent. type: object properties: cosolvents: minItems: 1 maxItems: 10 type: array items: type: object properties: name: type: string minLength: 1 maxLength: 80 description: >- Probe name. A library probe needs nothing else: benzene, toluene, phenol, pyrimidine, imidazole, propane, cyclohexane, methanol, ethanol, isopropanol, ethylene glycol, acetonitrile, acetamide, N-methylacetamide, formamide, urea, dimethyl sulfoxide, N,N-dimethylformamide, acetate, methylammonium, benzamidine. smiles: description: Required for a probe not in the library. type: string minLength: 1 maxLength: 500 resname: description: >- Residue name in the built system (1–3 characters). type: string pattern: ^[A-Z0-9]{1,3}$ concentration: description: >- Molar concentration. Defaults to the library value; give this or copies for a custom probe. type: number exclusiveMinimum: 0 maximum: 5 copies: description: >- A fixed number of copies, instead of a concentration. type: integer minimum: 1 maximum: 100000 required: - name additionalProperties: false description: Probe molecules to place around the receptor. md_format: default: openmm description: >- Format of the built system. openmm is required for add_repulsive. type: string enum: - openmm - amber - gromacs - charmm clean_protein: default: true description: Repair and protonate the receptor first. type: boolean keep_heterogens: default: false description: Keep ligands, ions and other heterogens. type: boolean box: default: orthorhombic description: >- Shape of the solvent box. orthorhombic sizes each axis from the receptor's extent along it; cubic sizes every axis from the receptor's circumscribing sphere, which is CoSolvKit's own behaviour and costs 1.8-2x the volume for anything non-spherical. Both keep 12 Å of solvent on every face. Measured on a 102-residue construct: 415 vs 745 nm³, 37k vs 67k atoms, 952 vs 533 ns/day, with the protein never closer than 20 Å to its periodic image over 1 ns. Ignored when radius is set, which builds a cube by definition. type: string enum: - orthorhombic - cubic radius: default: null description: >- Å. A sphere of this radius instead of a box around the receptor. anyOf: - type: number exclusiveMinimum: 0 maximum: 200 - type: 'null' solvent_smiles: default: H2O description: The bulk solvent; H2O for water. type: string minLength: 1 maxLength: 200 solvent_copies: default: null description: >- Fixed number of solvent molecules; null fills the box. anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' membrane: default: false description: Embed the receptor in a membrane. type: boolean lipid_type: default: POPC type: string enum: - POPC - POPE - DLPC - DLPE - DMPC - DOPC - DPPC memb_cosolv_placement: default: both description: 'With a membrane: which side(s) the probes go.' type: string enum: - both - outside - inside add_repulsive: default: false description: >- Add probe–probe repulsion so probes do not aggregate (openmm only). type: boolean repulsive_residues: default: [] description: >- Residue names the repulsive force applies to. Leave empty to apply it to every probe in `cosolvents` (their `resname` values), which is almost always what you want. maxItems: 1000 type: array items: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: string maxLength: 20 epsilon: default: 0.01 description: Repulsion depth. type: number minimum: 0 maximum: 10 sigma: default: 10 description: Repulsion range. type: number minimum: 0 maximum: 100 execute: default: false description: >- Build the solvated system (system.pdb/.xml) on the server. false writes only the CoSolvKit input deck. Set this when the run is meant to feed `stage: "md"` -- that stage needs a built system, not a deck. CoSolvKit also runs no MD here; use `stage: "md"` for the simulation. type: boolean pocket_rank: default: 1 description: >- Stage both: the ranked pocket the analysis deck is centred on. type: integer minimum: 1 maximum: 50 required: - cosolvents additionalProperties: false md: description: Cosolvent MD options; required for stage md. type: object properties: source_pipeline_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: >- A finished run of this engine that built a cosolvent system (stage both or cosolvent with execute). Its system.xml is what gets simulated. ns: type: number exclusiveMinimum: 0 maximum: 1000 description: >- Production length in nanoseconds. Throughput depends on the system: a 612k-atom box measured 26.9 ns/day on one A10G. seed: default: null description: Integrator seed; null leaves it random. anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' temperature_k: default: 300 description: K. type: number minimum: 1 maximum: 1000 pressure_bar: default: 1 description: Barostat pressure for the NPT phases. type: number minimum: 0 maximum: 1000 heat_ps: default: 100 description: Heating from 0 K, in ps. 0 skips it. type: number minimum: 0 maximum: 10000 equil_ps: default: 500 description: >- Restrained NPT equilibration, in ps. Cutting this short is the usual cause of an unstable production run. type: number minimum: 0 maximum: 100000 restraint_kcal_a2: default: 1 description: >- Positional restraint on the receptor during equilibration. type: number minimum: 0 maximum: 100 timestep_fs: default: 4 description: >- Integration timestep. 4 fs relies on the hydrogen mass repartitioning CoSolvKit builds into the system. type: number minimum: 0.5 maximum: 5 frame_ps: default: 10 description: How often a frame is written to the trajectory. type: number exclusiveMinimum: 0 maximum: 10000 checkpoint_ps: default: 1000 description: >- How often state is checkpointed to storage. A retried job resumes from the last checkpoint instead of restarting. type: number exclusiveMinimum: 0 maximum: 100000 metadynamics: default: false description: >- Well-tempered metadynamics on the protein heavy-atom RMSD, which is how the CoSolvKit paper drives cryptic openings. Off runs plain cosolvent MD, the cheaper unbiased baseline. type: boolean metad_pace_ps: default: 500 description: >- A hill is deposited this often. It must be well under ns: a run shorter than the pace deposits no hills at all. type: number exclusiveMinimum: 0 maximum: 100000 metad_height_kcal: default: 0.3 description: Initial hill height, scaled down as the bias builds. type: number exclusiveMinimum: 0 maximum: 10 metad_sigma_a: default: 0.5 description: >- Gaussian width along the RMSD coordinate, in angstrom. type: number exclusiveMinimum: 0 maximum: 10 metad_bias_factor: default: 15 description: >- Well-tempered bias factor. Higher explores further from the starting structure. type: number exclusiveMinimum: 1 maximum: 1000 metad_max_rmsd_a: default: 10 description: Upper edge of the bias grid, in angstrom. type: number exclusiveMinimum: 0 maximum: 100 required: - source_pipeline_id - ns additionalProperties: false additionalProperties: false inputs: type: object properties: structure: type: string description: >- The receptor (PDB or mmCIF). Give this or parameters.accession. Stages both and cosolvent need a PDB. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: pdb, cif, mmcif, ent; up to 50 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: accession: summary: >- Cryptic pockets of KRAS G12C (PDB 4OBE), fetched by ID, with the default 20-conformer normal-mode ensemble. value: name: KRAS cryptic pockets parameters: accession: 4OBE inputs: {} druggable-cryptic: summary: >- An uploaded receptor; ranks by crypticity and keeps the five best pockets with druggability of at least 0.5. value: parameters: pockets: rank_by: crypticity top: 5 min_druggability: 0.5 inputs: structure: file_… pockets-and-cosolvent: summary: >- Pocket discovery, then a solvated benzene/methanol cosolvent system built on the server and aligned on the top pocket. value: parameters: stage: both cosolvent: cosolvents: - name: benzene - name: methanol execute: true inputs: structure: file_… cosolvent-md: summary: >- A 0.1 ns pilot on the system a finished cosolvent run built. The whole receptor comes from that run, so this request carries no structure. value: name: SOST cosolvent MD pilot parameters: stage: md md: source_pipeline_id: 00000000-0000-0000-0000-000000000000 ns: 0.1 inputs: {} cosolvent-md-metadynamics: summary: >- A 1 ns biased pilot: well-tempered metadynamics on the protein heavy-atom RMSD, with the hill interval cut to 100 ps so the bias actually forms over a run this short (the paper's 500 ps pace would deposit two hills). value: parameters: stage: md md: source_pipeline_id: 00000000-0000-0000-0000-000000000000 ns: 1 metadynamics: true metad_pace_ps: 100 inputs: {} pockets-from-md-trajectory: summary: >- Cryptic pockets scored on a finished md run's trajectory instead of a generated ensemble: 20 evenly strided frames, protein atoms only. value: parameters: pockets: ensemble: source_pipeline_id: 00000000-0000-0000-0000-000000000000 max_frames: 20 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' 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.