openapi: 3.1.0
info:
  title: MedDRA Medical Dictionary for Regulatory Activities Hierarchy Terms API
  description: MedDRA (Medical Dictionary for Regulatory Activities) and the WHO Drug Dictionary provide standardized medical terminology APIs for adverse event coding, drug safety reporting, and pharmacovigilance. APIs enable term lookup, hierarchy navigation, and coding validation for regulatory submissions to ICH, FDA, EMA, and other health authorities.
  version: 27.0.0
  contact:
    name: MedDRA MSSO Support
    url: https://www.meddra.org/contact-msso
  license:
    name: MedDRA License Agreement
    url: https://www.meddra.org/license-subscription
servers:
- url: https://api.meddra.example.com/v1
  description: MedDRA API server (requires subscription)
security:
- APIKey: []
- BearerAuth: []
tags:
- name: Terms
  description: MedDRA term search and retrieval
paths:
  /terms/search:
    get:
      operationId: searchTerms
      summary: Search MedDRA terms
      description: Search for MedDRA terms by text string across any or all levels of the MedDRA hierarchy (SOC, HLGT, HLT, PT, LLT). Returns matching terms with their codes and hierarchy context.
      tags:
      - Terms
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
        description: Search text (partial match supported)
      - name: level
        in: query
        schema:
          type: string
          enum:
          - SOC
          - HLGT
          - HLT
          - PT
          - LLT
          - ALL
          default: ALL
        description: MedDRA hierarchy level to search
      - name: version
        in: query
        schema:
          type: string
        description: MedDRA version (e.g., 27.0); defaults to current
      - name: language
        in: query
        schema:
          type: string
          default: en
        description: Language for term text (en, ja, de, fr, es, zh, etc.)
      - name: currentOnly
        in: query
        schema:
          type: boolean
          default: true
        description: Return only current (non-deprecated) terms
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 500
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TermSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /terms/{termCode}:
    get:
      operationId: getTerm
      summary: Get a term by code
      description: Retrieve a specific MedDRA term by its numeric code, returning the term name, level, current status, and parent/child hierarchy links.
      tags:
      - Terms
      parameters:
      - name: termCode
        in: path
        required: true
        schema:
          type: integer
        description: MedDRA term code (e.g., 10019211 for HLT "Hepatic failures")
      - name: level
        in: query
        required: true
        schema:
          type: string
          enum:
          - SOC
          - HLGT
          - HLT
          - PT
          - LLT
      - name: version
        in: query
        schema:
          type: string
      - name: language
        in: query
        schema:
          type: string
          default: en
      responses:
        '200':
          description: Term details with hierarchy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TermDetail'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Authentication required or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Term not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    MedDRATerm:
      type: object
      description: A MedDRA terminology term
      properties:
        code:
          type: integer
          description: MedDRA numeric term code
        termText:
          type: string
          description: Term name in the requested language
        level:
          type: string
          enum:
          - SOC
          - HLGT
          - HLT
          - PT
          - LLT
        current:
          type: boolean
          description: Whether the term is current (not deprecated)
        primarySOCCode:
          type: integer
          description: Code of the primary System Organ Class
        primarySOCName:
          type: string
        version:
          type: string
    TermDetail:
      allOf:
      - $ref: '#/components/schemas/MedDRATerm'
      - type: object
        properties:
          parents:
            type: array
            items:
              $ref: '#/components/schemas/MedDRATerm'
            description: Parent terms at the next higher level
          children:
            type: array
            items:
              $ref: '#/components/schemas/MedDRATerm'
            description: Child terms at the next lower level
          allSOCLinks:
            type: array
            items:
              type: object
              properties:
                socCode:
                  type: integer
                socName:
                  type: string
                isPrimary:
                  type: boolean
            description: All SOC links (a PT may belong to multiple SOCs)
          predecessors:
            type: array
            description: Previous codes in older MedDRA versions
            items:
              type: object
              properties:
                code:
                  type: integer
                version:
                  type: string
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    TermSearchResponse:
      type: object
      properties:
        terms:
          type: array
          items:
            $ref: '#/components/schemas/MedDRATerm'
        totalCount:
          type: integer
        version:
          type: string
        limit:
          type: integer
        offset:
          type: integer
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
externalDocs:
  description: MedDRA Documentation
  url: https://www.meddra.org/