StabiliNNator API Reference

This document describes the network API used to submit and monitor Protein Stability Prediction (StabiliNNator) jobs. The envelope is shared with every other BV-BRC service — only the values payload is service-specific.

Scope. This is the AppService JSON-RPC interface — the one the web form talks to when you click Submit Job. The public REST data API at https://www.bv-brc.org/api/ (documented at https://www.bv-brc.org/api/doc/) is a different endpoint and is not covered here.

Transport

JSON-RPC 2.0 over HTTPS POST, with the BV-BRC-specific MIME type application/jsonrpc+json (not plain application/json).

POST <serviceAPI>
Content-Type: application/jsonrpc+json
Authorization: <BV-BRC auth token>
X-Requested-With: false

Request body:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "AppService.start_app2",
  "params": ["StabiliNNator", { ...values... }, { ...start_params... }]
}

Response on success:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [ { "id": "<task-id>", "app": { "id": "StabiliNNator" }, ... } ]
}

The current production AppService endpoint is https://www.bv-brc.org/services/AppService.

Authentication

Every call requires a BV-BRC auth token in the Authorization header. The UI obtains one through the login flow; for programmatic use see the p3-login / p3-token tools shipped with the BV-BRC CLI.

Parameters

The values object mirrors the app spec in app_specs/StabiliNNator.json.

Field

Type

Required

Default

Description

input_file

wsfile (ws://...)

yes

—

Protein structure in PDB or mmCIF format. Must contain standard amino acids with CA atoms

analysis_type

enum

yes

both

proline | disulfide | both

output_path

folder (ws://...)

yes

—

Workspace folder where the job result directory will be created

output_file

string

yes

—

Job result name; results land at ${output_path}/.${output_file}/

theme

enum

no

bvbrc

Report styling: bvbrc | editorial. Presentation only

accelerator

enum

no

cpu

cpu | gpu. CPU is recommended and normally faster — see Choosing a device below

hidden_dim

int

no

32

Network hidden dimension. Both shipped models were trained with 32; change only for custom-trained models

dry_run

boolean

no

false

Validate inputs and workspace access, then stop without predicting

Workspace files use the ws://<user>@BVBRC/<path> URI scheme.

Validation rules enforced by the service

App-StabiliNNator.pl rejects the submission before running any prediction if:

  1. output_path is absent.

  2. output_file is absent. Both are checked explicitly in the service script — results are written to ${output_path}/.${output_file}/, so a missing name has nowhere valid to land.

  3. input_file is absent.

  4. The input parses as neither PDB (an ATOM/HETATM record) nor mmCIF (a data_/loop_ block with _atom_site. records).

analysis_type is validated against its enum by the framework before the service script runs.

Choosing a device

accelerator defaults to cpu, and that is the recommended setting. The two models are 14–22 KB; CUDA initialization costs several seconds, which exceeds the compute it saves. Setting gpu requests a GPU and, if CUDA is unavailable at runtime, the job fails rather than silently falling back.

Note that jobs are scheduled on a GPU partition regardless of this setting. That is a placement constraint — the shared container image is staged on those nodes — and not a statement about how inference runs.

Start parameters

The start_params (3rd argument) is a bag of UI hints attached by the Web form: parent_id, workflow_id, comment. Pass {} if you have nothing to set.

Preflight

The AppService calls preflight internally before scheduling; clients do not call it directly. StabiliNNator reports a fixed estimate, independent of input size:

{
  "cpu": 2,
  "memory": "1G",
  "runtime": 600,
  "storage": "1G",
  "policy_data": { "gpu_count": 0, "partition": "gpu2" }
}

The 10-minute allowance is dominated by container staging rather than inference, which is sub-second. gpu_count is 0 because inference runs on CPU.

Results

On success the workspace contains a job directory at ${output_path}/.${output_file}/, and the task’s output_files lists its contents:

${output_path}/.${output_file}/
├── stabilinnator_report.html        # fixed name — the user-facing entry point
├── <input>_proline.pdb              # probability in the B-factor column
├── <input>_disulfide.pdb
├── <input>_proline_summary.tsv      # ranked, highest probability first
├── <input>_disulfide_summary.tsv
└── <input>_summary.json             # top 25 sites per analysis

<input> is the basename of the input structure. Files for an analysis that was not requested are absent. The report filename is fixed, so a client can locate it without knowing the input name.

<input>_summary.json is the machine-readable entry point:

{
  "input": "crambin.pdb",
  "analysis_type": "both",
  "proline": {
    "top_sites": [
      { "rank": 1, "chain": "A", "pos": 21, "icode": "",
        "residue": "THR", "probability": 0.97 }
    ]
  },
  "disulfide": {
    "cys_sites": [
      { "rank": 1, "chain": "A", "pos": 3, "icode": "",
        "residue": "CYS", "probability": 1 }
    ]
  }
}

Sites carry "note": "already PRO" where a high-scoring proline position is already a proline and therefore not an actionable substitution.

Example request — both analyses

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "AppService.start_app2",
  "params": [
    "StabiliNNator",
    {
      "input_file": "ws://awilke@BVBRC/home/structures/crambin.pdb",
      "analysis_type": "both",
      "output_path": "ws://awilke@BVBRC/home/jobs/",
      "output_file": "crambin-stability-2026-08-25"
    },
    {}
  ]
}

Example request — disulfide only, from a predicted structure

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "AppService.start_app2",
  "params": [
    "StabiliNNator",
    {
      "input_file": "ws://awilke@BVBRC/home/jobs/.spike-boltz/predictions/rank_1.pdb",
      "analysis_type": "disulfide",
      "output_path": "ws://awilke@BVBRC/home/jobs/",
      "output_file": "spike-disulfide"
    },
    { "comment": "prefusion stabilization candidates" }
  ]
}

Chaining the two services this way — predict a structure, then score it for stabilizing mutations — is the common workflow.

See also