openapi: 3.1.0
info:
  title: NCI Clinical Search Diseases Trials API
  description: 'RESTful API for searching NCI-supported cancer clinical trials data

    sourced from NCI''s Clinical Trials Reporting Program (CTRP). This is

    the same API that powers NCI''s public Clinical Trials Search at

    cancer.gov. A free API key is required and must be sent in the

    X-API-KEY header; developers register through the CTS Developer

    Accounts portal at https://clinicaltrialsapi.cancer.gov/.


    This is a best-effort, hand-authored specification covering the

    documented v2 endpoints (trials, interventions, diseases, terms).

    Request and response payloads use permissive schemas where the full

    property set is not enumerated in public documentation.

    '
  version: v2
  contact:
    name: NCI Clinical Trials API
    url: https://clinicaltrialsapi.cancer.gov/
servers:
- url: https://clinicaltrialsapi.cancer.gov/api/v2
security:
- apiKey: []
tags:
- name: Trials
paths:
  /trials:
    get:
      tags:
      - Trials
      summary: Search clinical trials (GET form)
      description: 'Search for clinical trials using query-string parameters. Equivalent

        to POST /trials for simple queries.

        '
      parameters:
      - in: query
        name: size
        schema:
          type: integer
          default: 10
      - in: query
        name: from
        schema:
          type: integer
          default: 0
      - in: query
        name: include
        description: Comma-separated fields to include in the response.
        schema:
          type: string
      - in: query
        name: exclude
        schema:
          type: string
      - in: query
        name: current_trial_status
        schema:
          type: string
      - in: query
        name: keyword
        schema:
          type: string
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialSearchResponse'
    post:
      tags:
      - Trials
      summary: Search clinical trials (POST form)
      description: 'Search for clinical trials with a full JSON query body supporting

        keyword, geographic, eligibility, biomarker, and other filters.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrialSearchQuery'
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialSearchResponse'
  /trials/{id}:
    parameters:
    - in: path
      name: id
      required: true
      schema:
        type: string
      description: NCI trial id (e.g. NCI-2014-01632).
    get:
      tags:
      - Trials
      summary: Retrieve a single clinical trial
      responses:
        '200':
          description: Trial document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trial'
        '404':
          description: Trial not found.
components:
  schemas:
    Trial:
      type: object
      description: NCI clinical trial document.
      properties:
        nci_id:
          type: string
        nct_id:
          type: string
        brief_title:
          type: string
        official_title:
          type: string
        brief_summary:
          type: string
        current_trial_status:
          type: string
        phase:
          type: string
        study_protocol_type:
          type: string
        lead_org:
          type: string
        principal_investigator:
          type: string
        sites:
          type: array
          items:
            type: object
            additionalProperties: true
        eligibility:
          type: object
          additionalProperties: true
        diseases:
          type: array
          items:
            type: object
            additionalProperties: true
        interventions:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    TrialSearchQuery:
      type: object
      description: Free-form search query supported by the trials endpoint.
      properties:
        size:
          type: integer
          default: 10
        from:
          type: integer
          default: 0
        include:
          type: array
          items:
            type: string
        exclude:
          type: array
          items:
            type: string
        keyword:
          type: string
        current_trial_status:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        nci_id:
          type: array
          items:
            type: string
        nct_id:
          type: array
          items:
            type: string
        eligibility:
          type: object
          additionalProperties: true
        sites:
          type: object
          additionalProperties: true
      additionalProperties: true
    TrialSearchResponse:
      type: object
      properties:
        total:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/Trial'
      additionalProperties: true
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Free API key issued by the CTS Developer Accounts portal.