version_without_operations.yaml

openapi: 3.0.3
info:
  contact:
    email: help@biothings.io
    name: BioThings Team
    x-id: https://github.com/biothings
    x-role: responsible organization
  description: >-
    Documentation of the BioThings API for [SEMMEDDB](https://pubmed.ncbi.nlm.nih.gov/23044550/) 
    data (download data 
    [here](https://lhncbc.nlm.nih.gov/ii/tools/SemRep_SemMedDB_SKR/SemMedDB_download.html)). 
    This is a newer version where each record is a unique combination of subjectID-predicate-
    objectID and contains a count of the unique pmids and predications supporting it.
  termsOfService: https://biothings.io/about
  title: BioThings SEMMEDDB API
  version: '43'
  x-translator:
    infores: "infores:biothings-semmeddb"
    component: KP
    team:
      - Service Provider
    biolink-version: "4.2.2"
servers:
- description: Production server
  url: https://biothings.ncats.io/semmeddb
  x-maturity: production
- url: https://biothings.test.transltr.io/semmeddb
  description: ITRB Test server
  x-maturity: testing
- url: https://biothings.ci.transltr.io/semmeddb
  description: ITRB CI server
  x-maturity: staging
tags:
## has many biolink-model semantic types, more than the tags here
- name: disease
- name: phenotype
- name: gene
- name: chemical
- name: association
- name: query
- name: translator
- name: biothings
- name: ngd
paths:
  "/association/{id}":
    get:
      description: >-
        By default, this will return the complete association in JSON format. If the input is not valid,
        404 (NOT FOUND) will be returned.
        

        Optionally, you can pass a "fields" parameter to return only the annotation you want 
        (by filtering returned object fields). "fields" accepts any attributes (a.k.a fields) available 
        from the association. Multiple attributes should be separated by commas. If an attribute is not 
        available for a specific association, it will be ignored. Note that the attribute names are 
        case-sensitive.


        Just like the query service, you can also pass a "callback" parameter to make a JSONP call.
      parameters:
      - name: id
        in: path
        required: true
        example: "C0015063-CAUSES-C0544884"
        schema:
          type: string
      - "$ref": "#/components/parameters/fields"
      - "$ref": "#/components/parameters/callback"
      - "$ref": "#/components/parameters/email"
      ## this is useful even when it's not noted in the docs
      - "$ref": "#/components/parameters/size"
      ## these are noted in the /spec endpoint; commenting out for now
      # - "$ref": "#/components/parameters/raw"
      # - "$ref": "#/components/parameters/rawquery"
      # - "$ref": "#/components/parameters/dotfield"
      # - "$ref": "#/components/parameters/_sorted"
      # - "$ref": "#/components/parameters/always_list"
      # - "$ref": "#/components/parameters/allow_null"
      # - "$ref": "#/components/parameters/format"
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      ## commenting out schemas and other status codes for now
      #     content:
      #       application/json:
      #         schema:
      #           $ref: '#/components/schemas/Association'
      #   '404':
      #     description: A response indicating an unknown association ID
      tags:
      - association
  "/association":
    post:
      description: >-
        Although making simple GET requests above to our service is sufficient in most use cases, 
        there are some times you might find it easier to batch query (e.g., retrieving multiple associations). 
        Fortunately, you can also make batch queries via POST requests when you need to.
      parameters:
      - name: ids
        description: >-
          Accepts multiple association ids separated by commas. Note that currently we only take ids up to 
          1000 maximum, the rest will be omitted.


          The request body can also be used to provide these ids.
        in: query
        ## setting to false since putting this info in the request body seems to work as well
        required: false
        schema:
          type: string
      - "$ref": "#/components/parameters/fields"
      - "$ref": "#/components/parameters/email"
      ## this is useful even when it's not noted in the docs
      - "$ref": "#/components/parameters/size"
      ## these are noted in the /spec endpoint; commenting out for now
      # - "$ref": "#/components/parameters/raw"
      # - "$ref": "#/components/parameters/rawquery"
      # - "$ref": "#/components/parameters/dotfield"
      # - "$ref": "#/components/parameters/_sorted"
      # - "$ref": "#/components/parameters/always_list"
      # - "$ref": "#/components/parameters/allow_null"
      # - "$ref": "#/components/parameters/format"
      requestBody:
        content:
          application/json:
            example:
              ids:
              - "C0015063-CAUSES-C0544884"
              - "C0543800-CAUSES-C0392525"
            schema:
              type: object
              properties:
                ids:
                  description: >-
                    Accepts multiple association ids. Note that currently we only take the input ids 
                    up to 1000 maximum, the rest will be omitted.
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      tags:
      - association
  "/metadata":
    get:
      description: Get metadata about the data available from the API
      ## these are noted in the https://mychem.info/v1/spec endpoint; commenting out for now
      # parameters:
      # - "$ref": "#/components/parameters/format"
      # - "$ref": "#/components/parameters/raw"
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      tags:
      - metadata
  "/metadata/fields":
    get:
      description: Get metadata about the data fields available from the API
      ## these are noted in the https://mychem.info/v1/spec endpoint; commenting out for now
      # parameters:
      # - "$ref": "#/components/parameters/format"
      # - "$ref": "#/components/parameters/raw"
      # - "$ref": "#/components/parameters/search"
      # - "$ref": "#/components/parameters/prefix"
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      tags:
      - metadata
  "/query/ngd":
    get:
      parameters:
      - name: umls
        description: Query string.
        in: query
        required: true
        example: 
        - "C0003762,C0262587"
        schema:
          type: array
          items:
            type: string
      ## these are noted in the /spec endpoint; commenting out for now
      # - "$ref": "#/components/parameters/format"
      responses:
        '200':
          description: Success
      tags:
      - ngd
    post:
      parameters:
      - name: umls
        description: Query string.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      ## these are noted in the /spec endpoint; commenting out for now
      # - "$ref": "#/components/parameters/format"
      requestBody:
        content:
          application/json:
            example:
              umls:
              - 
                - C0003762
                - C0262587
            schema:
              type: object
              properties:
                umls:
                  type: array
                  items:
                    type: array
                    items:
                      type: string
      responses:
        '200':
          description: Success
      tags:
      - ngd
  "/query":
    get:
      description: >-
        Query service. In the output, "total" in the output gives the total number 
        of matching hits, while the actual hits are returned under "hits" field.
      parameters:
      - name: q
        description: >-
          Required, passing user query. The detailed query syntax for parameter is explained 
          [here for a core BioThings 
          API](https://docs.mychem.info/en/latest/doc/chem_query_service.html#query-syntax).
        in: query
        required: true
        example: "subject.umls:C0055723"
        schema:
          type: string
      - "$ref": "#/components/parameters/fields"
      - "$ref": "#/components/parameters/size"
      - "$ref": "#/components/parameters/from"
      - "$ref": "#/components/parameters/fetch_all"
      - "$ref": "#/components/parameters/scroll_id"
      - "$ref": "#/components/parameters/sort"
      - "$ref": "#/components/parameters/facets"
      - "$ref": "#/components/parameters/facet_size"
      - "$ref": "#/components/parameters/callback"
      - "$ref": "#/components/parameters/dotfield"
      - "$ref": "#/components/parameters/email"
      ## these are noted in the /spec endpoint; commenting out for now
      # - "$ref": "#/components/parameters/aggs"
      # - "$ref": "#/components/parameters/userquery"
      # - "$ref": "#/components/parameters/explain"
      # - "$ref": "#/components/parameters/raw"
      # - "$ref": "#/components/parameters/rawquery"
      # - "$ref": "#/components/parameters/_sorted"
      # - "$ref": "#/components/parameters/always_list"
      # - "$ref": "#/components/parameters/allow_null"
      # - "$ref": "#/components/parameters/format"
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      ## commenting out schemas and other status codes for now
      #     content:
      #       application/json:
      #         schema:
      #           "$ref": "#/components/schemas/QueryResult"
      #   '400':
      #     content:
      #       application/json:
      #         schema:
      #           "$ref": "#/components/schemas/ErrorResult"
      #     description: A response indicating an improperly formatted query
      # summary: Make queries and return matching gene hits. Supports JSONP and CORS
      #   as well.
      tags:
      - query
    post:
      description: >-
        Although making simple GET requests above to our query service is sufficient for most use cases, 
        there are times you might find it more efficient to make batch queries (e.g., retrieving data 
        for multiple inputs). Fortunately, you can also make batch queries via POST requests when you need to.


        The "query” field in the returned object indicates the matching query term. If a query term has no match, 
        it will return with a “notfound” field with the value “true”.
      parameters:
      - name: q
        description: >-
          Accepts multiple values separated by commas. Note that currently we only take the input values up to 1000 
          maximum, the rest will be omitted.


          The request body can also be used to provide these ids.
        in: query
        ## setting to false since putting this info in the request body seems to work as well
        required: false
        schema:
          type: array
          items:
            type: string
      - name: scopes
        description: >-
          Optional, specify one or more fields (separated by commas) to search. Default: _id


          The request body can also be used to provide this information.
        in: query
        ## setting to false since putting this info in the request body seems to work as well
        required: false
        schema:
          type: string
      - "$ref": "#/components/parameters/fields"
      - "$ref": "#/components/parameters/email"
      ## this is useful even when it's not noted in the docs
      - "$ref": "#/components/parameters/size"
      - "$ref": "#/components/parameters/from"
      - "$ref": "#/components/parameters/fetch_all"
      - "$ref": "#/components/parameters/scroll_id"
      ## these are noted in the https://mychem.info/v1/spec endpoint; commenting out for now
      # - "$ref": "#/components/parameters/sort"
      # - "$ref": "#/components/parameters/raw"
      # - "$ref": "#/components/parameters/rawquery"
      # - "$ref": "#/components/parameters/dotfield"
      # - "$ref": "#/components/parameters/_sorted"
      # - "$ref": "#/components/parameters/always_list"
      # - "$ref": "#/components/parameters/allow_null"
      # - "$ref": "#/components/parameters/format"
      requestBody:
        content:
          application/json:
            example:
              q:
              - "C0055723"
              - "C0085083"
              scopes:
              - "subject.umls"
            schema:
              type: object
              properties:
                q:
                  description: >-
                    Accepts multiple values separated by commas. Note that currently we only take the input values 
                    up to 1000 maximum, the rest will be omitted.
                  type: array
                  items:
                    type: string
                scopes:
                  description: >-
                    Specify one or more fields (separated by commas) to search. Default: _id
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      ## commenting out schemas and other status codes for now
      #     content:
      #       application/json:
      #         schema:
      #           "$ref": "#/components/schemas/QueryPOSTResult"
      #   '400':
      #     content:
      #       application/json:
      #         schema:
      #           "$ref": "#/components/schemas/ErrorResult"
      #     description: A response indicating an improperly formatted query
      # summary: Make batch gene queries and return matching gene hits
      tags:
      - query
      ## list of operations goes here!!! 3 levels of indent
components:
  parameters:
    callback:
      name: callback
      description: >-
        Optional, you can pass a "callback" parameter to make a JSONP call.
      in: query
      required: false
      schema:
        type: string
    dotfield:
      name: dotfield
      description: >-
        Optional, can be used to control the format of the returned object. 
        If "dotfield" is true, the returned data object is returned flattened (no nested objects) 
        using dotfield notation for key names. Default: false.
      in: query
      required: false
      schema:
        type: boolean
        default: false
    email:
      name: email
      description: >-
        Optional, if you are regular users of our services, we encourage you to provide us an email, 
        so that we can better track the usage or follow up with you.
      in: query
      required: false
      schema:
        type: string
    facet_size:
      name: facet_size
      description: >-
        Optional, an integer (1 <= facet_size <= 1000) that specifies how many buckets to return in a 
        [faceted query](https://docs.mychem.info/en/latest/doc/chem_query_service.html?highlight=from#faceted-queries).
      in: query
      required: false
      schema:
        type: integer
        default: 10
    facets:
      name: facets
      description: >-
        Optional, a single field or comma-separated fields to return facets, can only be used on non-free text fields. 
        E.g. “facets=chembl.molecule_properties.full_mwt”. See [examples of faceted queries for a core BioThings 
        API](https://docs.mychem.info/en/latest/doc/chem_query_service.html?highlight=from#faceted-queries).
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    fetch_all:
      name: fetch_all
      description: >-
        Optional, a boolean, which when TRUE, allows fast retrieval of all unsorted query hits. 
        The return object contains a _scroll_id field, which when passed as a parameter to the query endpoint 
        (see the scroll_id parameter), returns the next 1000 query results. Setting fetch_all = TRUE causes 
        the results to be inherently unsorted, therefore the sort parameter is ignored. For more information, 
        see [examples using fetch_all for a core BioThings 
        API](https://docs.mychem.info/en/latest/doc/chem_query_service.html?highlight=from#scrolling-queries). 
        Default: FALSE.
      in: query
      required: false
      schema:
        type: boolean
        default: false
    fields:
      name: fields
      description: >-
        Optional, can be a comma-separated list to limit the fields returned from the object. 
        If "fields=all", all available fields will be returned.
        

        Note that it supports dot notation as well, e.g., you can pass "chebi.name". 
        Default: "fields=all". 
        The parameter "filter" is an alias for this parameter.
      in: query
      required: false
      schema:
        type: string
        default: all
    from:
      name: from
      description: >-
        Optional, the number of matching hits to skip, starting from 0. Default: 0. 
      in: query
      required: false
      schema:
        type: integer
        default: 0
    scroll_id:
      name: scroll_id
      description: >-
        Optional, a string containing the _scroll_id returned from a query request with fetch_all = TRUE. 
        Supplying a valid scroll_id will return the next 1000 unordered results. If the next results are 
        not obtained within 1 minute of the previous set of results, the scroll_id becomes stale, and a 
        new one must be obtained with another query request with fetch_all = TRUE. All other parameters are 
        ignored when the scroll_id parameter is supplied. For more information see [examples using scroll_id 
        for a core BioThings 
        API](https://docs.mychem.info/en/latest/doc/chem_query_service.html?highlight=from#scrolling-queries).
      in: query
      required: false
      schema:
        type: string
    size:
      name: size
      description: >-
        Optional, the maximum number of matching hits to return (with a cap of 1000 at the moment). Default: 10.
        The combination of "size" and "from" parameters can be used to get paging for a large query.
      in: query
      required: false
      schema:
        type: integer
        default: 10
    sort:
      name: sort
      description: >-
        Optional, the comma-separated fields to sort on. Prefix with "-" for descending order, otherwise in ascending order. 
        Default: sort by matching scores in descending order.
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    ## these are noted in the https://mychem.info/v1/spec endpoint; commenting out for now
    # _sorted:
    #   name: _sorted
    #   in: query
    #   required: false
    #   schema:
    #     type: boolean
    #     default: true
    # aggs:
    #   name: aggs
    #   in: query
    #   required: false
    #   schema:
    #     type: array
    #     items:
    #       type: string
    # allow_null:
    #   name: allow_null
    #   in: query
    #   required: false
    #   schema:
    #     type: array
    #     items:
    #       type: string
    # always_list:
    #   name: always_list
    #   in: query
    #   required: false
    #   schema:
    #     type: array
    #     items:
    #       type: string
    # explain:
    #   name: explain
    #   in: query
    #   required: false
    #   schema:
    #     type: boolean
    # format:
    #   name: format
    #   description: 'controls output format of server response, currently supports:
    #     "json", "jsonld", "html". Type: string. Default: json.'
    #   in: query
    #   required: false
    #   schema:
    #     type: string
    #     default: json
    # prefix:
    #   name: prefix
    #   in: query
    #   required: false
    #   schema:
    #     type: string
    # raw:
    #   name: raw
    #   in: query
    #   required: false
    #   schema:
    #     type: boolean
    # rawquery:
    #   name: rawquery
    #   in: query
    #   required: false
    #   schema:
    #     type: boolean
    # search:
    #   name: search
    #   in: query
    #   required: false
    #   schema:
    #     type: string
    # userquery:
    #   name: userquery
    #   in: query
    #   required: false
    #   schema:
    #     type: string
  ## commenting out schemas and other status codes for now
  # schemas:
  #   Association:
  #     properties:
  #       _id:
  #         type: string
  #     required:
  #     - _id
  #     type: object
  #   ErrorResult:
  #     properties:
  #       message:
  #         type: string
  #       success:
  #         type: boolean
  #     type: object
  #   QueryPOSTResult:
  #     items:
  #       allOf:
  #       - $ref: '#/components/schemas/Association'
  #       - properties:
  #           _score:
  #             format: float
  #             type: number
  #           query:
  #             type: string
  #         type: object
  #     type: array
  #   QueryResult:
  #     properties:
  #       hits:
  #         items:
  #           $ref: '#/components/schemas/Association'
  #         type: array
  #       max_score:
  #         format: float
  #         type: number
  #       took:
  #         type: integer
  #       total:
  #         type: integer
  #     type: object
  #   int64_or_array:
  #     oneOf:
  #     - items:
  #         format: int64
  #         type: integer
  #       type: array
  #     - format: int64
  #       type: integer
  #   string_or_array:
  #     oneOf:
  #     - items:
  #         type: string
  #       type: array
  #     - type: string
  x-bte-response-mapping:
    umls-obj:
      UMLS: object.umls              ## no prefix
      ref_pmid: predication.pmid     ## no prefix
      "biolink:supporting_text": predication.sentence
      input_name: subject.name
      output_name: object.name
      ## commenting out because data-processing / biolink-modeling issues
      # publication_count: pmid_count
      # semmeddb_predication_count: predication_count
      # "biolink:original_predicate": predicate
    umls-subj:
      UMLS: subject.umls             ## no prefix
      ref_pmid: predication.pmid     ## no prefix
      "biolink:supporting_text": predication.sentence
      output_name: subject.name
      input_name: object.name
      ## commenting out because data-processing / biolink-modeling issues
      # publication_count: pmid_count
      # semmeddb_predication_count: predication_count
      # "biolink:original_predicate": predicate
    ncbigene-obj:
      NCBIGene: object.ncbigene      ## no prefix
      ref_pmid: predication.pmid     ## no prefix
      "biolink:supporting_text": predication.sentence
      input_name: subject.name
      output_name: object.name
      ## commenting out because data-processing / biolink-modeling issues
      # publication_count: pmid_count
      # semmeddb_predication_count: predication_count
      # "biolink:original_predicate": predicate
    ncbigene-subj:
      NCBIGene: subject.ncbigene     ## no prefix
      ref_pmid: predication.pmid     ## no prefix
      "biolink:supporting_text": predication.sentence
      output_name: subject.name
      input_name: object.name
      ## commenting out because data-processing / biolink-modeling issues
      # publication_count: pmid_count
      # semmeddb_predication_count: predication_count
      # "biolink:original_predicate": predicate
## FUTURE: currently, BTE already strips prefix.... In the future, need to add rmPrefix before wrap
## currently we can't use OR (to map multiple SEMMED semantic types to 1 biolink semantic type)
## joinSafe is only needed if the delimiter isn't a comma
  ## operations go here!!! 1 level of indent