API Reference¶

The REST APIs provide programmatic ways to submit new jobs and to download data from Michigan Imputation Server. It identifies users using authentication tokens, responses are provided in JSON format.

Authentication¶

Michigan Imputation Server uses a token-based authentication. The token is required for all future interaction with the server. The token can be created and downloaded from your user profile (username -> Profile):

Activate API

For security reasons, Api Tokens are valid for 30 days. You can check the status in the web interface.

Job Submission for Whole Genome Imputation¶

The API allows to submit imputation jobs and to set several parameters. For HLA imputation, please see below.

POST /jobs/submit/imputationserver2¶

The following parameters can be set:

Parameter	Values	Default Value	Required
files	/path/to/file		x
mode	`qconly` `phasing` `imputation`	`imputation`
password	user-defined password	auto generated and send by mail
refpanel	`hrc-r1.1` `1000g-phase-3-v5` `gasp-v2` `genome-asia-panel` `1000g-phase-1` `cappa` `hapmap-2`	-	x
phasing	`eagle` `no_phasing`	`eagle`
population	`eur` `afr` `asn` `amr` `sas` `eas` `AA` `mixed` `all`	-	x
build	`hg19` `hg38`	`hg19`
r2Filter	`0` `0.001` `0.1` `0.2` `0.3`	`0`

Job Submission for HLA Imputation¶

The API also allows to submit imputation jobs using the HLA application. Please note, that the population parameter can be skipped here.

POST /jobs/submit/imputationserver-hla¶

The following parameters can be set:

Parameter	Values	Default Value	Required
files	/path/to/file		x
mode	`qconly` `phasing` `imputation`	`imputation`
password	user-defined password	auto generated and send by mail
refpanel	`multiethnic-hla-panel-Ggroup` `multiethnic-hla-panel-4digit`	-	x
phasing	`eagle` `no_phasing`	`eagle`
build	`hg19` `hg38`	`hg19`
r2Filter	`0` `0.001` `0.1` `0.2` `0.3`	`0`

Examples: curl¶

Submit a single file¶

To submit a job please change /path-to/file.vcf.gz to a valid vcf file and update TOKEN with your API Token:

Command:

TOKEN="YOUR-API-TOKEN";

curl https://imputationserver.sph.umich.edu/api/v2/jobs/submit/imputationserver2 \
  -H "X-Auth-Token: $TOKEN" \
  -F "files=@/path-to/file.vcf.gz" \
  -F "refpanel=1000g-phase-3-v5" \
  -F "population=eur"

Response:

{
  "id":"job-20160504-161420",
  "message":"Your job was successfully added to the job queue.",
  "success":true
}

Submit multiple files¶

Submits multiple vcf files and impute against 1000 Genomes Phase 3 reference panel.

Command:

TOKEN="YOUR-API-TOKEN";

curl https://imputationserver.sph.umich.edu/api/v2/jobs/submit/imputationserver2 \
  -H "X-Auth-Token: $TOKEN" \
  -F "files=@/path-to/file1.vcf.gz" \
  -F "files=@/path-to/file2.vcf.gz" \
  -F "refpanel=1000g-phase-3-v5" \
  -F "population=eur"

Response:

{
  "id":"job-20120504-155023",
  "message":"Your job was successfully added to the job queue.",
  "success":true
}

Submit file from a HTTP(S)¶

Submits files from https with HRC reference panel and quality control.

Command:

TOKEN="YOUR-API-TOKEN";

curl  https://imputationserver.sph.umich.edu/api/v2/jobs/submit/imputationserver2 \
  -H "X-Auth-Token: $TOKEN" \
  -F "files=https://imputationserver.sph.umich.edu/static/downloads/hapmap300.chr1.recode.vcf.gz" \
  -F "files-source=http" \
  -F "refpanel=hrc-r1.1" \
  -F "population=eur" \
  -F "mode=qconly"

Response:

{
  "id":"job-20120504-155023",
  "message":"Your job was successfully added to the job queue.",
  "success":true
}

Examples: Python¶

Submit single vcf file¶

import requests
import json

