The GDC Application Programming Interface (API): An Overview The GDC API drives the GDC Data and Submission Portals and provides programmatic access to GDC functionality. This includes searching for, downloading, and submitting data and metadata. The GDC API uses JSON as its communication format, and standard HTTP methods like GET , PUT , POST and DELETE . This guide explains how to construct and execute API requests and interpret API responses. Tools for communicating with the GDC API Many third-party tools can be used for communicating with the GDC API and for preparing and visualizing API calls. Examples of tools for communicating with the GDC API: Examples of tools that can help build GDC API calls: NOTE: When using the command line tool curl be sure to use the bash shell only for compatibility reasons. All examples using curl are using the bash shell. The authentication token should be kept in a secure location, as it allows access to all data accessible by the associated user account. Communicating with the GDC API involves making calls to API endpoints. Each GDC API endpoint represents specific API functionality, as summarized in the following table: The HTTP URL that corresponds to the latest version of a GDC API endpoint is https://api.gdc.cancer.gov/<endpoint> , where <endpoint> is the name of the endpoint. The HTTP URL of an endpoint corresponding to a specific major version of the GDC API is https://api.gdc.cancer.gov/<version>/<endpoint> , where <endpoint> is the name of the endpoint and <version> is the GDC API version. For example, the address of the latest version of the status endpoint is https://api.gdc.cancer.gov/status , whereas the address of the status endpoint corresponding to version 0 of GDC API is https://api.gdc.cancer.gov/v0/status .

All objects ( entities ) in the GDC are assigned a unique identifier in the form of a version 4 universally unique identifier (UUID) . The UUID uniquely identifies the entity in the GDC, and is stored in the entity's id property. UUIDs are frequently used in GDC API requests and responses to identify specific entities like files, cases, and samples. See GDC Data Model for details. The following is an example of a request to the files endpoint, which retrieves information about a MAF file stored in the GDC. Download Script Authentication is required for downloading controlled-access data, and for all data submission functionality. The GDC API uses tokens for authentication. Users can obtain authentication tokens from the GDC Data Portal and the GDC Data Submission Portal . See the GDC Data Submission Portal User's Guide for instructions. Using Authentication Tokens All API requests that require authentication must include a token as an X-Auth-Token custom HTTP header. In the following example, an authentication token is saved as an environment variable and passed to curl to download a controlled-access file: Download Python Script For more information about authentication tokens, including token expiration and rotation, see Data Security . NOTE: The authentication token should be kept in a secure location, as it allows access to all data accessible by the associated user account.