REST API Documentation

Overview

FABIAN-variant provides a RESTful API for programmatic access. Requests and responses use JSON, allowing integration into automated analysis pipelines.

Base URL: https://fabianapp.org/variant26/api/v1

Live API

The form below allows testing the API directly in the browser:

Authentication

The API is open and does not require authentication. The following rate limits apply per IP address:

3 concurrent jobs
10 requests per 30 seconds, applied to all endpoints except status polling

If you need higher limits for your research, please contact us.

Endpoints

Submit analysis

POST /variant26/api/v1/analyse
Returns immediately with a job ID that can be used to poll for status.
Request header: Content-Type: application/json

Request body parameters:

Field	Type	Required	Description
`mode`	string	Yes	One of: `single`, `single_seq`, `batch`, `batch_seq`, `vcf`
`genome`	string	No	`hg38` (default), `hg19`, `mm39`, or `mm10`
`single_variant`	string	*	Variant in chromosomal notation (required for mode `single`)
`single_ref`	string	*	Reference sequence (required for mode `single_seq`)
`single_alt`	string	*	Variant sequence (required for mode `single_seq`)
`batch_variants`	string	*	Multiple variants, one per line (required for mode `batch`)
`batch_ref_alt`	string	*	Multiple Ref/Alt pairs, space-separated per line (required for mode `batch_seq`)
`vcf_content`	string	*	Base64-encoded VCF file content (required for mode `vcf`)
`tfs_filter`	string	No	`all` (default), `known`, or `names`
`tfs_custom_names`	string	*	Space-separated TF names (required when `tfs_filter` is `names`)
`sources`	array	No	`JASPAR-TFFM` (default), `JASPAR-PWM` (default), `HOCOMOCO` (default), `CIS-BP`, `SwissRegulon`, `Factorbook`, `SELEX`, `UniPROBE`, `HOMER`, `hPDI`. Each source is governed by its own license terms. See Acknowledgements before redistributing results.
`heterodimer`	string	No	`exclude` (default), `merge`, or `show`. Controls heterodimer TFs (e.g. JUND::FOS): exclude omits them, merge includes them when a component TF is selected, show includes all.
`dl_scoring`	boolean	No	Run deep learning scoring (default: `true`). Results are returned as a separate download URL.
`same_species`	boolean	No	Restrict to models derived from data for the selected species (default: false)
`email`	string	No	Email address for notification when job completes
`min_coverage`	integer	No	Minimum coverage threshold for VCF mode (default: 0, no filtering)
`ignore_genotype`	boolean	No	Ignore GT field and analyse all ALT alleles (default: false)
`regions_filter`	string	No	Region filter mode for VCF: `include` (custom coordinates), `gene` (variants near genes), or `range` (variants by position). Omit to process the entire file.
`regions_coordinates`	string	No	Genomic coordinates for region filtering (e.g. `chr1:1000-2000`), one per line
`regions_genes`	string	No	Gene names for region filtering, one per line
`variant_range_start`	integer	*	First variant to process, by position in the VCF (1-based, inclusive). Required when `regions_filter` is `range`
`variant_range_end`	integer	*	Last variant to process, by position in the VCF (1-based, inclusive, must be ≥ `variant_range_start`). Required when `regions_filter` is `range`
`gwas`	boolean	No	Filter VCF variants by GWAS catalog overlap (default: false)
`gnomad_homozygous_max`	integer	No	Maximum gnomAD homozygous count for VCF filtering (default: 0, no filtering)
`gnomad_present_max`	integer	No	Maximum gnomAD allele count for VCF filtering (default: 0, no filtering)
`mgp_present_max`	integer	No	Maximum MGP strain count for mouse VCF filtering (default: 0, no filtering)

Response (201 Created):

{
  "job_id": "1735912345_12345",
  "status": "submitted",
  "status_url": "/variant26/api/v1/jobs/1735912345_12345/status",
  "results_url": "/variant26/api/v1/jobs/1735912345_12345/results",
  "web_url": "/variant26/1735912345_12345"
}

