openapi: 3.0.3
info:
  title: Castor EDC / CDMS Audit Trail Studies API
  description: 'The Castor EDC / CDMS API is a RESTful interface to Castor''s cloud electronic data capture (EDC) and clinical data management platform. It exposes study configuration and collected data - studies, participants (records), institutes (sites), users, fields and field metadata, study data points, repeating data (reports), surveys and survey packages, the audit trail, and batch data export. Authentication is OAuth2 with the Client Credentials flow: request an access token from POST /oauth/token using an API Client ID and Client Secret generated in Castor User Settings, then send it as a Bearer token. Access tokens are valid for 5 hours. Most identifiers (study, field, report / repeating-data instance, survey package instance) are uppercase GUIDs in 8-4-4-4-12 format; the participant ID is the exception.


    Endpoint status: paths that this document marks with `x-endpoint-status: confirmed` were observed directly in Castor''s published API reference and helpdesk documentation. Paths marked `x-endpoint-status: modeled` reflect the documented resource model and the coverage of the official R and Python wrapper packages, but the exact path or shape was inferred and should be verified against https://data.castoredc.com/api during reconciliation.'
  version: '1.0'
  contact:
    name: Castor
    url: https://www.castoredc.com
  license:
    name: Proprietary
    url: https://www.castoredc.com/legal/
servers:
- url: https://data.castoredc.com/api
  description: Castor EU (default)
- url: https://us.castoredc.com/api
  description: Castor US region
security:
- oauth2ClientCredentials: []
tags:
- name: Studies
  description: Studies accessible to the API client.
paths:
  /oauth/token:
    post:
      operationId: getAccessToken
      tags:
      - Studies
      summary: Obtain an OAuth2 access token
      description: Exchange an API Client ID and Client Secret for a Bearer access token using the client_credentials grant. The returned token is valid for 5 hours.
      security: []
      x-endpoint-status: confirmed
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - client_id
              - client_secret
              - grant_type
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
                grant_type:
                  type: string
                  enum:
                  - client_credentials
      responses:
        '200':
          description: An access token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                    example: Bearer
                  expires_in:
                    type: integer
                    example: 18000
        '401':
          $ref: '#/components/responses/Unauthorized'
  /study:
    get:
      operationId: listStudies
      tags:
      - Studies
      summary: List studies
      description: Lists all studies the authenticated API client has access to.
      x-endpoint-status: confirmed
      parameters:
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of studies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /study/{study_id}:
    get:
      operationId: getStudy
      tags:
      - Studies
      summary: Retrieve a study
      description: Retrieves a single study by its GUID.
      x-endpoint-status: confirmed
      parameters:
      - $ref: '#/components/parameters/StudyId'
      responses:
        '200':
          description: A study.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    Page:
      name: page
      in: query
      required: false
      description: Page number for paginated (HAL) collections.
      schema:
        type: integer
        minimum: 1
    StudyId:
      name: study_id
      in: path
      required: true
      description: The study GUID (uppercase, 8-4-4-4-12 format).
      schema:
        type: string
  schemas:
    Study:
      type: object
      properties:
        study_id:
          type: string
          format: uuid
        name:
          type: string
        created_by:
          type: string
        live:
          type: boolean
        randomization_enabled:
          type: boolean
        surveys_enabled:
          type: boolean
        created_on:
          type: string
          format: date-time
    StudyCollection:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            study:
              type: array
              items:
                $ref: '#/components/schemas/Study'
        page_count:
          type: integer
        total_items:
          type: integer
  responses:
    NotFound:
      description: The requested resource was not found.
    Unauthorized:
      description: Missing or invalid access token.
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://data.castoredc.com/api/oauth/token
          scopes: {}