openapi: 3.2.0
info:
  title: SEER* Disease API
  description: 'SEER API is a RESTful Web service that supports various SEER Program data sets and mapping.


    This service is available to developers who wish to incorporate SEER resources into their own systems. These resources

    include databases and tools developed to enhance registry operations and quality improvement. The SEER API is designed

    for integration into registry computer systems and is not designed to be accessed by end-users.'
  termsOfService: /terms
  version: '1.0'
servers:
- url: https://api.seer.cancer.gov
  description: Generated server url
security:
- apiKeyScheme: []
tags:
- name: disease
  description: Hematopoietic, lymphoid neoplasms and solid tumor diseases
paths:
  /rest/disease/{version}/update:
    put:
      tags:
      - disease
      summary: Update a disease entry
      operationId: updateDisease
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Disease'
        required: true
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disease'
        '400':
          description: Invalid input
        '404':
          description: Unknown version
  /rest/disease/{version}/reset/{id}:
    put:
      tags:
      - disease
      summary: Reset a disease entry
      operationId: resetDisease
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Disease identifier
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success
        '400':
          description: Invalid input
        '404':
          description: Unknown version
        '204':
          description: No Content
  /rest/disease/{version}/unhide/{id}:
    post:
      tags:
      - disease
      summary: Unhide a disease item
      description: Given a DEVELOPMENT disease item, unhide the associated production disease item. If there are other unpublished changes in the DEVELOPMENT disease item, they will not be published.
      operationId: unhideDisease
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Disease identifier
        required: true
        schema:
          type: string
      - name: description
        in: query
        description: Description
        required: false
        schema:
          type: string
      responses:
        '201':
          description: Success
        '400':
          description: Invalid input
        '404':
          description: Unknown version
        '204':
          description: No Content
  /rest/disease/{version}/publish:
    post:
      tags:
      - disease
      summary: Publish the specified disease entities into the associated production database
      operationId: publishDisease
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishInfo'
        required: true
      responses:
        '201':
          description: Success
        '400':
          description: Invalid input
        '404':
          description: Unknown version
        '204':
          description: No Content
  /rest/disease/{version}/hide/{id}:
    post:
      tags:
      - disease
      summary: Hide a disease item
      description: Given a DEVELOPMENT disease item, hide the associated production disease item. If there are other unpublished changes in the DEVELOPMENT disease item, they will not be published.
      operationId: hideDisease
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Disease identifier
        required: true
        schema:
          type: string
      - name: description
        in: query
        description: Description
        required: false
        schema:
          type: string
      responses:
        '201':
          description: Success
        '400':
          description: Invalid input
        '404':
          description: Unknown version
        '204':
          description: No Content
  /rest/disease/{version}/create:
    post:
      tags:
      - disease
      summary: Save a new disease entry
      operationId: createDisease
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Disease'
        required: true
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disease'
        '400':
          description: Invalid input
        '404':
          description: Unknown version
  /rest/disease/versions/create:
    post:
      tags:
      - disease
      summary: Creates a new BETA version database
      description: The new database will be created as a copy of the current production version.
      operationId: createBetaVersion_2
      parameters:
      - name: name
        in: query
        description: The name of the version to be created
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiseaseVersion'
  /rest/disease/reportability:
    post:
      tags:
      - disease
      summary: Returns the reportable year range of the supplied disease
      operationId: getReportability
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Disease'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disease'
        '400':
          description: Invalid input
  /rest/disease/{version}:
    get:
      tags:
      - disease
      summary: Return a list of Disease entries
      description: This API call returns both Hematopoietic and Solid Tumor data. The Solid Tumor data, however, is being provided as a preview only. In order to retrieve data that is ready for use in your systems, please make sure to include the HEMATO type parameter when retrieving disease data. **If you do not provide a parameter, you will be retrieving data for both Hematopoietic and Solid Tumors.**
      operationId: searchDiseases
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      - name: q
        in: query
        description: Search query
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: The status of the disease item. This field only exists on development databases.
        required: false
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
      - name: assigned_to
        in: query
        description: Only include disease items with this assigned_to value
        required: false
        schema:
          type: string
      - name: site_category
        in: query
        description: Limit the search to a site category of diseases. For a list of categories, see disease/site_categories
        required: false
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
      - name: type
        in: query
        description: Disease classification.
        required: false
        schema:
          type: string
          enum:
          - SOLID_TUMOR
          - HEMATO
          - NON_NEOPLASTIC
      - name: modified_from
        in: query
        description: Include all disease items modified on or after the supplied date. Dates have the format of YYYY-MM-DD.
        required: false
        schema:
          type: string
      - name: modified_to
        in: query
        description: Include all disease items modified on or before the supplied date. Dates have the format of YYYY-MM-DD.
        required: false
        schema:
          type: string
      - name: published_from
        in: query
        description: Include all disease items published on or after the supplied date. Dates have the format of YYYY-MM-DD.
        required: false
        schema:
          type: string
      - name: published_to
        in: query
        description: Include all disease items published on or before the supplied date. Dates have the format of YYYY-MM-DD.
        required: false
        schema:
          type: string
      - name: been_published
        in: query
        description: If 'true', only include diseases that been published; if 'false', only include glossary items that have never been published.
        required: false
        schema:
          type: boolean
      - name: hidden
        in: query
        description: If 'true', only return disease items that are hidden
        required: false
        schema:
          type: boolean
      - name: mode
        in: query
        description: Search mode
        required: false
        schema:
          type: string
          default: OR
          enum:
          - AND
          - OR
      - name: count
        in: query
        description: The number of results to return
        required: false
        schema:
          type: integer
          format: int64
          default: 25
      - name: offset
        in: query
        description: Results start at this offset
        required: false
        schema:
          type: integer
          format: int64
          default: 0
      - name: order
        in: query
        description: The sort order of the results
        required: false
        schema:
          type: string
          enum:
          - name
          - -name
          - status
          - -status
          - assigned_to
          - -assigned_to
          - last_modified
          - -last_modified
          - type
          - -type
          - site_category
          - -site_category
          - icdO3_morphology
          - -icdO3_morphology
      - name: output_type
        in: query
        description: Output type
        required: false
        schema:
          type: string
          default: MIN
          enum:
          - MIN
          - PARTIAL
          - FULL
      - name: glossary
        in: query
        description: Return glossary matches
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishableSearchResults'
        '400':
          description: Invalid input
  /rest/disease/{version}/status_summary:
    get:
      tags:
      - disease
      summary: Return a list of disease entries
      operationId: diseaseStatus
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishStatus'
        '404':
          description: Unknown version
  /rest/disease/{version}/same_primary:
    get:
      tags:
      - disease
      summary: Indicate whether 2 morphologies (and diagnosis years) represent the same primary
      operationId: isSame
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      - name: d1
        in: query
        description: A morphology (i.e. 8000/3) representing the first disease
        required: true
        schema:
          type: string
      - name: year1
        in: query
        description: Year of diagnosis for first disease
        required: true
        schema:
          type: string
      - name: d2
        in: query
        description: A morphology (i.e. 8000/3) representing the second disease
        required: true
        schema:
          type: string
      - name: year2
        in: query
        description: Year of diagnosis for second disease
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SamePrimaries'
        '404':
          description: Unknown version
  /rest/disease/{version}/keywords:
    get:
      tags:
      - disease
      summary: Return a list of keywords contained in the disease entries
      operationId: getKeywords_2
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      - name: q
        in: query
        description: Search query
        required: false
        schema:
          type: string
      - name: count
        in: query
        description: The number of results to return
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KeywordInfo'
  /rest/disease/{version}/id/{id}:
    get:
      tags:
      - disease
      summary: Return a single disease
      operationId: getDiseaseById
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Disease identifier
        required: true
        schema:
          type: string
      - name: glossary
        in: query
        description: Return glossary matches
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disease'
        '404':
          description: Unknown disease
  /rest/disease/{version}/id/{id}/{year}:
    get:
      tags:
      - disease
      summary: Return a single disease with only year-based information for the passed year…
      operationId: getDiseaseByIdWithYear
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Disease identifier
        required: true
        schema:
          type: string
      - name: year
        in: path
        description: The year to use for inclusion of year-based fields. Only values that fall in the passed range will be included.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disease'
        '404':
          description: Unknown disease
  /rest/disease/{version}/changelog:
    get:
      tags:
      - disease
      summary: Return a list of Disease changelog entries
      operationId: getChangelog_2
      parameters:
      - name: version
        in: path
        description: Glossary version
        required: true
        schema:
          type: string
      - name: from
        in: query
        description: Include all changelog item entries modified on or after the supplied date. Dates have the format of YYYY-MM-DD.
        required: false
        schema:
          type: string
      - name: to
        in: query
        description: Include all changelog item entries modified on or before the supplied date. Dates have the format of YYYY-MM-DD.
        required: false
        schema:
          type: string
      - name: count
        in: query
        description: The number of changelog entries to return. If not supplied, 10 will be returned at once. This cannot be more than 10.
        required: false
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: The starting offset for the results. This defaults to 0.
        required: false
        schema:
          type: integer
          format: int32
      - name: id
        in: query
        description: Include changelogs containing this entity ID. The changelogs that are returned will only include entries relating to the requested entity.
        required: false
        schema:
          type: string
      - name: order
        in: query
        description: Results are ordered by date in descending order by default
        required: false
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishableChangelogResults'
        '400':
          description: Invalid input
  /rest/disease/versions:
    get:
      tags:
      - disease
      summary: Return a list of all versions of the disease database
      operationId: getDiseaseVersions
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DiseaseVersion'
  /rest/disease/site_categories:
    get:
      tags:
      - disease
      summary: Return the complete list of site categories for use in the search API
      description: Note that site categories are only relevant for solid tumor diseases.
      operationId: getSiteCategories
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SiteCategory'
  /rest/disease/primary_site:
    get:
      tags:
      - disease
      summary: Return the list of ICDO2/ICDO3 primary site codes and labels
      operationId: getPrimarySites
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Lookup'
  /rest/disease/primary_site/{code}:
    get:
      tags:
      - disease
      summary: Return the list of ICDO2/ICDO3 primary sites matching a code
      operationId: getPrimarySites_1
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Lookup'
        '404':
          description: Code not found
  /rest/disease/{version}/delete/{id}:
    delete:
      tags:
      - disease
      summary: Delete a disease entry
      operationId: deleteDisease
      parameters:
      - name: version
        in: path
        description: Disease version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Disease identifier
        required: true
        schema:
          type: string
      - name: description
        in: query
        description: Description
        required: false
        schema:
          type: string
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disease'
        '400':
          description: Invalid input
        '404':
          description: Unknown version
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disease'
  /rest/disease/versions/delete:
    delete:
      tags:
      - disease
      summary: Deletes an existing BETA version and all associated glossary entries
      description: Only BETA databases may be deleted.
      operationId: deleteBetaVersion_2
      parameters:
      - name: name
        in: query
        description: The name of the version to be deleted
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
components:
  schemas:
    YearRange:
      type: object
      properties:
        start:
          type: integer
          format: int32
        end:
          type: integer
          format: int32
    PublishableEntity:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        version:
          type: string
        hidden:
          type: boolean
        status:
          type: string
        assigned_to:
          type: string
        first_published:
          type: string
          format: date-time
        last_modified:
          type: string
          format: date-time
        fingerprint:
          type: string
        note:
          type: string
        field_notes:
          type: object
          additionalProperties:
            type: string
        score:
          type: number
          format: double
        glossary:
          type: array
          items:
            $ref: '#/components/schemas/ApiKeywordMatch'
          uniqueItems: true
    ApiKeywordMatch:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        keyword:
          type: string
        category:
          type: array
          items:
            type: string
            enum:
            - GENERAL
            - SOLID_TUMOR
            - HEMATO
            - NON_NEOPLASTIC
            - SEERRX
            - SEER_TRAINING
            - LYMPH_NODES
            - STAGING
          uniqueItems: true
        start:
          type: integer
          format: int32
        end:
          type: integer
          format: int32
    DiseaseVersion:
      type: object
      properties:
        version:
          type: string
        type:
          type: string
          enum:
          - PRODUCTION
          - DEVELOPMENT
          - BETA
        first_published:
          type: string
          format: date-time
        last_modified:
          type: string
          format: date-time
        count:
          type: integer
          format: int64
    SiteRange:
      type: object
      properties:
        low:
          type: string
        high:
          type: string
    PublishableChangelogEntry:
      type: object
      properties:
        oldVersion:
          $ref: '#/components/schemas/PublishableEntity'
        newVersion:
          $ref: '#/components/schemas/PublishableEntity'
        id:
          type: string
        name:
          type: string
    SiteCategory:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        sites:
          type: array
          items:
            $ref: '#/components/schemas/SiteRange'
    PublishableSearchResults:
      type: object
      properties:
        terms:
          type: array
          items:
            type: string
        total:
          type: integer
          format: int64
        count:
          type: integer
          format: int64
        offset:
          type: integer
          format: int64
        max_score:
          type: number
          format: double
        order:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/PublishableEntity'
    Disease:
      type: object
      description: Disease entity
      properties:
        id:
          type: string
        name:
          type: string
        version:
          type: string
        hidden:
          type: boolean
        status:
          type: string
        assigned_to:
          type: string
        first_published:
          type: string
          format: date-time
        last_modified:
          type: string
          format: date-time
        fingerprint:
          type: string
        note:
          type: string
        field_notes:
          type: object
          additionalProperties:
            type: string
        score:
          type: number
          format: double
        glossary:
          type: array
          items:
            $ref: '#/components/schemas/ApiKeywordMatch'
          uniqueItems: true
        icdO3_morphology:
          type: string
        primary_site:
          type: array
          items:
            $ref: '#/components/schemas/SiteRange'
        primary_site_text:
          type: string
        type:
          type: string
          enum:
          - SOLID_TUMOR
          - HEMATO
          - NON_NEOPLASTIC
        valid:
          $ref: '#/components/schemas/YearRange'
        obsolete_new_code:
          type: array
          items:
            type: string
        reportable:
          type: array
          items:
            $ref: '#/components/schemas/YearRange'
        abstractor_note:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        treatment:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        genetics:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        alternate_name:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        definition:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        icdO2_morphology:
          type: array
          items:
            type: string
        icdO1_morphology:
          type: array
          items:
            type: string
        icd_10cm_code:
          type: array
          items:
            $ref: '#/components/schemas/DateRangeString'
        icd_10_code:
          type: array
          items:
            type: string
        icd_9_code:
          type: array
          items:
            type: string
        signs:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        exams:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        mortality:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        source:
          type: array
          items:
            $ref: '#/components/schemas/DiseaseSource'
        icdO3_effective:
          $ref: '#/components/schemas/YearRange'
        icdO2_effective:
          $ref: '#/components/schemas/YearRange'
        icdO1_effective:
          $ref: '#/components/schemas/YearRange'
        missing_primary_site_message:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        grade:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeInteger'
        transform_to:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        transform_to_text:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        transform_from:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        transform_from_text:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        immunophenotype:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        diagnosis_method:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        module_id:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        same_primary:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        same_primary_text:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        progression:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        diagnostic_confirmation:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        site_category:
          type: string
        biomarkers:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        treatment_text:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        recurrence:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
        metastatic:
          type: array
          items:
            $ref: '#/components/schemas/YearRangeString'
    SummaryCount:
      type: object
      properties:
        type:
          type: string
        status:
          type: string
        count:
          type: integer
          format: int64
    KeywordInfo:
      type: object
      properties:
        keyword:
          type: string
        count:
          type: integer
          format: int32
    DiseaseSource:
      type: object
      properties:
        name:
          type: string
        section:
          type: string
        pages:
          type: string
    YearRangeString:
      type: object
      properties:
        value:
          type: string
        start:
          type: integer
          format: int32
        end:
          type: integer
          format: int32
    DateRangeString:
      type: object
      properties:
        value:
          type: string
        start:
          type: string
        end:
          type: string
    YearRangeInteger:
      type: object
      properties:
        value:
          type: integer
          format: int32
        start:
          type: integer
          format: int32
        end:
          type: integer
          format: int32
    PublishStatus:
      type: object
      properties:
        version:
          type: string
        count:
          type: integer
          format: int64
        status_summary:
          type: array
          items:
            $ref: '#/components/schemas/SummaryCount'
    PublishableChangelog:
      type: object
      properties:
        adds:
          type: array
          items:
            $ref: '#/components/schemas/PublishableChangelogEntry'
        mods:
          type: array
          items:
            $ref: '#/components/schemas/PublishableChangelogEntry'
        deletes:
          type: array
          items:
            $ref: '#/components/schemas/PublishableChangelogEntry'
        user:
          type: string
        date:
          type: string
          format: date-time
        version:
          type: string
        description:
          type: string
    PublishableChangelogResults:
      type: object
      properties:
        total:
          type: integer
          format: int64
        count:
          type: integer
          format: int32
        offset:
          type: integer
          format: int32
        changelogs:
          type: array
          items:
            $ref: '#/components/schemas/PublishableChangelog'
    Lookup:
      type: object
      properties:
        value:
          type: string
        label:
          type: string
    SamePrimaries:
      type: object
      properties:
        disease1:
          type: string
        year1:
          type: integer
          format: int32
        disease2:
          type: string
        year2:
          type: integer
          format: int32
        is_same:
          type: boolean
    PublishInfo:
      type: object
      description: Publish info
      properties:
        version_to:
          type: string
        status:
          type: string
        assigned_to:
          type: string
        ids:
          type: array
          items:
            type: string
        description:
          type: string
  securitySchemes:
    apiKeyScheme:
      type: apiKey
      name: X-SEERAPI-Key
      in: header