Check status

GET /variant26/api/v1/jobs/{job_id}/status
Possible status values: pending (queued), running (processing), completed (finished), failed (error occurred)

Response (200 OK):

{
  "job_id": "1735912345_12345",
  "status": "running",
  "progress": {
    "current_size": 12345,
    "variant_count": 50,
    "messages": ["Processing variant 50 of 100..."]
  },
  "results_url": null,
  "download_url": null,
  "dl_status": null,
  "dl_download_url": null
}

Get results

GET /variant26/api/v1/jobs/{job_id}/results

Response (200 OK):

{
  "job_id": "1735912345_12345",
  "status": "completed",
  "download_url": "/variant26/temp/1735912345_12345/fabian.data",
  "dl_download_url": "/variant26/temp/1735912345_12345/dl_results.tsv",
  "data": [
    {
      "variant": "chr1:12345A>G.1",
      "tf": "SP1",
      "model": "MA0079.5@...",
      "database": "JASPAR2026_Core",
      "ref_score": "0.45",
      "alt_score": "0.85",
      "ref_pos": "5..15",
      "alt_pos": "5..15",
      "ref_strand": "plus",
      "alt_strand": "plus",
      "effect": "gain",
      "score_diff": "0.40"
    },
    ...
  ]
}

Delete job
- DELETE /variant26/api/v1/jobs/{job_id}
- Terminates any processes still running for the job and removes its working directory. Works on running, completed, and failed jobs. Saved projects cannot be deleted via this endpoint.
- Response (200 OK):
```
{
  "job_id": "1735912345_12345",
  "killed_processes": 2,
  "deleted": true
}
```

Examples

Python

import requests, time
BASE_URL = "https://fabianapp.org/variant26/api/v1"

response = requests.post(f"{BASE_URL}/analyse", json={
    "mode": "single",
    "genome": "hg38",
    "single_variant": "chr1:159204893T>C"
})
job_id = response.json()["job_id"]

while True:
    status = requests.get(f"{BASE_URL}/jobs/{job_id}/status").json()
    if status["status"] in ["completed", "failed"]:
        break
    time.sleep(5)

results = requests.get(f"{BASE_URL}/jobs/{job_id}/results").json()
print(results["download_url"])

Python (VCF)

import requests, base64
with open("sample.vcf", "rb") as f:
    vcf_content = base64.b64encode(f.read()).decode()

response = requests.post("https://fabianapp.org/variant26/api/v1/analyse", json={
    "mode": "vcf",
    "genome": "hg38",
    "vcf_content": vcf_content
})
print(response.json())

Perl

use LWP::UserAgent;
use JSON;
my $ua = LWP::UserAgent->new;
my $base = "https://fabianapp.org/variant26/api/v1";

my $res = $ua->post("$base/analyse",
    Content_Type => 'application/json',
    Content => encode_json({
        mode => "single",
        genome => "hg38",
        single_variant => "chr1:159204893T>C"
    })
);
my $job_id = decode_json($res->content)->{job_id};

while (1) {
    my $status = decode_json($ua->get("$base/jobs/$job_id/status")->content);
    last if $status->{status} =~ /^(completed|failed)$/;
    sleep 5;
}

my $results = decode_json($ua->get("$base/jobs/$job_id/results")->content);
print $results->{download_url};

cURL

curl -X POST https://fabianapp.org/variant26/api/v1/analyse \
  -H "Content-Type: application/json" \
  -d '{"mode": "single", "genome": "hg38", "single_variant": "chr1:159204893T>C"}'

curl https://fabianapp.org/variant26/api/v1/jobs/JOB_ID/status
curl https://fabianapp.org/variant26/api/v1/jobs/JOB_ID/results
curl -X DELETE https://fabianapp.org/variant26/api/v1/jobs/JOB_ID

Contact

If you have questions about the API or need higher rate limits, please email robin.steinhaus (at) bih-charite.de.