How-To Use CanRisk Web-Services

These are the web-services:

  1. auth-token; retrieve an authentication token (for use with the other web-services).

  2. boadicea; calculates risks and mutation carrier probabilities for breast cancer.

  3. ovarian; calculates risks and mutation carrier probabilities for ovarian cancer.

  4. vcf2prs; takes a VCF file and returns a PRS (alpha and z-score) for use in the breast and ovarian cancer web-services.

The following describes auth-token and boadicea.

All requests to the web-services are made over HTTPS. An authentication token can be requested using the ‘auth-token’ web-service and added to the request authorization headers. Data is sent to and from the web-service in JSON format.

Patient identifiable data is not needed to run the risk calculations and the client software should remove this to de-identify the data before submitting the request to the web-service.

The web-service supports the pedigree data submitted in the CanRisk file format and BOADICEA pedigree data format v4 (see the BOADICEA documentation Appendix). It can be sent either as a ‘pedigree_data’ field in the JSON request or posted as a file. See the example usage below.


The following examples use the curl command to send requests to each of the web-services.

  1. Obtaining Authentication Token (replace URL with the CanRisk website address):

    curl -k 'https://{URL}/auth-token/' \
    -d '{"username": "XYZ", "password": "ABC"}' \
    -H "Content-Type: application/json"

  2. Running a breast cancer risk calculation with pedigree data as a JSON parameter (replace with the authentication token):

    CanRisk v1 format
    curl -k -XPOST -H "Content-Type: application/json"  -d '{"mut_freq":"UK","cancer_rates":"UK","user_id":"end_user_id","pedigree_data":"##CanRisk 1.0\n##menarche=12\n##oc_use=N\n##mht_use=N\n##BMI=23.01\n##alcohol=44.8\n##height=180.34\n##FamID\tName\tTarget\tIndivID\tFathID\tMothID\tSex\tMZtwin\tDead\tAge\tYob\tBC1\tBC2\tOC\tPRO\tPAN\tAshkn\tBRCA1\tBRCA2\tPALB2\tATM\tCHEK2\tRAD51D\tRAD51C\tBRIP1\tER:PR:HER2:CK14:CK56\nXXXX\tpa\t0\tm21\t0\t0\tM\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0:0:0:0\nXXXX\tma\t0\tf21\t0\t0\tF\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0:0:0:0\nXXXX\tme\t1\tch1\tm21\tf21\tF\t0\t0\t42\t1977\t38\t0\t0\t0\t0\t0\tS:N\tS:N\tS:N\tS:N\t0:0\t0:0\t0:0\t0:0\t0:0:0:0:0\n"}' https://{URL}/boadicea/ -H "Authorization: Token <TOKEN>"

    or with a pedigree file POSTed as a form
    curl -k -XPOST -F "mut_freq=UK" -F "cancer_rates=UK" -F "user_id=end_user_id" -F "pedigree_data=@/home/xxxx/d10.canrisk" https://{URL}/boadicea/ -H "Authorization: Token <TOKEN>" -H "Accept: application/json"

    BOADICEA format
    curl -k -XPOST -H "Content-Type: application/json" \
    -H 'Authorization: Token <TOKEN>' -H "Accept: application/json" \
    -d '{"mut_freq": "UK", "cancer_rates":"UK", "user_id": "end_user_id",
    pedigree_data":"BOADICEA import pedigree file format 4.0\nFamID\tName\tTarget\tIndivID\tFathID\tMothID\tSex\tMZtwin\tDead\tAge\tYob\t1stBrCa\t2ndBrCa\tOvCa\tProCa\tPanCa\tAshkn\tBRCA1t\tBRCA1r\tBRCA2t\tBRCA2r\tPALB2t\tPALB2r\tATMt\tATMr\tCHEK2t\tCHEK2r\tER\tPR\tHER2\tCK14\tCK56\nXXX1 \tF1 \t1\t1 \t3 \t2 \tF\t0\t0\t23 \t1993\t21 \t0 \t0 \t0 \t0 \t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\nXXX1 \tF2 \t0\t2 \t0 \t0 \tF\t0\t0\t55 \t1961\t0 \t0 \t0 \t0 \t0 \t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\nXXX1 \tM2 \t0\t3 \t0 \t0 \tM\t0\t0\t53 \t1963\t0 \t0 \t0 \t0 \t0 \t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0"}' https://{URL}/boadicea/

  3. Running a ovarian cancer risk calculation with a pedigree file POSTed as a form:
    curl -k -XPOST -F "mut_freq=UK" -F "cancer_rates=UK" \
    -F "user_id=end_user_id" \
    -F "pedigree_data=@/home/xxx/bwa4_pedigree_data.txt" \
    https://{URL}/ovarian/ -H 'Authorization: Token <TOKEN>' -H "Accept: application/json"

  4. Obtaining a PRS for breast cancer:
    curl -k -XPOST -F "bc_prs_reference_file=BCAC_313_PRS.prs" -F "sample_name=SampleA" \
    -F "vcf_file=@/home/xxx/sample_BCAC_313.vcf" \
    https://{URL}/vcf2prs/ \
    -H 'Authorization: Token <TOKEN>' -H "Accept: application/json"