...

Access to any NBIA Search with Authentication REST API requires an authentication token. The an access token.  If you want to access restricted collections, the TCIA Help Desk must give your user account permission to access restricted collectionsthem. 

The full API for data consists of a base URL followed by the API and query parameters, in that order. The base URL to access NBIA Search with Authentication REST APIs is Advanced REST API data is https://services.cancerimagingarchive.net/nbia-api/services/v2/. 

<Token><BaseURL><Resource><QueryEndpoint><YOUR_ACCESS_TOKEN><BaseURL><Resource><QueryEndpoint>?<QueryParameters>

For example, the API call below requests all modality values for the TCGA-BRCA collection. 

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValues?Collection=TCGA-BRCA"

Note: To accommodate special characters, use double quotes on Windows and single quotes on Mac and Linux.

We can break this down as follows.

See See Image Download APIs and Image Metadata APIs for more information about each NBIA Search with Authentication REST API.

...

Access to any NBIA Search with Authentication API requires a token that you must request.

...

 This token can then be used on subsequent requests to authorize access to resources. This token will expire in two hours but you can refresh it.

The NBIA REST API supports secure access to private data in the Client Credentials authorization flow with Spring Security and OAuth2. The Client Credentials authorization flow is also known as "signed fetch" or 2-legged OAuth. The following figure illustrates the typical use case for REST API calls made on the web using 2-legged OAuth. For more information regarding the specific workflow, consult the OAuth2 Specification. 

...

Figure 1: Client Credentials Flow

This flow includes the following steps:

1. The client authenticates with the authorization server and requests an access token from the token endpoint.
2. The authorization server authenticates the client, and if valid, issues an access token.

This token can then be used on subsequent requests to authorize access to resources. The REST API server also supports token expiration and extension by refresh. The time it takes tokens to expire is currently two hours but is configurable.

To access TCIA using an NBIA Search with Authentication REST API, you must do the following:

• Request a token
• Use the token in an API call

Requesting a Token

Access to any NBIA Search with Authentication REST API  requires an authentication token. 

A request for a token takes the following structure. Note that USERNAME should be your TCIA username and PASSWORD should be your TCIA password.

Requesting a Token

Access to any NBIA Advanced REST API requires an access token. A request for an access token takes the following structure. Note that USER should be your TCIA username and PASSWORD should be your TCIA password.

Note: To accommodate special characters, use double quotes on Windows and single quotes on Mac and Linux.

curl -v -d "username=USER

curl -d "username=USERNAME&password=PASSWORD&client_id=NBIA&grant_type=password" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/token

Request a token by interacting with the application in the following way.

1. The application requests credentials. The credentials you pass are different depending on if you want to access public or restricted data (see above).

2. The application sends a request to the service using the credentials you provided as a query string for the body. 

   • grant_type=password
   • username
   • password

3. The service responds with access token details and expiration information.

   • access_token
   • expires_in
   • token_type

   The application makes a request for resources using the returned access token. All APIs listed for accessing public data also support secure access to restricted data with an additional parameter for the access token. 

If you don't have a TCIA account, you can access public data using the "nbia_guest" account with no password, as follows.

curl -v -d "username=nbia_guest&password=&client_id=NBIA&grant_type=password" -k https://services.cancerimagingarchive.net/nbia-api/oauth/token

How a Token How a Token is Returned/Granted/Given

A successful token request returns a standard access token in JSON format. The value after "access_token" will be longer than this example.

{"access_token":"f7889076cd2b2895-b3e485d0-476849c5-9419bd75-3cd973adda76804f162da942","tokenexpires_typein":"bearer"7200,"refresh_expires_in":7200,"refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":7199}

...

eyJhbGciOiJIUzI1NiIsInR5cCIgO","not-before-policy":0,"session_state":"92a199c6-84ed-48aa-a0d2-059bbb99bc90","scope":"openid profile email"}

Make a note of the access token you received and pass it with the REST service call.

# Request for modality values and counts        
    
curl -H "Authorization:Bearer c428d42ccd2b2895-9eed85d0-4f5d49c5-8007bd75-416d46be9b52804f162da942" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValuesAndCounts?Collection=LIDC-IDRI"

A successful service request returns the value in a defined format. 

Refreshing the Token

The time it takes tokens to expire is configurable but is currently two hoursYou can refresh your access token for an additional two hours by passing the refresh token from your original token request.

# Request for refreshing the token  

$ curl -X -v -d "refresh_token=7c2414a1-1f2f-4c9e-82a0-69fcb9fd18ed& "client_id=nbiaRestAPIClient&client_secret=ItsBetweenUAndMe&nbia&grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN" -X POST -k https://servicesnbia.cancerimagingarchive.net/nbia-api/oauth/token
        
