openapi: 3.1.0
info:
  title: Medidata Rave EDC REST API
  description: >-
    Medidata Rave provides electronic data capture (EDC) APIs for clinical trial
    data collection and management. APIs enable access to study designs, case report
    forms, patient data, queries, and audit trails for clinical research organizations
    and pharmaceutical companies.
  version: 1.0.0
  contact:
    name: Medidata Support
    url: https://www.medidata.com/support
  license:
    name: Proprietary
    url: https://www.medidata.com/terms
externalDocs:
  description: Medidata Developer Documentation
  url: https://www.medidata.com/
servers:
  - url: https://{tenant}.medidata.com/RaveWebServices/studies
    variables:
      tenant:
        default: medidatatrials
        description: Your Medidata Rave instance subdomain
  - url: https://developer.medidata.com/api/v2
    description: Medidata Developer API v2
security:
  - BasicAuth: []
  - OAuth2: []
paths:
  /:
    get:
      operationId: listStudies
      summary: List studies
      description: >-
        Return a list of clinical studies accessible with the provided
        credentials. Each study entry includes the study name, OID, and
        environment (Production, UAT, etc.).
      tags:
        - Studies
      parameters:
        - name: include
          in: query
          schema:
            type: string
          description: Include additional metadata (e.g., include=subjectCount)
      responses:
        '200':
          description: List of studies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /{studyOID}/Subjects:
    get:
      operationId: listSubjects
      summary: List subjects in a study
      description: >-
        Retrieve all subjects enrolled in the specified study. Returns subject
        key, site ID, status, and enrollment date.
      tags:
        - Subjects
      parameters:
        - name: studyOID
          in: path
          required: true
          schema:
            type: string
          description: Study OID (e.g., Mediflex(Dev))
        - name: Status
          in: query
          schema:
            type: string
            enum: [Active, Inactive, Screened, Failed]
        - name: SiteID
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Subject list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubjectListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createSubject
      summary: Create or update a subject
      description: >-
        Enroll a new subject or update an existing subject's demographic
        data. Subject key must be provided if updating.
      tags:
        - Subjects
      parameters:
        - name: studyOID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubjectCreateRequest'
      responses:
        '200':
          description: Subject created or updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subject'
        '400':
          $ref: '#/components/responses/BadRequest'
  /{studyOID}/Subjects/{subjectKey}:
    get:
      operationId: getSubject
      summary: Get subject details
      description: Retrieve full details of a single subject including all CRF data, events, and queries.
      tags:
        - Subjects
      parameters:
        - name: studyOID
          in: path
          required: true
          schema:
            type: string
        - name: subjectKey
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Subject details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subject'
        '404':
          $ref: '#/components/responses/NotFound'
  /{studyOID}/Subjects/{subjectKey}/ClinicalData:
    get:
      operationId: getSubjectClinicalData
      summary: Get clinical data (CRF data) for a subject
      description: >-
        Retrieve all clinical data (case report form field values) for a subject
        across all visit events and CRF pages.
      tags:
        - Clinical Data
      parameters:
        - name: studyOID
          in: path
          required: true
          schema:
            type: string
        - name: subjectKey
          in: path
          required: true
          schema:
            type: string
        - name: formOID
          in: query
          schema:
            type: string
          description: Filter to a specific form OID
        - name: EventRepeatKey
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Subject clinical data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClinicalDataResponse'
    post:
      operationId: submitClinicalData
      summary: Submit clinical data for a subject
      description: >-
        Submit or update CRF field values for a subject. Supports ODM-compliant
        clinical data XML or JSON submission.
      tags:
        - Clinical Data
      parameters:
        - name: studyOID
          in: path
          required: true
          schema:
            type: string
        - name: subjectKey
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClinicalDataSubmission'
      responses:
        '200':
          description: Data submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionResponse'
  /{studyOID}/Queries:
    get:
      operationId: listQueries
      summary: List data queries
      description: >-
        Retrieve open and closed data queries (discrepancies) for the study.
        Queries are created by data managers or automatically by edit checks.
      tags:
        - Queries
      parameters:
        - name: studyOID
          in: path
          required: true
          schema:
            type: string
        - name: Status
          in: query
          schema:
            type: string
            enum: [Open, Answered, Closed, Cancelled]
        - name: SiteID
          in: query
          schema:
            type: string
        - name: SubjectKey
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Query list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryListResponse'
  /{studyOID}/AuditRecords:
    get:
      operationId: getAuditRecords
      summary: Get audit trail records
      description: >-
        Retrieve audit trail records for data changes in the study. Provides
        a 21 CFR Part 11 / GCP-compliant audit history.
      tags:
        - Audit
      parameters:
        - name: studyOID
          in: path
          required: true
          schema:
            type: string
        - name: SubjectKey
          in: query
          schema:
            type: string
        - name: SiteID
          in: query
          schema:
            type: string
        - name: StartDate
          in: query
          schema:
            type: string
            format: date-time
        - name: EndDate
          in: query
          schema:
            type: string
            format: date-time
        - name: PageSize
          in: query
          schema:
            type: integer
            default: 100
            maximum: 1000
      responses:
        '200':
          description: Audit records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditRecordListResponse'
  /{studyOID}/Sites:
    get:
      operationId: listSites
      summary: List study sites
      description: Retrieve all sites (investigator sites) enrolled in the study.
      tags:
        - Sites
      parameters:
        - name: studyOID
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Site list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteListResponse'
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: Medidata Rave username and password
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://identity.medidata.com/connect/token
          scopes:
            rave.read: Read access to Rave study data
            rave.write: Write access to Rave study data
  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Study:
      type: object
      properties:
        studyOID:
          type: string
          description: Study Object Identifier
        studyName:
          type: string
        protocolName:
          type: string
        environment:
          type: string
          enum: [Production, UAT, Validation, Training]
        status:
          type: string
          enum: [Designing, Testing, Active, Locked, Archived]
        createdDate:
          type: string
          format: date-time
        modifiedDate:
          type: string
          format: date-time
    StudyListResponse:
      type: object
      properties:
        studies:
          type: array
          items:
            $ref: '#/components/schemas/Study'
        totalCount:
          type: integer
    Subject:
      type: object
      properties:
        subjectKey:
          type: string
          description: Unique subject identifier within the study
        siteID:
          type: string
        siteName:
          type: string
        status:
          type: string
          enum: [Active, Inactive, Screened, Failed, Randomized, Completed, Withdrawn]
        enrollmentDate:
          type: string
          format: date
        screeningDate:
          type: string
          format: date
        initials:
          type: string
        studyOID:
          type: string
    SubjectCreateRequest:
      type: object
      required:
        - siteID
      properties:
        subjectKey:
          type: string
          description: Provide to update existing subject; omit to auto-assign
        siteID:
          type: string
        status:
          type: string
        screeningDate:
          type: string
          format: date
        initials:
          type: string
    SubjectListResponse:
      type: object
      properties:
        subjects:
          type: array
          items:
            $ref: '#/components/schemas/Subject'
        totalCount:
          type: integer
    CRFField:
      type: object
      properties:
        fieldOID:
          type: string
        value:
          type: string
        status:
          type: string
          enum: [NotStarted, Saved, Incomplete, Complete, Verified, Signed, Frozen, Locked]
        dataEntryDateTime:
          type: string
          format: date-time
        enteredBy:
          type: string
    CRFForm:
      type: object
      properties:
        formOID:
          type: string
        formName:
          type: string
        fields:
          type: array
          items:
            $ref: '#/components/schemas/CRFField'
    ClinicalDataEvent:
      type: object
      properties:
        eventOID:
          type: string
        eventName:
          type: string
        eventDate:
          type: string
          format: date
        repeatKey:
          type: string
        forms:
          type: array
          items:
            $ref: '#/components/schemas/CRFForm'
    ClinicalDataResponse:
      type: object
      properties:
        subjectKey:
          type: string
        studyOID:
          type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/ClinicalDataEvent'
    ClinicalDataSubmission:
      type: object
      required:
        - events
      properties:
        events:
          type: array
          items:
            type: object
            required:
              - eventOID
              - forms
            properties:
              eventOID: {type: string}
              eventDate: {type: string, format: date}
              repeatKey: {type: string}
              forms:
                type: array
                items:
                  type: object
                  required:
                    - formOID
                    - fields
                  properties:
                    formOID: {type: string}
                    fields:
                      type: array
                      items:
                        type: object
                        required:
                          - fieldOID
                          - value
                        properties:
                          fieldOID: {type: string}
                          value: {type: string}
    SubmissionResponse:
      type: object
      properties:
        status:
          type: string
          enum: [Success, Partial, Failed]
        message:
          type: string
        subjectKey:
          type: string
        warnings:
          type: array
          items:
            type: string
    Query:
      type: object
      properties:
        queryID:
          type: integer
        subjectKey:
          type: string
        siteID:
          type: string
        formOID:
          type: string
        fieldOID:
          type: string
        status:
          type: string
          enum: [Open, Answered, Closed, Cancelled]
        message:
          type: string
        createdBy:
          type: string
        createdDate:
          type: string
          format: date-time
        closedDate:
          type: string
          format: date-time
    QueryListResponse:
      type: object
      properties:
        queries:
          type: array
          items:
            $ref: '#/components/schemas/Query'
        totalCount:
          type: integer
    AuditRecord:
      type: object
      properties:
        auditID:
          type: integer
        subjectKey:
          type: string
        siteID:
          type: string
        formOID:
          type: string
        fieldOID:
          type: string
        oldValue:
          type: string
        newValue:
          type: string
        auditType:
          type: string
        userID:
          type: string
        auditDateTime:
          type: string
          format: date-time
        reason:
          type: string
    AuditRecordListResponse:
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/AuditRecord'
        totalCount:
          type: integer
    Site:
      type: object
      properties:
        siteID:
          type: string
        siteName:
          type: string
        investigator:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        status:
          type: string
          enum: [Active, Inactive, Closed]
    SiteListResponse:
      type: object
      properties:
        sites:
          type: array
          items:
            $ref: '#/components/schemas/Site'
    ErrorResponse:
      type: object
      properties:
        ErrorCode:
          type: integer
        ErrorDescription:
          type: string
tags:
  - name: Audit
    description: Audit trail access for 21 CFR Part 11 compliance
  - name: Clinical Data
    description: CRF data entry and retrieval
  - name: Queries
    description: Data query management
  - name: Sites
    description: Investigator site management
  - name: Studies
    description: Clinical study management
  - name: Subjects
    description: Trial subject enrollment and management