API

Programmatic access to variant annotations

The API provides programmatic access to the same annotation layer shown in the web interface.

Purpose

The API returns structured annotations for submitted human protein missense variants.

This allows the resource to be used beyond manual search, including in scripts, notebooks, internal tools, and larger analysis workflows.

Endpoint

POST /api/variants

Request format

Submit one or more variants in JSON.

{
  "variants": [
    "Q7Z4H8/A126C",
    "P12235/P144L"
  ]
}

Response format

The response returns one object per queried variant.

{
  "results": [
    {
      "variant_id": "Q7Z4H8/A126C",
      "am_pathogenicity": 0.6158,
      "am_class": "pathogenic",
      "am_label": true,
      "ESM1b_LLR": -10.388,
      "ESM1b_is_pathogenic": true,
      "pred_ddg": -0.353881,
      "pred_ddg_label": false,
      "interface_pdockq": null,
      "interface_label": false,
      "pocket_label": false,
      "mechanistic_label": "Unassigned"
    }
  ]
}

Field definitions

The API returns the same core fields documented on the Documentation page:

• variant_id
• am_pathogenicity
• am_class
• am_label
• ESM1b_LLR
• ESM1b_is_pathogenic
• pred_ddg
• pred_ddg_label
• interface_pdockq
• interface_label
• pocket_label
• mechanistic_label

Field meanings are unchanged between the web interface and the API.

Query rules

Variants should be submitted in protein-level missense notation:

UNIPROT_ID/REFPOSALT

Example:

Q7Z4H8/A126C

Invalid or unsupported variants may return an error or a null result entry.

Example request

curl -X POST https://your-domain/api/variants \
  -H "Content-Type: application/json" \
  -d '{
    "variants": ["Q7Z4H8/A126C", "P12235/P144L"]
  }'

Example use cases

The API is useful when annotations need to be:

• retrieved for many variants at once
• integrated into internal review tools
• added to notebooks or reports
• reused in downstream prioritisation or modelling workflows

Stability and compatibility

The API is designed as a retrieval layer over a fixed annotation schema.

Where possible, field names should remain stable. If new fields are added in future, existing fields should continue to behave consistently.

Limits

The API provides mechanistic annotations only.

It does not perform variant calling, transcript normalisation, genome coordinate conversion, or clinical classification.