# imputation server url
url = 'https://imputationserver.sph.umich.edu/api/v2'
token = 'YOUR-API-TOKEN';

# add token to header (see Authentication)
headers = {'X-Auth-Token' : token }
data = {
  'refpanel': '1000g-phase-3-v5',
  'population': 'eur'
}

# submit new job
vcf = '/path/to/genome.vcf.gz';
files = {'files' : open(vcf, 'rb')}
r = requests.post(url + "/jobs/submit/imputationserver2", files=files, data=data, headers=headers)
if r.status_code != 200:
  print(r.json()['message'])
  raise Exception('POST /jobs/submit/imputationserver2 {}'.format(r.status_code))

# print response and job id
print(r.json()['message'])
print(r.json()['id'])

Submit multiple vcf files¶

import requests
import json

# imputation server url
url = 'https://imputationserver.sph.umich.edu/api/v2'
token = 'YOUR-API-TOKEN';

# add token to header (see Authentication)
headers = {'X-Auth-Token' : token }
data = {
  'refpanel': '1000g-phase-3-v5',
  'population': 'eur'
}

# submit new job
vcf = '/path/to/file1.vcf.gz';
vcf1 = '/path/to/file2.vcf.gz';
files = [('files', open(vcf, 'rb')), ('files', open(vcf1, 'rb'))]
r = requests.post(url + "/jobs/submit/imputationserver2", files=files, data=data, headers=headers)
if r.status_code != 200:
  print(r.json()['message'])
  raise Exception('POST /jobs/submit/imputationserver2 {}'.format(r.status_code))

# print message
print(r.json()['message'])
print(r.json()['id'])

List all jobs¶

All running jobs can be returned as JSON objects at once.

GET /jobs¶

Examples: curl¶

Command:

TOKEN="YOUR-API-TOKEN";

curl -H "X-Auth-Token: $TOKEN" https://imputationserver.sph.umich.edu/api/v2/jobs

Response:

[
  {
    "applicationId":"minimac",
    "executionTime":0,
    "id":"job-20160504-155023",
    "name":"job-20160504-155023",
    "positionInQueue":0,
    "running":false,
    "state":5
  },{
    "applicationId":"minimac",
    "executionTime":0,
    "id":"job-20160420-145809",
    "name":"job-20160420-145809",
    "positionInQueue":0,
    "running":false,
    "state":5
  },{
    "applicationId":"minimac",
    "executionTime":0,
    "id":"job-20160420-145756",
    "name":"job-20160420-145756",
    "positionInQueue":0,
    "running":false,
    "state":5
  }
]

Example: Python¶

import requests
import json

# imputation server url
url = 'https://imputationserver.sph.umich.edu/api/v2'
token = 'YOUR-API-TOKEN';

# add token to header (see authentication)
headers = {'X-Auth-Token' : token }

# get all jobs
r = requests.get(url + "/jobs", headers=headers)
if r.status_code != 200:
    raise Exception('GET /jobs/ {}'.format(r.status_code))

# print all jobs
for job in r.json():
    print('{} [{}]'.format(job['id'], job['state']))

Monitor Job Status¶

/jobs/{id}/status¶

Example: curl¶

Command:

TOKEN="YOUR-API-TOKEN";

curl -H "X-Auth-Token: $TOKEN" https://imputationserver.sph.umich.edu/api/v2/jobs/job-20160504-155023/status

Response:

{
  "application":"Michigan Imputation Server (Minimac4) 1.5.8",
  "applicationId":"minimac4",
  "deletedOn":-1,
  "endTime":1462369824173,
  "executionTime":0,
  "id":"job-20160504-155023",
  "logs":"",
  "name":"job-20160504-155023",
  "outputParams":[],
  "positionInQueue":0,
  "running":false,
  "startTime":1462369824173,
  "state":5
  ,"steps":[]
}

Monitor Job Details¶

/jobs/{id}¶

Example: curl¶

TOKEN="YOUR-API-TOKEN";

curl -H "X-Auth-Token: $TOKEN" https://imputationserver.sph.umich.edu/api/v2/jobs/job-20160504-155023/