openapi: 3.0.3
info:
  title: NCI Genomic Data Commons (GDC) API
  description: >-
    The GDC API provides programmatic access to cancer genomic and clinical
    data hosted by the National Cancer Institute Genomic Data Commons. The API
    supports search and retrieval of projects, cases, files, and annotations,
    along with file download, BAM slicing, and data submission workflows.
  version: "1.0.0"
  contact:
    name: NCI Genomic Data Commons
    url: https://gdc.cancer.gov/developers/gdc-application-programming-interface-api
servers:
  - url: https://api.gdc.cancer.gov
    description: GDC API latest
  - url: https://api.gdc.cancer.gov/v0
    description: GDC API v0
tags:
  - name: Status
  - name: Search
  - name: Download
  - name: Submission
paths:
  /status:
    get:
      tags: [Status]
      summary: Get API status
      description: Returns API status and version information.
      operationId: getStatus
      responses:
        '200':
          description: API status response
  /projects:
    get:
      tags: [Search]
      summary: Search projects
      description: Search and retrieve metadata about projects available in the GDC.
      operationId: searchProjects
      parameters:
        - name: filters
          in: query
          schema: { type: string }
        - name: fields
          in: query
          schema: { type: string }
        - name: size
          in: query
          schema: { type: integer }
        - name: from
          in: query
          schema: { type: integer }
        - name: sort
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Project search results
  /projects/{project_id}:
    get:
      tags: [Search]
      summary: Get project by ID
      operationId: getProject
      parameters:
        - name: project_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Project details
  /cases:
    get:
      tags: [Search]
      summary: Search cases
      description: Search cases (donors) and their associated files.
      operationId: searchCases
      parameters:
        - name: filters
          in: query
          schema: { type: string }
        - name: fields
          in: query
          schema: { type: string }
        - name: size
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: Case search results
  /cases/{case_id}:
    get:
      tags: [Search]
      summary: Get case by ID
      operationId: getCase
      parameters:
        - name: case_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Case details
  /files:
    get:
      tags: [Search]
      summary: Search files
      description: Search for files in the GDC by characteristics.
      operationId: searchFiles
      parameters:
        - name: filters
          in: query
          schema: { type: string }
        - name: fields
          in: query
          schema: { type: string }
        - name: size
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: File search results
  /files/{file_id}:
    get:
      tags: [Search]
      summary: Get file metadata by ID
      operationId: getFile
      parameters:
        - name: file_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: File metadata
  /annotations:
    get:
      tags: [Search]
      summary: Search annotations
      description: Retrieve curation annotations attached to GDC entities.
      operationId: searchAnnotations
      parameters:
        - name: filters
          in: query
          schema: { type: string }
        - name: fields
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Annotation search results
  /data/{file_id}:
    get:
      tags: [Download]
      summary: Download a file
      description: Download an open-access file by ID. Controlled data requires a token.
      operationId: downloadFile
      parameters:
        - name: file_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: File data
        '401':
          description: Authentication required for controlled data
  /manifest:
    get:
      tags: [Download]
      summary: Generate manifest
      description: Generate a manifest for use with the GDC Data Transfer Tool.
      operationId: getManifest
      parameters:
        - name: filters
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Manifest
  /slicing/view/{file_id}:
    get:
      tags: [Download]
      summary: BAM slicing
      description: Retrieve a slice of a BAM file by genomic region.
      operationId: sliceBam
      parameters:
        - name: file_id
          in: path
          required: true
          schema: { type: string }
        - name: region
          in: query
          schema: { type: string }
      responses:
        '200':
          description: BAM slice
        '401':
          description: Authentication required
  /submission/{program}/{project}:
    get:
      tags: [Submission]
      summary: Get submission program/project resources
      operationId: getSubmissionProject
      parameters:
        - name: program
          in: path
          required: true
          schema: { type: string }
        - name: project
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Submission resource
        '401':
          description: Authentication required
components:
  securitySchemes:
    GdcAuthToken:
      type: apiKey
      in: header
      name: X-Auth-Token
security:
  - GdcAuthToken: []