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>" -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"


Related articles

The content by label feature displays related articles automatically, based on labels you choose. To edit options for this feature, select the placeholder below and tap the pencil icon.

Related issues