Portal API Guide
The ICGC Portal API can be accessed from the command line using cURL but we suggest using httpie, a cURL replacement that is particularly well-suited to JSON-based REST APIs. The following examples will contain instuctions for using both cURL and httpie.
ICGC API is a set of RESTful endpoints -- programmable interfaces over the Web -- that allows third-party developers to build automation scripts and apps.
Please see the API Endpoint Documentation for detailed information on the API endpoints, representations and how the API responds to different requests.
The following examples are known to work with curl v7.43.0 and httpie v0.9.3.
Controlled Access
Logging in from the Command Line
Logging in to the ICGC Portal API from the command line requires an ICGC.org account.
Request
$ curl -XPOST -i -H 'Content-Type: application/json' 'https://dcc.icgc.org/api/v1/auth/login' -d '{"username":"...","password":"..."}'
$ http 'https://dcc.icgc.org/api/v1/auth/login' username='...' password='...'
Response
{token: YOUR_DCC_PORTAL_TOKEN_HERE}
Downloading Static Files
Request
$ curl -L -o simple_somatic_mutation.open.COAD-US.tsv.gz https://dcc.icgc.org/api/v1/download?fn=/release_16/Projects/COAD-US/simple_somatic_mutation.open.COAD-US.tsv.gz
$ http --follow -o simple_somatic_mutation.open.COAD-US.tsv.gz https://dcc.icgc.org/api/v1/download?fn=/release_16/Projects/COAD-US/simple_somatic_mutation.open.COAD-US.tsv.gz
Response
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 21.8M 100 21.8M 0 0 27.6M 0 --:--:-- --:--:-- --:--:-- 27.5M
Controlled Access
Request
$ curl -L -o simple_somatic_mutation.controlled.COAD-US.tsv.gz 'https://dcc.icgc.org/api/v1/download?fn=/release_16/Projects/COAD-US/simple_somatic_mutation.controlled.COAD-US.tsv.gz' --cookie 'dcc_portal_token=YOUR_DCC_PORTAL_TOKEN_HERE'
$ http --follow -o simple_somatic_mutation.controlled.COAD-US.tsv.gz 'https://dcc.icgc.org/api/v1/download?fn=/release_16/Projects/COAD-US/simple_somatic_mutation.controlled.COAD-US.tsv.gz' 'Cookie:dcc_portal_token=YOUR_DCC_PORTAL_TOKEN_HERE'
Response
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 21.8M 100 21.8M 0 0 27.6M 0 --:--:-- --:--:-- --:--:-- 27.5M
Dynamic Filtered Download
Start a job
Request
$ curl -g 'https://dcc.icgc.org/api/v1/download/submit?filters={"donor":{"primarySite":{"is":["Brain"]}}}&info=[{"key":"ssm","value":"TSV"}]'
$ http 'https://dcc.icgc.org/api/v1/download/submit' 'filters=={"donor":{"primarySite":{"is":["Brain"]}}}' 'info==[{"key":"ssm","value":"TSV"}]'
Response
{"downloadId":"YOUR_DOWNLOAD_ID"}
Downloading
The files can be downloaded using the aforementioned YOUR_DOWNLOAD_ID
.
Request
$ curl -L 'https://dcc.icgc.org/api/v1/download/YOUR_DOWNLOAD_ID' -o my_dl.gz
$ http --follow 'https://dcc.icgc.org/api/v1/download/YOUR_DOWNLOAD_ID' -o my_dl.gz
Response
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 12.3M 0 12.3M 0 0 471k 0 --:--:-- 0:00:26 --:--:-- 3411k
Controlled Access
If the Dynamic Download Job contains controlled access data you must include your dcc_portal_token
with every request.
Request
$ curl -g 'https://dcc.icgc.org/api/v1/download/submit?filters={"donor":{"primarySite":{"is":["Brain"]}}}&info=[{"key":"ssm","value":"TSV"}]' --cookie 'dcc_portal_token=YOUR_DCC_PORTAL_TOKEN_HERE'
$ http 'https://dcc.icgc.org/api/v1/download/submit' 'filters=={"donor":{"primarySite":{"is":["Brain"]}}}' 'info==[{"key":"ssm","value":"TSV"}]' 'Cookie:dcc_portal_token=YOUR_DCC_PORTAL_TOKEN_HERE'
Request
$ curl -L 'https://dcc.icgc.org/api/v1/download/YOUR_DOWNLOAD_ID' --cookie 'dcc_portal_token=YOUR_DCC_PORTAL_TOKEN_HERE' -o my_dl.gz
$ http --follow -o my_dl.gz 'https://dcc.icgc.org/api/v1/download/YOUR_DOWNLOAD_ID' 'Cookie:dcc_portal_token=YOUR_DCC_PORTAL_TOKEN_HERE'
Common Errors
File downloaded successfully but only 133B
Look into the file, you should see a message along the lines of:
Error(code=404, message=Download with id '/release_16/Projects/COAD-US/simple_somatic_mutation.controlled.COAD-US.tsv.gz' not found.)
Solution
Make sure the path to the file is correct and if you are trying to download a controlled access file make sure your dcc_access_token
is valid.