openapi: 3.2.0
info:
  title: SEER* Rx 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: rx
  description: Antineoplastic drugs database
paths:
  /rest/rx/{version}/update:
    put:
      tags:
      - rx
      summary: Update an Rx entry
      operationId: updateRx
      parameters:
      - name: version
        in: path
        description: Rx version
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Rx'
        required: true
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rx'
        '400':
          description: Invalid input
        '404':
          description: Unknown version
  /rest/rx/{version}/reset/{id}:
    put:
      tags:
      - rx
      summary: Reset an Rx entry
      operationId: resetRx
      parameters:
      - name: version
        in: path
        description: Rx version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Rx identifier
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success
        '400':
          description: Invalid input
        '404':
          description: Unknown version
        '204':
          description: No Content
  /rest/rx/{version}/unhide/{id}:
    post:
      tags:
      - rx
      summary: Unhide an Rx item
      description: Given a DEVELOPMENT Rx item, unhide the associated production Rx item. If there are other unpublished changes in the DEVELOPMENT Rx item, they will not be published.
      operationId: unhideRx
      parameters:
      - name: version
        in: path
        description: Rx version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Rx identifier
        required: true
        schema:
          type: string
      - name: description
        in: query
        required: false
        schema:
          type: string
      responses:
        '201':
          description: Success
        '400':
          description: Invalid input
        '404':
          description: Unknown version
        '204':
          description: No Content
  /rest/rx/{version}/publish:
    post:
      tags:
      - rx
      summary: Publish the specified Rx entities into the associated production database
      description: Publish the specified Rx entities into the associated production database.
      operationId: publishRx
      parameters:
      - name: version
        in: path
        description: Rx 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/rx/{version}/hide/{id}:
    post:
      tags:
      - rx
      summary: Hide an Rx item
      description: Given a DEVELOPMENT Rx item, hide the associated production Rx item. If there are other unpublished changes in the DEVELOPMENT Rx item, they will not be published.
      operationId: hideRx
      parameters:
      - name: version
        in: path
        description: Rx version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Rx identifier
        required: true
        schema:
          type: string
      - name: description
        in: query
        required: false
        schema:
          type: string
      responses:
        '201':
          description: Success
        '400':
          description: Invalid input
        '404':
          description: Unknown version
        '204':
          description: No Content
  /rest/rx/{version}/create:
    post:
      tags:
      - rx
      summary: Save a new Rx entry
      operationId: createRx
      parameters:
      - name: version
        in: path
        description: Rx version
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Rx'
        required: true
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rx'
        '400':
          description: Invalid input
        '404':
          description: Unknown version
  /rest/rx/versions/create:
    post:
      tags:
      - rx
      summary: Creates a new BETA version database
      description: The new database will be created as a copy of the current production version.
      operationId: createBetaVersion
      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/RxVersion'
  /rest/rx/{version}:
    get:
      tags:
      - rx
      summary: Return a list of Rx entries
      operationId: searchRx
      parameters:
      - name: version
        in: path
        description: Rx 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 Rx 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 Rx items with this assigned_to value
        required: false
        schema:
          type: string
      - name: type
        in: query
        description: RX classification
        required: false
        schema:
          type: string
          enum:
          - DRUG
          - REGIMEN
      - name: modified_from
        in: query
        description: Include all Rx 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 Rx 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 Rx 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 Rx 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 Rx items that been published; if 'false', only include Rx items that have never been published.
        required: false
        schema:
          type: boolean
      - name: hidden
        in: query
        description: If 'true', only return Rx 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
      - name: category
        in: query
        description: Limit the search to one or more categories
        required: false
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
      - name: do_not_code
        in: query
        description: If specified, limit results based on the 'do_not_code' value in the drug
        required: false
        schema:
          type: string
          enum:
          - 'YES'
          - 'NO'
          - SEE_REMARKS
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishableSearchResults'
        '400':
          description: Invalid input
  /rest/rx/{version}/status_summary:
    get:
      tags:
      - rx
      summary: Return a list of Rx entries
      operationId: rxStatus
      parameters:
      - name: version
        in: path
        description: Rx version
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishStatus'
        '404':
          description: Unknown version
  /rest/rx/{version}/keywords:
    get:
      tags:
      - rx
      summary: Return a list of keywords contained in the Rx entries
      operationId: getKeywords
      parameters:
      - name: version
        in: path
        description: Rx 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/rx/{version}/id/{id}:
    get:
      tags:
      - rx
      summary: Return an Rx entry
      operationId: getRxById
      parameters:
      - name: version
        in: path
        description: Rx version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Rx 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/Rx'
        '404':
          description: Unknown Rx entry
  /rest/rx/{version}/id/{id}/regimens:
    get:
      tags:
      - rx
      summary: Return a list of regimens containing the passed drug
      operationId: getRegimensForDrug
      parameters:
      - name: version
        in: path
        description: Rx version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Rx identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rx'
        '404':
          description: Unknown Rx entry
  /rest/rx/{version}/changelog:
    get:
      tags:
      - rx
      summary: Return a list of Rx changelog entries
      operationId: getChangelog
      parameters:
      - name: version
        in: path
        description: Rx 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/rx/versions:
    get:
      tags:
      - rx
      summary: Return a list of all versions of the Rx database
      operationId: getRxVersions
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RxVersion'
  /rest/rx/{version}/delete/{id}:
    delete:
      tags:
      - rx
      summary: Delete an Rx entry
      operationId: deleteRx
      parameters:
      - name: version
        in: path
        description: Rx version
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Rx identifier
        required: true
        schema:
          type: string
      - name: description
        in: query
        required: false
        schema:
          type: string
      responses:
        '201':
          description: Success
        '400':
          description: Invalid input
        '404':
          description: Unknown version
        '204':
          description: No Content
  /rest/rx/versions/delete:
    delete:
      tags:
      - rx
      summary: Deletes an existing BETA version and all associated glossary entries
      description: Only BETA databases may be deleted.
      operationId: deleteBetaVersion
      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:
    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'
    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
    Rx:
      type: object
      description: Rx entity
      properties:
        type:
          type: string
          enum:
          - DRUG
          - REGIMEN
        alternate_name:
          type: array
          items:
            type: string
        primary_site:
          type: array
          items:
            type: string
        histology:
          type: string
        remarks:
          type: string
        evs_id:
          type: string
        abbreviation:
          type: array
          items:
            type: string
        category:
          type: array
          items:
            type: string
        subcategory:
          type: array
          items:
            type: string
        nsc_number:
          type: array
          items:
            type: string
        do_not_code:
          type: string
          enum:
          - 'YES'
          - 'NO'
          - SEE_REMARKS
        drugs:
          type: array
          items:
            type: string
        radiation:
          type: string
        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
    PublishableChangelogEntry:
      type: object
      properties:
        oldVersion:
          $ref: '#/components/schemas/PublishableEntity'
        newVersion:
          $ref: '#/components/schemas/PublishableEntity'
        id:
          type: string
        name:
          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'
    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
    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
    RxVersion:
      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
    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
    PublishStatus:
      type: object
      properties:
        version:
          type: string
        count:
          type: integer
          format: int64
        status_summary:
          type: array
          items:
            $ref: '#/components/schemas/SummaryCount'
  securitySchemes:
    apiKeyScheme:
      type: apiKey
      name: X-SEERAPI-Key
      in: header