/nbia-api/oauth/token"

In the following result, 119 is 7200 is the seconds before the token expires.

{"access_token":"bbe4aa2c-7235-41ad-9770-31619d3dbd15YOUR_ACCESS_TOKEN","tokenexpires_typein":"bearer"7200,"refresh_expires_in":7200,"refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007aYOUR_REFRESH_TOKEN","expirestoken_in":119}type":"Bearer","id_token":"YOUR_ID_TOKEN","not-before-policy":0,"session_state":"531425b6-425d-44f8-bc74-41200d6803c0","scope":"openid profile email"}

Logging Out

The following is an example request to log out. Logging out invalidates the token you previously requested.

# Request for logout
   
curl -X     
$ curl -H-v -d "Authorization:Bearer caa278aa-e7a9-45b8-a7ec-2c83d4b03cc0YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/logout"

If successful, the request returns the following text.

 You Have Logged Out successfully.

...

Testing an API with Public Data

If you don't have a TCIA account and want to test an API, you can access public data using the NBIA guest account with no password, as follows.

...

...

The request does not return any values.

Accessing the National Lung Screening Trial (NLST) collection

Due to its size, the National Lung Screening Trial (NLST) collection lives on a separate NBIA server. Since this server only holds the public NLST collection, there is no reason to create an API token with your own credentials. To access these data via the Advanced REST API, you must change the URL to obtain the authentication token from https://nlst.cancerimagingarchive.net/nbia-api/oauth/token. You can then use https://nlst.cancerimagingarchive.net/nbia-api/

...

services/ to make REST API calls. In both cases, the beginning of the URL is changed from "services" to "nlst."  Examples of requesting a token and performing an API query are shown below:

curl -X -v -d "username=nbia_guest&password=&client_id=NBIA&grant_type=password" -X POST -k https://nlst

Return Values

This section lists and explains the return values of the APIs included in both tables above.

.cancerimagingarchive.net/nbia-api/

getCollectionValues

oauth/token

curl -H "Authorization:Bearer 

YOUR_ACCESS_TOKEN" -k "https://

nlst.cancerimagingarchive.net/nbia-api/services/

getBodyPartValuesAndCounts?Modality=PT"

Return Values

This section lists and explains the return values of the APIs included in both tables above.

getContentsByName

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getContentsByName?name=TCIA_TCGA-PRAD_08-09-2016-v3getBodyPartValues"

getCollectionValues

curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getCollectionValues"

getContentsByName

curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getContentsByName?name=TCIA_TCGA-PRAD_08-09-2016-v3"

getImage

The license file, which includes the data usage agreement, is included in the returned ZIP file.

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getImage?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992"

getImage

The license file, which includes the data usage agreement, is included in the returned ZIP file.

getImageWithMD5Hash

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getImageWithMD5HashgetImage?SeriesInstanceUID=1.3.6.1.4.1.145199590.5100.2.1.69192.4624.313514201353787659031503464798374115997511889073021386151921807063992"

getImageWithMD5Hash

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getManufacturerValues"getImageWithMD5Hash?SeriesInstanceUID=1.3.6.1.4.1.14519.5.2.1.6919.4624.313514201353787659031503464798"

getManufacturerValues

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValuesgetManufacturerValues"

getModalityValues

curl -H "Authorization:Bearer YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValues"

getNewPatientsInCollection

curl -H "Authorization:Bearer YOUR_ACCESS_TOKENcd2b2895-85d0-49c5-bd75-804f162da942" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/NewPatientsInCollection?Collection=CBIS-DDSM&Date=2010/08/16"

getNewStudiesInPatientCollection 

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/NewStudiesInPatientCollection?Collection=CBIS-DDSM&Date=2010/08/16"

getPatient

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getPatient"

getPatientByCollectionAndModality

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getPatientByCollectionAndModality?Collection=VICTRE&Modality=MG"

getPatientStudy

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getPatientStudy"

getSeries

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getSeries

getSeriesMetaData

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getSeriesMetaData?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992"2.374115997511889073021386151921807063992"

getSeriesSize

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getSeriesSize?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992"

getSingleImage

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getSingleImage?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992&SOPInstanceUID:1.3.6.1.4.1.9590.100.1.2.289923739312470966435676008311959891294"

getSOPInstanceUIDs

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getSOPInstanceUIDs?SeriesInstanceUID=1.3.6.1.4.1.9590.100.1.2.374115997511889073021386151921807063992"

getUpdatedSeries

curl -H "Authorization:Bearer cd2b2895-85d0-49c5-bd75-804f162da942YOUR_ACCESS_TOKEN" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getUpdatedSeries?fromDate=01/01/2020"