University of Chicago Gen3 Sheepdog — export API

openapi: 3.0.0
info:
  title: Gen3 Sheepdog OpenAPI Specification — export API
  version: 0.1.0
  description: >-
    Sheepdog is the Gen3 data submission service, authored by the University of Chicago Center for Translational Data Science.
    Code: https://github.com/uc-cdis/sheepdog
  termsOfService: http://cdis.uchicago.edu/terms/
  contact:
    email: cdis@uchicago.edu
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://gen3.datacommons.io/
  description: >-
    University of Chicago Center for Translational Data Science (CTDS) reference Gen3 data
    commons. Gen3 is deployable software authored by CTDS (github.com/uc-cdis), so the upstream
    specification ships a placeholder host; this is the base URL of the deployment CTDS itself
    operates. The datacommons.io domain is registered to CDIS, University of Chicago.
  x-operator: institution
  x-verified: '2026-08-19'
  x-verified-evidence: https://gen3.datacommons.io/.well-known/openid-configuration
tags:
- name: export
paths:
  /v0/submission/<program>/<project>/export:
    get:
      description: 'Return a file with the requested entities as an attachment. Either ``ids`` or ``node_label`` must be provided in the parameters. When both are provided, ``node_label`` is ignored and ``ids`` is used. If ``ids`` is provided, all entities matching given ``ids`` will be exported. If there is only one entity type in the output, it will return a ``{node_type}.tsv`` or ``{node_type}.json`` file, e.g.: ``aliquot.tsv``. If there are multiple entity types, it returns ``gdc_export_{one_time_sha}.tar.gz`` for TSV format, or ``gdc_export_{one_time_sha}.json`` for JSON format. CSV is similar to TSV. If ``node_label`` is provided, it will export all entities of type with name ``node_label`` to a TSV file or JSON file. CSV is not supported yet in this case.'
      parameters:
      - description: The program to which the submitter belongs and in which the entities will be created. The `program` is the human-readable name, e.g. TCGA.
        in: path
        name: program
        required: true
        schema:
          type: string
      - description: The project to which the submitter belongs and in which the entities will be created. The `project` is the human-readable code, e.g. BRCA.
        in: path
        name: project
        required: true
        schema:
          type: string
      - description: one or a list of node IDs seperated by commas.
        in: query
        name: ids
        schema:
          type: string
      - description: type of nodes to look up, for example ``'case'``
        in: query
        name: node_label
        schema:
          type: string
      - description: output format, ``json`` or ``tsv`` or ``csv``; default is ``tsv``
        in: query
        name: format
        schema:
          type: string
      - description: whether to recursively find children or not; default is False
        in: query
        name: with_children
        schema:
          type: string
      - description: 'category of node to filter on children. Example: ``clinical``'
        in: query
        name: category
        schema:
          type: string
      - description: whether to include the ids in the export file; default is False
        in: query
        name: without_id
        schema:
          type: boolean
      responses:
        '200':
          description: Success
        '400':
          description: Bad Request
        '403':
          description: Unauthorized request.
        '404':
          description: No id is found
      summary: Export entities
      tags:
      - export
    post:
      description: 'Return a file with the requested entities as an attachment. Either ``ids`` or ``node_label`` must be provided in the parameters. When both are provided, ``node_label`` is ignored and ``ids`` is used. If ``ids`` is provided, all entities matching given ``ids`` will be exported. If there is only one entity type in the output, it will return a ``{node_type}.tsv`` or ``{node_type}.json`` file, e.g.: ``aliquot.tsv``. If there are multiple entity types, it returns ``gdc_export_{one_time_sha}.tar.gz`` for TSV format, or ``gdc_export_{one_time_sha}.json`` for JSON format. CSV is similar to TSV. If ``node_label`` is provided, it will export all entities of type with name ``node_label`` to a TSV file or JSON file. CSV is not supported yet in this case.'
      parameters:
      - description: The program to which the submitter belongs and in which the entities will be created. The `program` is the human-readable name, e.g. TCGA.
        in: path
        name: program
        required: true
        schema:
          type: string
      - description: The project to which the submitter belongs and in which the entities will be created. The `project` is the human-readable code, e.g. BRCA.
        in: path
        name: project
        required: true
        schema:
          type: string
      - description: one or a list of node IDs seperated by commas.
        in: query
        name: ids
        schema:
          type: string
      - description: type of nodes to look up, for example ``'case'``
        in: query
        name: node_label
        schema:
          type: string
      - description: output format, ``json`` or ``tsv`` or ``csv``; default is ``tsv``
        in: query
        name: format
        schema:
          type: string
      - description: whether to recursively find children or not; default is False
        in: query
        name: with_children
        schema:
          type: string
      - description: 'category of node to filter on children. Example: ``clinical``'
        in: query
        name: category
        schema:
          type: string
      - description: whether to include the ids in the export file; default is False
        in: query
        name: without_id
        schema:
          type: boolean
      responses:
        '200':
          description: Success
        '400':
          description: Bad Request
        '403':
          description: Unauthorized request.
        '404':
          description: No id is found
      summary: Export entities
      tags:
      - export
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            user: generic user access