openapi: 3.2.0
info:
  title: Peregrine OpenAPI Specification GraphQL API
  version: 0.1.0
  description: GraphQL search microservice for CDIS Gen 3 data commons. Code is available on GitHub.
  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: Graph QL
  description: GraphQL Queries
paths:
  /graphql:
    post:
      tags:
      - Graph QL
      summary: Perform a GraphQL Query
      description: Perform a graphql query over the data commons given a query, variables, and name.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryOutputRef'
        '400':
          description: Invalid input
        '403':
          description: Invalid authorization token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryInputInfo'
        description: The GraphQL query and parameters
        required: true
      operationId: postGraphql
      x-operation-id-source: derived
  /getschema:
    get:
      tags:
      - Graph QL
      summary: Returns the data dictionary schema json
      description: The data dictionary for the data commons is internally converted from yaml files to json. This endpoint returns the json schema for the dictionary for use in generating queries.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaOutputRef'
      operationId: getGetschema
      x-operation-id-source: derived
components:
  schemas:
    QueryInputInfo:
      type: object
      properties:
        query:
          type: string
          description: the text of the GraphQL query
        variables:
          type: string
          description: variables for the GraphQL query
        operationName:
          type: string
          description: the name of the operation
      example:
        query: '{ project {project_id} }'
        operationName: null
        variables: null
    QueryOutputRef:
      type: object
      properties:
        data:
          type: object
          description: the results of the GraphQL query
    SchemaOutputRef:
      type: object
      properties:
        data:
          type: object
          description: the json schema for the data dictionary