> ## 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 BoltzGen run > Designs brand-new proteins, peptides or single-domain antibodies that stick to a chosen target (a protein structure, a protein sequence, or a small molecule), generates many candidates, filters them and keeps a diverse top set of 30. Every run runs under a credit cap (the budget), which this engine requires because it has no uncapped mode; set it high enough that the run can finish, as the engine is stopped the moment spending passes it. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `maxDesigns`: 10, `maxLigands`: 10, `maxTargetChains`: 20, `minNumDesigns`: 1, `maxNumDesigns`: 10000, `minDiffusionBatch`: 1, `maxDiffusionBatch`: 100, `maxLengthSpec`: 200, `maxTargetResidues`: 4000, `maxCcdLength`: 16, `maxSmilesLength`: 1000, `minBudgetCredits`: 10. How the engine works and how to read its results: [BoltzGen documentation](/docs/boltzgen). **Scope:** `runs:write`. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/engines/boltzgen/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/boltzgen/runs: post: tags: - Engine runs summary: Start a BoltzGen run description: >- Designs brand-new proteins, peptides or single-domain antibodies that stick to a chosen target (a protein structure, a protein sequence, or a small molecule), generates many candidates, filters them and keeps a diverse top set of 30. Every run runs under a credit cap (the budget), which this engine requires because it has no uncapped mode; set it high enough that the run can finish, as the engine is stopped the moment spending passes it. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `maxDesigns`: 10, `maxLigands`: 10, `maxTargetChains`: 20, `minNumDesigns`: 1, `maxNumDesigns`: 10000, `minDiffusionBatch`: 1, `maxDiffusionBatch`: 100, `maxLengthSpec`: 200, `maxTargetResidues`: 4000, `maxCcdLength`: 16, `maxSmilesLength`: 1000, `minBudgetCredits`: 10. How the engine works and how to read its results: [BoltzGen documentation](/docs/boltzgen). **Scope:** `runs:write`. operationId: engineRuns.boltzgen 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: protocol: default: protein-anything description: >- What kind of binder to design. protein-anything: a full-size protein binder to a target structure. peptide-anything: a short peptide binder. nanobody-anything: a single-domain antibody binder. protein-small_molecule: a protein that binds the given small molecule(s) instead of a structure. type: string enum: - protein-anything - peptide-anything - protein-small_molecule - nanobody-anything target: description: >- The thing to bind, when it is a protein or complex: refine the uploaded target file, or give the target as a sequence. Leave out for protein-small_molecule (the target is the ligands). type: object properties: chains: description: >- Which chains of the uploaded target file to use. Leave empty to use every chain. Only for a file target. minItems: 1 maxItems: 20 type: array items: type: string pattern: ^[A-Za-z0-9]{1,4}$ binding_residues: description: >- Residues on the target the binder should contact, as chain id to a list of residue numbers (counting from 1), e.g. {"A": [54, 56, 66]}. Guides the binder toward that spot. Each chain listed here must also appear in chains. Only for a file target. type: object propertyNames: type: string pattern: ^[A-Za-z0-9]{1,4}$ additionalProperties: minItems: 1 type: array items: type: integer minimum: 1 maximum: 9007199254740991 sequence: description: >- The target protein as a sequence, instead of uploading a structure file. Use either the target file input or this, not both. type: string maxLength: 4000 pattern: ^[ACDEFGHIKLMNPQRSTVWYX]+$ additionalProperties: false designs: minItems: 1 maxItems: 10 type: array items: type: object properties: length: type: string maxLength: 200 pattern: ^(\d+(\.\.\d+)?|[ACDEFGHIKLMNPQRSTVWYX]+)+$ description: >- How long the designed binder is. Give a range like "80..120" to let the engine choose a length in that window, a fixed sequence like "AAVTTTTPPP" to pin residues, or a mix like "3..5C6C3". A wider range explores more lengths. cyclic: default: false description: >- Design a head-to-tail ring instead of a straight chain. Only for the peptide and nanobody protocols. Rings are more rigid and often more stable. type: boolean chain_id: description: >- Optional id for this designed chain in the output structure. Leave empty to have the engine assign one (A, B, ...), skipping any id used by target.chains. type: string pattern: ^[A-Za-z0-9]{1,4}$ required: - length additionalProperties: false description: The binder chain(s) to design. At least one. ligands: default: [] description: >- The small molecule target(s), for protein-small_molecule only. At least one for that protocol; not allowed otherwise. maxItems: 10 type: array items: type: object properties: ccd: description: >- A known small molecule by its Protein Data Bank code, e.g. "ATP". Give this or smiles, not both. type: string maxLength: 16 pattern: ^[A-Z0-9]+$ smiles: description: >- A small molecule written as SMILES. Give this or ccd, not both. type: string maxLength: 1000 pattern: ^[A-Za-z0-9@+\-[\]()=#$%:/\\.*]+$ chain_id: description: >- Optional id for this molecule in the output structure. type: string pattern: ^[A-Za-z0-9]{1,4}$ additionalProperties: false num_designs: default: 10 description: >- How many candidate designs to generate before filtering. More designs explore more of the space and usually give better final binders, but cost more compute (and credits). The engine then keeps a fixed diverse top set (30) of whatever passes its filters. type: integer minimum: 1 maximum: 10000 diffusion_batch_size: description: >- Advanced: how many designs are generated together in one batch. Leave empty to let the engine choose (1 when num_designs is under 100, otherwise 10). All designs in a batch share one sampled length, so a large batch samples fewer lengths. type: integer minimum: 1 maximum: 100 required: - designs additionalProperties: false inputs: type: object properties: target: type: string description: >- The target structure to bind: a protein (or complex) in a PDB or mmCIF file. Required for every protocol except protein-small_molecule, unless you give the target as a sequence in parameters.target.sequence instead. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: cif, pdb; 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: protein-binder-to-a-structure: summary: >- Design protein binders of 80-120 residues to an uploaded target structure, aimed at four residues of chain A. value: name: PD-L1 binders parameters: protocol: protein-anything target: chains: - A binding_residues: A: - 54 - 56 - 66 - 115 designs: - length: 80..120 num_designs: 20 inputs: target: file_target_structure peptide-binder-to-a-sequence: summary: >- Design short cyclic peptide binders to a target given as a sequence, with no file upload. value: name: Cyclic peptide binders parameters: protocol: peptide-anything target: sequence: >- MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG designs: - length: 12..18 cyclic: true num_designs: 10 inputs: {} protein-binder-to-a-small-molecule: summary: >- Design a protein that binds a given small molecule (here caffeine as SMILES); no target structure. value: name: Small-molecule binder parameters: protocol: protein-small_molecule designs: - length: 60..100 ligands: - smiles: CN1C=NC2=C1C(=O)N(C(=O)N2C)C num_designs: 10 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.