openapi: 3.0.3
info:
  title: Castor EDC / CDMS Audit Trail Fields 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: Fields
  description: Study fields and their metadata (dependencies, option groups, validations).
paths:
  /study/{study_id}/field:
    get:
      operationId: listFields
      tags:
      - Fields
      summary: List fields
      description: Lists all data-capture fields defined in a study.
      x-endpoint-status: confirmed
      parameters:
      - $ref: '#/components/parameters/StudyId'
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /study/{study_id}/field/{field_id}:
    get:
      operationId: getField
      tags:
      - Fields
      summary: Retrieve a field
      description: Retrieves a single field by ID.
      x-endpoint-status: confirmed
      parameters:
      - $ref: '#/components/parameters/StudyId'
      - $ref: '#/components/parameters/FieldId'
      responses:
        '200':
          description: A field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '404':
          $ref: '#/components/responses/NotFound'
  /study/{study_id}/field-dependency:
    get:
      operationId: listFieldDependencies
      tags:
      - Fields
      summary: List field dependencies
      description: Lists conditional-logic dependencies between fields in a study.
      x-endpoint-status: confirmed
      parameters:
      - $ref: '#/components/parameters/StudyId'
      responses:
        '200':
          description: A list of field dependencies.
          content:
            application/json:
              schema:
                type: object
  /study/{study_id}/field-optiongroup:
    get:
      operationId: listFieldOptionGroups
      tags:
      - Fields
      summary: List field option groups
      description: Lists the option groups (answer choices) used by fields in a study.
      x-endpoint-status: confirmed
      parameters:
      - $ref: '#/components/parameters/StudyId'
      responses:
        '200':
          description: A list of option groups.
          content:
            application/json:
              schema:
                type: object
  /study/{study_id}/field-validation:
    get:
      operationId: listFieldValidations
      tags:
      - Fields
      summary: List field validations
      description: Lists validation rules attached to fields in a study.
      x-endpoint-status: modeled
      parameters:
      - $ref: '#/components/parameters/StudyId'
      responses:
        '200':
          description: A list of field validations.
          content:
            application/json:
              schema:
                type: object
components:
  parameters:
    Page:
      name: page
      in: query
      required: false
      description: Page number for paginated (HAL) collections.
      schema:
        type: integer
        minimum: 1
    FieldId:
      name: field_id
      in: path
      required: true
      description: The field GUID.
      schema:
        type: string
    StudyId:
      name: study_id
      in: path
      required: true
      description: The study GUID (uppercase, 8-4-4-4-12 format).
      schema:
        type: string
  schemas:
    Field:
      type: object
      properties:
        id:
          type: string
          format: uuid
        field_id:
          type: string
          format: uuid
        field_variable_name:
          type: string
        field_label:
          type: string
        field_type:
          type: string
        field_required:
          type: boolean
        option_group:
          type: string
    FieldCollection:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            fields:
              type: array
              items:
                $ref: '#/components/schemas/Field'
        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: {}