openapi: 3.0.0
info:
  description: |
    Example ClinSpark Report Invocation API Doc (Transfer Data Report).  This is a basic representation of a standard Transfer Data Report and its options.  Adapting the use of parameters appropriately will allow invocation of other reports supported by an instance.  Bearer (token) Authentication is only supported in ClinSpark version 23.3 and greater.

    Successfully invocation the API with this embedded Swagger tooling will provide client bindings and command line invocation patterns that can be used for integrations.
  version: "1.0.0"
  title: ClinSpark Report Invocation API
servers:
  - url: 'https://{customerId}.clinspark.com/api/v1'
    variables:
      customerId:
        default: community-dev
        description: Customer ID assigned by the service provider
  - url: 'https://{ngrokPrefix}.ngrok.io/clinspark/api/v1'
    variables:
      ngrokPrefix:
        default: 04f5b951df6d
        description: first part of ngrok-assigned id
paths:
  /invokeReport:
    get:
      summary: Invoke a the Transfer Data Report
      operationId: get-transferReport
      parameters:
        - name: studyId
          in: query
          description: Status values that need to be considered for filter.  
          required: false
          schema:
            type: integer
        - name: studyName
          in: query
          description: Name of the Study, as seen in the Study > Configure component.  Capitalization and spelling must match exactly. Only include EITHER studyId OR studyName, not both.
          required: false
          example: ABC-PK-12
          schema:
            type: string
        - name: reportName
          in: query
          description: Name of the report, as seen in the Study > Report component.
          required: false
          example: Transfer Data
          schema:
            type: string
        - name: transferReportType
          in: query
          description: Type of transfer report.
          required: false
          example: clinicalCSV
          schema:
            type: string
            enum:
              - clinicalXpt
              - clinicalCSV
              - clinicalExcel
              - odmXml
              - sdtmMappingSpecs
        - name: itemDataTyped
          in: query
          description: Used for the ODM XML report.  
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: includeMetaData
          in: query
          description: Used for the ODM XML report.  
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: includeNonCrfMetaData
          in: query
          description: Include Non-CRF? 
          required: false
          schema:
            type: string
            enum:
              - 'false'
              - 'true'
        - name: xptVersion
          in: query
          description: XPT Version
          example: 'v5'
          schema:
            type: string
            enum:
              - 'v5'
              - 'v8'
        - name: onlyRandomized
          in: query
          description: Only Randomized Subjects?  Has no effect when choosing specific subjects.
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: subjectsIds
          in: query
          description: Optionally defined the ID of specific subjects to include.  Allows for narrowing output to specified subjects.
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: false
          examples:
            oneId:
              summary: Example of a single ID
              value: [5]   # ?subjectsIds=5
            multipleIds:
              summary: Example of multiple IDs
              value: [1, 5, 7]   # ?subjectsIds=1,5,7
      security:
        - basicAuth: []
        - bearerAuth: []
      responses:
        '200':
          description: Successful operation.
          content:  # Response body
            application/zip:
             schema: 
               type: string
               format: binary
        '400':
          description: Invalid status value.
        '401':
          description: Unauthorized. You must add Authentication headers. Check user account for API role action, study restrictions, and any role action and/or roles specified against the report to execute. 
        '422':
          description: Invalid request.  There are input validation errors.  Look at the response for details.
components:
  securitySchemes:
    basicAuth:     # <-- arbitrary name for the security scheme
      type: http
      scheme: basic
    bearerAuth:
        type: http
        scheme: bearer