Volt documentation

API reference, outputs, and model confidence guidance for Volt workflows.

Structure Prediction 101

Volt uses a state-of-the-art deep learning model to predict the three-dimensional structures of proteins and their complexes with other proteins, nucleic acids, and small molecules. The model was trained on the Protein Data Bank (PDB), the largest public repository of experimentally determined molecular structures, along with sequence databases that capture evolutionary relationships across millions of known proteins. By learning which amino acid sequences fold into which structures across biology, the model can generate accurate structure predictions for novel sequences it has never seen.

At its core, the deep learning approach works by feeding structured inputs into a neural network that has learned to analyze the relationships within that data. For a given prediction job, inputs include the amino acid sequence itself as well as a multiple sequence alignment (MSA): a set of related sequences from evolutionarily distant organisms that reveal which positions tend to co-vary. Co-variation between residue positions is a strong signal that those positions are spatially close or functionally coupled in the folded structure. The model integrates these signals to infer plausible geometries for how a protein folds internally and how it might interact with other molecules.

For each job, Volt generates multiple independent structure predictions using a diffusion-based sampling process, similar in concept to how image generation models produce varied outputs from the same prompt. This gives a distribution of plausible conformations rather than a single answer, which is valuable for understanding flexibility and assessing prediction robustness.

Confidence metrics

Each prediction comes with built-in confidence signals that indicate how reliable different parts of the structure are. These are not experimental measurements; they are the model's own estimates of its certainty:

pLDDT

Per-residue local confidence, scored 0-100. High values (above ~70) indicate well-modeled regions. Low values often correspond to disordered or flexible segments.

PAE

Pairwise Aligned Error. Estimates the expected positional error between pairs of residues. Low PAE between two regions means the model is confident about their relative orientation, which is particularly useful for assessing domain arrangement and interfaces.

iPTM

Interface predicted TM-score. Measures the model's confidence in the overall accuracy of a chain-chain interface. Values above ~0.8 generally indicate a high-confidence interaction; below ~0.5 is low confidence.

Consistency

A Volt-computed metric that summarizes how reproducibly the same inter-chain contacts appear across the set of generated predictions. High consistency suggests a more stable, recurrent interface rather than an artifact of one sample.

Confidence metrics are useful for prioritizing which predictions to investigate further, but they do not replace experimental validation. A high-confidence prediction is a strong hypothesis, not a confirmed structure.

Overview

Volt supports both a web UI workflow and a public API under /api/v1. The public API is designed for lab pipelines, notebooks, and automation agents that need to submit runs, monitor progress, inspect jobs, and download outputs.

What you can do

Submit runs, list runs/jobs, check run status, and download completed job outputs as ZIP files.

What you should monitor

Run/job status plus confidence metrics like pLDDT, PAE, iPTM, and cross-model contact consistency.

Quick start

1. Create an API key

Logged-in users can create API keys from API keys. Keys are permission-scoped and tied to a group.

2. Read the API agent instructions

Volt provides a machine-readable guide at /api/v1/agent that is useful for automation tools and LLM agents.

3. Test your key

Call GET /api/v1/ to verify authentication and view key permissions. 

curl -sS https://runvolt.io/api/v1/ \
  -H "X-API-Key: <YOUR_API_KEY>"

The response wrapper uses success, message, and data.

API Authentication

Most public API endpoints require an API key. Send the key in either the X-API-Key header (preferred) or Authorization: Bearer ....

Headers

X-API-Key: ... or Authorization: Bearer ...

Permissions

Use write for submission and other mutating actions. Read-only endpoints, including output downloads, accept read or write.

Public API requests are rate-limited per API key. Current server behavior allows one API call per key every 5 seconds.

Keys are associated with a single group, so list/status/download operations are automatically scoped to that group.

API Endpoints

Primary public endpoints currently available under /api/v1:

Method Path Permission Purpose
GET /api/v1/agent None Returns markdown instructions for programmatic/agent integrations.
GET /api/v1/ Any valid key Returns API key info, associated user/group, and allowed actions.
POST /api/v1/run/submit write Submit a run with explicit jobs.
POST /api/v1/run/list read or write List runs in the API key's group.
POST /api/v1/run/status read or write Fetch a run status summary by run ID.
POST /api/v1/run/info read or write Fetch run metadata and job counts by run ID.
POST /api/v1/run/list/jobs read or write List jobs for a run (includes job-level analysis summary when available).
POST /api/v1/run/cancel write Cancel a run and all its pending jobs.
POST /api/v1/run/screen write Submit a pairwise screen: list A × list B generates one job per pair.
POST /api/v1/job/status read or write Fetch status for a single job by job ID.
POST /api/v1/job/info read or write Fetch job metadata and the original input payload.
GET /api/v1/job/{job_id}/download read or write Download completed job outputs as a ZIP archive.
POST /api/v1/job/output/list read or write List per-artifact outputs for a completed job.
POST /api/v1/job/output/get read or write Download one artifact by output ID.

