overlay: 1.0.0
info:
  title: API Evangelist enhancements for ClinicalTrials.gov studies-api
  version: 1.0.0
extends: openapi/clinical-trials-gov-studies-api-openapi.yml
x-provenance:
  generated: '2026-09-06'
  method: generated
  source: >-
    API Evangelist enrichment pass. Every value applied here was read from a live probe of
    https://clinicaltrials.gov/api/v2 or from the provider's own documentation on
    2026-09-06 — nothing is asserted that was not observed. The underlying OpenAPI is not
    mutated.
actions:
- target: $.info
  update:
    x-apievangelist-slug: clinical-trials-gov
    x-api-lifecycle: production
    x-api-version-live: 2.0.5
    x-data-refresh-cadence: daily
    x-authentication: none
    x-license: U.S. Government public domain (see https://clinicaltrials.gov/about-site/terms-conditions)
    x-agent-readiness:
      write_surface: false
      idempotency: na
      reversibility: na
      rate_limit_headers: none
- target: $.info.contact
  update:
    name: NLM Support
    url: https://support.nlm.nih.gov/
- target: $
  update:
    x-conventions: conventions/clinical-trials-gov-conventions.yml
    x-error-catalog: errors/clinical-trials-gov-problem-types.yml
    x-lifecycle: lifecycle/clinical-trials-gov-lifecycle.yml
    x-authentication-profile: authentication/clinical-trials-gov-authentication.yml
    x-rate-limits: rate-limits/clinical-trials-gov-rate-limits.yml
    x-data-model: data-model/clinical-trials-gov-data-model.yml
    x-conformance: conformance/clinical-trials-gov-conformance.yml
- target: $.paths['/studies/{nctId}'].get
  update:
    x-response-formats:
    - json
    - csv
    - fhir.json
    x-fhir:
      profile: http://hl7.org/fhir/uv/ebm/StructureDefinition/study-registry-record
      media_type: application/fhir+json
      docs: https://clinicaltrials.gov/data-api/fhir
      status: pilot
      evidence: 'GET /api/v2/studies/NCT00141635?format=fhir.json -> 200 application/fhir+json (probed 2026-09-06)'
    x-alias-redirect: 'since API 2.0.2, resolves NCTIdAlias values to the current record'
- target: $.paths['/studies'].get
  update:
    x-query-language: Essie expression syntax
    x-query-docs: https://clinicaltrials.gov/find-studies/constructing-complex-search-queries
    x-pagination:
      style: opaque-cursor
      request: [pageSize, pageToken, countTotal]
      response: [nextPageToken, totalCount]
    x-undocumented-parameters:
    - name: aggFilters
      note: >-
        Documented only in the 2026-01-22 release note (the 'ressub' Results Submitted
        filter); absent from the description document.
- target: $.paths['/studies/metadata'].get
  update:
    x-role: >-
      Authoritative machine-readable field dictionary for the whole study record; the real
      data model lives here rather than in components.schemas.