openapi: 3.1.0
info:
  title: CDISC Library ADaM Biomedical Concepts API
  description: The CDISC Library API is a REST API that delivers CDISC standards metadata to software applications that automate standards-based processes. It uses linked data to provide access to SDTM, ADaM, and other clinical data standards. Responses are available in JSON, XML, ODM, CSV, and Excel formats. Access requires a CDISC Library account and an API key obtained from the CDISC Library API Management (APIM) Developer Portal.
  version: 1.0.0
  contact:
    name: CDISC Library Support
    url: https://jira.cdisc.org/servicedesk/customer/portal/2
  license:
    name: CDISC License
    url: https://www.cdisc.org/cdisc-library
servers:
- url: https://library.cdisc.org/api
  description: CDISC Library Production API
- url: https://library.cdisc.org/api/cosmos/v2
  description: CDISC Biomedical Concepts API v2
security:
- apiKey: []
tags:
- name: Biomedical Concepts
  description: CDISC Biomedical Concepts (COSMOS)
paths:
  /cosmos/v2/bc:
    get:
      operationId: listBiomedicalConcepts
      summary: List CDISC Biomedical Concepts
      description: Returns the CDISC COSMOS Biomedical Concept catalog. Supports pagination and filtering.
      tags:
      - Biomedical Concepts
      parameters:
      - name: packageDate
        in: query
        description: Filter BCs by package release date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: pageSize
        in: query
        schema:
          type: integer
          default: 100
          maximum: 500
      responses:
        '200':
          description: List of Biomedical Concepts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiomedicalConceptList'
  /cosmos/v2/bc/{conceptId}:
    get:
      operationId: getBiomedicalConcept
      summary: Get a specific Biomedical Concept
      description: Returns the full definition of a CDISC COSMOS Biomedical Concept including data elements and value sets.
      tags:
      - Biomedical Concepts
      parameters:
      - name: conceptId
        in: path
        required: true
        description: Biomedical Concept identifier
        schema:
          type: string
          example: C49488
      responses:
        '200':
          description: Biomedical Concept definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiomedicalConcept'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    BiomedicalConceptList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BiomedicalConceptSummary'
        meta:
          type: object
          properties:
            total:
              type: integer
            page:
              type: integer
            pageSize:
              type: integer
    BiomedicalConceptSummary:
      type: object
      properties:
        conceptId:
          type: string
          example: C49488
        name:
          type: string
        definition:
          type: string
    Error:
      type: object
      properties:
        message:
          type: string
        statusCode:
          type: integer
        timestamp:
          type: string
          format: date-time
    BiomedicalConcept:
      type: object
      properties:
        conceptId:
          type: string
        name:
          type: string
        definition:
          type: string
        dataElements:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              dataType:
                type: string
              codeList:
                type: string
  responses:
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: api-key
      description: API key obtained from CDISC Library API Management Developer Portal at https://api.developer.library.cdisc.org/