Exact input requirements and examples for each endpoint are in the cards below.

Reference
Auth
Runs
Screen
Jobs
Outputs

API Example Workflow

Typical flow: verify key, submit a run or screen, poll status, list jobs, then download completed outputs.

Option A: Submit a run (explicit jobs)

curl -sS -X POST https://runvolt.io/api/v1/run/submit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "name": "TP53 + pifithrin",
    "description": "Example API submission",
    "notify_by_email": false,
    "jobs": [
      {
        "name": "TP53 + pifithrin job",
        "chains": [
          {"name": "TP53", "type": "protein", "value": "MEEPQSDPSVEPPLSQETFSDLWK..."},
          {"name": "Pifithrin", "type": "ligand", "value": "CC1=CC=C(C=C1)C(=O)CN2C3=C(CCCC3)SC2=N.Br"}
        ]
      }
    ]
  }'

Use /api/v1/agent for the latest payload guidance and integration conventions.

Option B: Submit a pairwise screen

Use /run/screen instead of /run/submit when you want to test every combination of two lists of molecules. The server generates one job per A×B pair automatically. 

curl -sS -X POST https://runvolt.io/api/v1/run/screen \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "name": "MDM2 inhibitor screen",
    "description": "Screen MDM2 against a compound library",
    "list_a": [{"uniprot_id": "Q00987"}],
    "list_b": [
      {"name": "aspirin", "type": "ligand", "value": "CC1=CC=C(C=C1)C(=O)O"},
      {"name": "ibuprofen", "type": "ligand", "value": "CC(C)Cc1ccc(cc1)C(C)C(=O)O"}
    ]
  }'

Both /run/submit and /run/screen return a run_id immediately. Poll /run/status to track progress.

Check run status

curl -sS -X POST https://runvolt.io/api/v1/run/status \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{"run_id":"<RUN_ID>"}'

List jobs for a run

curl -sS -X POST https://runvolt.io/api/v1/run/list/jobs \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{"run_id":"<RUN_ID>"}'

Download outputs for a completed job

curl -L https://runvolt.io/api/v1/job/<JOB_ID>/download \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -o job_outputs.zip

Add ?type=structure for CIF files only or ?type=data for JSON analysis only. Use POST /api/v1/job/output/list and POST /api/v1/job/output/get when you want a specific artifact instead of a ZIP archive.

Troubleshooting

401 Unauthorized

Check the API key format and confirm the key is active and not expired.

403 Forbidden

The key is valid, but it likely lacks the required action. Read-only endpoints require read or write, while mutating endpoints require write.

404 Not found

Run/job IDs must exist and belong to the same group as the API key.

429 Rate limit exceeded

Slow down polling. Current public API behavior allows one request per key every 5 seconds.

Missing analysis fields

Analysis summaries are generated when supported outputs are available. Some jobs may complete without every confidence summary artifact.

Model Confidence

Volt exposes confidence-related summaries to help prioritize follow-up work. These metrics are useful, but they should be treated as decision support signals, not proof of biological truth.

pLDDT

Per-token / local confidence indicator. Useful for identifying uncertain regions or flexible segments.

PAE

Pairwise aligned-error estimate. Lower values generally indicate more reliable relative positioning.

iPTM

Interface confidence signal for chain-pair interactions. Useful when assessing complex interfaces.

Consistency

Cross-model contact recurrence summary. Higher consistency can indicate more stable contact patterns across sampled models.

Where confidence data appears

  • Job list responses can include a job analysis object.
  • Downloaded outputs include per-prediction *.analysis.json files and an analysis_summary.json summary file when available.
  • Chain-pair summaries include statistics such as pae, plddt, iptm, and consistency.

Practical interpretation: use confidence metrics to rank hypotheses and select experiments, then validate with orthogonal evidence (assays, literature, controls, or additional modeling).

Outputs

The job download endpoint returns a ZIP archive containing available outputs for the job. Output availability can vary by model/run. When you need an individual artifact instead, use POST /api/v1/job/output/list followed by POST /api/v1/job/output/get.

Common files

  • <prediction_id>.cif structure files for generated predictions.
  • <prediction_id>.analysis.json per-prediction confidence/contact summary files.
  • analysis_summary.json cross-prediction analysis summary.

Job-level API analysis summary

For convenience, Volt stores a compact analysis summary on the job record (exposed through run job listing). This summary includes chain-pair level fields such as contact counts, consistency, and confidence statistic ranges.

Limitations & Validation

High-confidence model outputs can still be incomplete, context-dependent, or wrong for the exact biological system and assay conditions you care about.

Treat structures and interfaces as hypotheses. Validate important conclusions independently before relying on them in critical scientific or business decisions.

Read model limitations About Volt