Skip to main content

%iKnow.REST.v1

deprecated class %iKnow.REST.v1 extends %iKnow.REST.Base, %iKnow.REST.Utils

Please note this version of the REST API is deprecated. See %iKnow.REST.v1dot1 for a newer version.

This class offers endpoints for accessing iKnow functionalities over REST.

The API is fully documented using the OpenAPI SpecificationOpens in a new tab (also known as SwaggerOpens in a new tab). The description in YAML is available from the "/swagger" endpoint and can be loaded directly into swagger-uiOpens in a new tab for convenient GUI capabilities on top of this API.

swagger: '2.0'
info:
  version: "1.0.0"
  title: iKnow REST APIs
  description: |
    This is the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) 
    of the iKnow REST APIs, giving you RESTful access to iKnow domain contents in your system
    Use [swagger-ui](https://github.com/swagger-api/swagger-ui/blob/master/README.md)
    or a similar tool to conveniently browse and test these APIs.
    For more information on iKnow, visit [intersystems.com](http://www.intersystems.com)
  contact:
    name: InterSystems
    url: http://wrc.intersystems.com
    email: support@intersystems.com
  license:
    name: Copyright InterSystems Corporation, all rights reserved.
    url: http://docs.intersystems.com/latest/csp/docbook/copyright.pdf
consumes:
  - application/json
produces:
  - application/json
parameters:
  domainParam:
    name: domain
    type: integer
    in: path
    description: the ID of the domain to query
    required: true
  sourceParam:
    name: source
    type: integer
    in: path
    description: the source ID to query for
    required: true
  tableParam:
    name: table
    type: string
    in: path
    description: the table containing iFind index
    required: true
definitions:
  PageNumber:
    type: integer
    description: |
      which "page" of the results to retrieve
    default: 1
  PageSize:
    type: integer
    description: |
      how many results to retrieve per "page"
    default: {{{PAGESIZE}}}
  FilterMode:
    description: filter mode to use for optionally recalculating certain metrics. Defaults to recalculating all and re-sorting the results (15).
    type: integer
    default: 15
    example: 15
    enum: [1, 3, 5, 7, 11, 13, 15]
  IncludeCount:
    description: whether or not to include a count of all results (ignoring page and pageSize)
    type: boolean
    default: 0
    format: integer
  CountOnly:
    description: whether or not to retrieve just the count and no result list
    type: boolean
    default: 0
    format: integer
  Blacklists:
    description: array of blacklist IDs or names to use for limiting query results, OR a valid SELECT clause retrieving entity values outright
    type: array
    default: []
    items:
      type: string
    
  Filter:
    # TODO: move into proper hierarchy once swagger-ui supports it
    description: filter object restricting the sources to be considered in this query
    type: object
    example: 
      { "operator": "OR", 
        "filters": [ { "ids": [ 123 ] }, 
                     {"field": "Year", "operator": ">", "value": 2016 } ] }
    properties:
      ids:
        description: for use with source-ID-based filters
        type: array
        items:
          type: integer
      extIds:
        description: for use with external-ID-based filters
        type: array
        items:
          type: string
      operator:
        description: for use with group filters ("AND"|"OR") or metadata-based filters (any other value)
        type: string
        enum: ["AND", "OR", "=", "!=", "<", ">", ">=", "<=", "BETWEEN", "IS NULL", "IS NOT NULL"]
      field:
        description: for use with metadata-based filters
        type: string
      value:
        description: for use with metadata-based filters
        type: string
      negate:
        description: for use with group filters
        type: boolean
        default: false
      filters:
        description: for use with group filters
        type: array
        items:
          $ref: '#/definitions/Filter'
      className:
        description: use for filters not covered by other shorthands
        type: string
        example: '%iKnow.Filters.ContainsEntityFilter'
      arguments:
        description: for use with 'className' property, any arguments to be passed to the filter's %New() method (except domain ID)
        type: array
        items:
          type: string
  
  HighlightingRule:
    description: |
      "style" property is mandatory, then pick one selector per rule
    type: object
    required: ["style"]
    properties:
      style:
        type: string
        description: |
          style specification for this highlighting rule: either a two-character 
          sequence or a HTML tag to use for wrapping the to-be-highlighted element.
          Use one selector per highlighting rule.
      entities:
        type: array
        items:
          type: string
        description: <i>selector</i> - selects list of entities
      role:
        type: string
        enum: ["concept", "relation", "pathRelevant", "nonRelevant" ]
        description: <i>selector</i> - selects all entities with this role
      attribute:
        type: string
        enum: ["negation", "positiveSentiment", "negativeSentiment" ]
        description: <i>selector</i> - selects all entities affected by this attribute
      attributeWords:
        type: string
        enum: ["negation", "positiveSentiment", "negativeSentiment" ]
        description: <i>selector</i> - selects all marker terms indicating this attribute
      anyMatch:
        type: boolean
        description: <i>selector</i> - selects any dictionary match
      dictionaries:
        type: array
        description: <i>selector</i> - selects any dictionary match of the specified dictionary IDs
        items:
          type: integer
      dictionaryItems:
        type: array
        description: <i>selector</i> - selects any dictionary match of the specified dictionary item IDs
        items:
          type: integer
      matchType:
        type: string
        enum: ["full", "partial"]
        description: |
          refines the "anyMatch", "dictionaries" or "dictionaryItems" selectors to the designated match type
  Highlighting:
    description: array of highlighting rules
    example:
      [ { "style": "[]", "role": "concept" },
        { "style": "<b>", "entities": [ "airplane", "pilot" ] } ]
    type: array
    items:
      $ref: '#/definitions/HighlightingRule'
  DomainList:
    type: object
    required: ["domains"]
    properties:
      domains:
        type: array
        items:
          title: Domain
          type: object
          required: ["id", "name" ]
          properties:
            id:
              type: integer
            name:
              type: string
            definitionClass:
              type: string
            sourceCount:
              type: integer
            version:
              type: integer
  
  DomainDetails:
    type: object
    required: ["id", "name"]
    properties:
      id:
        type: integer
      name: 
        type: string
      parameters:
        type: object
      metadata:
        type: array
        items:
          type: object
          required: ["id", "name", "operators", "dataType", "storage"]
          properties:
            id:
              type: integer
            name:
              type: string
            operators:
              type: array
              items:
                $ref: '#/definitions/MetadataOperator'
            dataType:
              type: string
              enum: ["string", "number", "date"]
            storage:
              type: string
              
  MetadataOperator:
    type: string
    enum: [ "=", "!=", "<", ">", ">=", "<=", "BETWEEN", "IS NULL", "IS NOT NULL" ]
  
  ConfigurationList:
    type: object
    required: ["configurations"]
    properties:
      configurations:
        type: array
        items:
          title: Configuration
          type: object
          required: ["id", "name", "languages"]
          properties:
            id:
              type: integer
            name:
              type: string
            languages:
              type: array
              items:
                $ref: '#/definitions/LanguageCode'
            userDictionary:
                $ref: '#/definitions/UserDictionary'
            maxConceptLength:
              type: integer
  
  UserDictionary:
    type: object
    required: ["entries"]
    properties:
      name:
        type: string
      entries:
        type: array
        items:
          title: UserDictionaryEntry
          type: object
          required: ["string"]
          properties:
            string:
              type: string
            rewrite:
              type: string
            label:
              type: string
  LanguageCode:
    description: 2-letter ISO language code
    type: string
    enum: [ "en", "fr", "de", "es", "pt", "nl", "ru", "uk", "se", "ja" ]
  SourceList:
    description: list of sources
    type: object
    required: ["sources"]
    properties:
      sources:
        type: array
        items:
          title: Source
          type: object
          required:
            - id
            - extId
          properties:
            id:
              type: integer
              description: source ID
            extId:
              type: string
              description: external ID
            metadata:
              type: object
              description: map of metadata field values
            snippet:
              type: string
              description: snippet (summary) of the retrieved source
      count:
        description: number of result sources (ignoring page and pageSize)
        type: integer
  
  EntityList:
    description: list of entities
    type: object
    properties:
      entities:
        type: array
        items:
          $ref: '#/definitions/Entity'
      count:
        type: integer
        description: number of result entities (ignoring page and pageSize)
  Entity:
    type: object
    required:
      - id
      - value
    properties:
      id:
        type: integer
        description: unique entity ID
      value:
        type: string
        description: entity value
      frequency:
        type: integer
        description: number of times the entity occurs in the result set
      spread:
        type: integer
        description: number of distinct sources the entity occurs in in the result set
    
  CRCList:
    type: object
    required:
      - crcs
    properties:
      crcs:
        type: array 
        items:
          title: CRC
          type: object
          required:
            - id
            - relation
            - frequency
            - spread
          properties:
            id:
              type: integer
              description: unique entity ID
            master: 
              type: string
              description: entity value of the master concept
            relation: 
              type: string
              description: entity value of the relation
            slave: 
              type: string   
              description: entity value of the slave concept
            frequency:
              type: integer
              description: number of times the CRC occurs in the result set
            spread:
              type: integer
              description: number of distinct sources the CRC occurs in in the result set
      count:
        type: integer
        description: number of result CRCs (ignoring page and pageSize)
  CRC:
    type: object
    required:
      - relation
    properties:
      master: 
        type: string
        description: entity value of the master concept
      relation: 
        type: string
        description: entity value of the relation
      slave: 
        type: string   
        description: entity value of the slave concept
  BlacklistList:
    type: object
    required: ["blacklists"]
    properties:
      blacklists:
        type: array
        items:
          $ref: '#/definitions/BlacklistDetails'
  BlacklistDetails:
    type: object
    required: ["id", "name"]
    properties:
      id:
        type: integer
      name:
        type: string
      description:
        type: string
      elements:
        type: array
        items:
          type: string
 
  DictionaryList:
    type: object
    required: ["dictionaries"]
    properties:
      dictionaries:
        type: array
        items:
          $ref: '#/definitions/DictionaryDetails'
      count:
        type: integer
        description: total number of dictionaries (ignoring page and pageSize)
  DictionaryDetails:
    type: object
    required: ["id", "name"]
    properties:
      id:
        type: integer
      name:
        type: string
      language:
        $ref: '#/definitions/LanguageCode'
      description:
        type: string
      items:
        type: array
        items:
          $ref: '#/definitions/DictionaryItemDetails'
  DictionaryItemDetails:
    type: object
    required: ["id", "name", "uri"]
    properties:
      id:
        type: integer
      name:
        description: display label
        type: string
      uri:
        description: unique, domain-wide identifier for this Dictionary Item
        type: string
      language:
        $ref: '#/definitions/LanguageCode'
      terms:
        type: array
        items:
          $ref: '#/definitions/DictionaryTermDetails'
  DictionaryTermDetails:
    type: object
    required: ["id"]
    example: { id: 123, string: "palm tree" }
    properties:
      id:
        type: integer
      language:
        $ref: '#/definitions/LanguageCode'
      string:
        description: if this is a regular term, the term string value
        type: string
      regexp:
        description: if this is a regular expression format term, the regular expression
        type: string
      replace:
        description: if this is a regular expression format term, the replacement string
        type: string
      formatClass:
        description: if this is a format term, the name of the format implementation class
        type: string
      formatParams:
        description: if this is a format term, any additional parameters for the format implementation class
        type: array
        items:
          type: string
  MatchList:
    type: object
    required: ["matches"]
    properties:
      matches:
        type: array
        items:
          $ref: '#/definitions/MatchListItem'
  MatchListItem:
    type: object
    required: [ "id", "score" ]
    properties:
      id:
        type: integer
      score:
        type: number
        description: aggregated score for this match
      partialCount:
        type: integer
        description: number of partially matched entities for this match
      ordered:
        type: boolean
        format: integer
        description: whether or not the matched entities appear in the term's order
      negatedCount:
        type: integer
        description: number of entities
      term:
        type: object
        title: MatchedTerm
        required: ["id","item"]
        properties:
          id:
            type: integer
          string:
            type: string
          item:
            title: MatchedItem
            type: object
            required: ["id", "uri", "name", "dictionary" ]
            properties:
              id:
                type: integer
              name:
                type: string
              uri:
                type: string
              dictionary:
                title: MatchedDictionary
                type: object
                required: ["id", "name"]
                properties:
                  id:
                    type: integer
                  name:
                    type: string
      target:
        title: MatchTarget
        type: object
        description: the matched piece of the source text
        properties:
          id:
            type: integer
          type:
            type: string
            enum: ["entity", "crc", "path", "sentence"]
      sentenceId:
        type: integer
      sentence:
        type: string
        description: full text of the sentence where the match occurred
      elements:
        type: array
        description: detailed overview of entity-level match results
        items:
          type: object
          title: MatchedElements
          required: ["partId", "literal", "score", "role", "matchedWords", "negated"]
          properties:
            partId:
              type: integer
              description: entity occurrence / part ID of the matched sentence part
            literal:
              type: string
              description: literal string how this part appeared in the sentence
            score:
              type: number
              description: entity-level score
            role:
              type: string
              enum: ["concept", "relation", "pathRelevant" ]
              description: role of this sentence part
            matchedWords:
              type: string
              description: which words within the entity actually matched
            negated:
              type: boolean
              format: integer
              description: whether this sentence part is part of a negative context
            entityId:
              type: integer
              description: entity ID, if this part corresponds to an entity
            entity:
              type: string
              description: entity value, if this part corresponds to an entity
            output:
              type: string
              description: format output, if this part corresponds to a matched format providing output
                  
  SentenceDetails:
    type: object
    required:
      - id
      - sourceId
      - text
    properties:
      id:
        description: sentence ID
        type: integer
      sourceId:
        description: containing source ID
        type: integer
      text:
        description: sentence text, optionally highlighted
        type: string
      parts:
        description: entities in this sentence
        type: array
        items:
          title: SentencePart
          type: object
          required:
            - partId
            - literal
            - role
          properties:
            partId:
              description: entity / part occurrence ID
              type: integer
            literal:
              description: literal value of this part in the sentence
              type: string
            role:
              description: role of this entity in the path
              type: string
              enum: ["concept", "relation", "pathRelevant"]
            entityId:
              description: unique entity ID, if this is not a non-relevant
              type: integer
            entity:
              description: entity value, if this is not a non-relevant
              type: string
            stemId:
              description: stem ID for this entity, if the domain is configured for stemming
              type: string
            stem:
              description: stem value of this entity, if the domain is configured for stemming
              type: string
            attributes:
              description: semantic attributes for this entity
              type: array
              items:
                title: AttributeInfo
                type: object
                required: ["type", "level"]
                properties:
                  type:
                    description: name of the attribute
                    type: string
                  level:
                    description: level at which the attribute applies
                    type: string
                    enum: ["path", "word"] 
                  words:
                    description: if level="word", the actual words affected
                    type: string
                  properties:
                    description: attribute properties
                    type: object
  HighlightSpec:
    # TODO: move into proper hierarchy once swagger-ui supports it
    description: The parameters needed for %iFind.Utils.Highlight
    type: object
    example: 
      { "tag": "<b>", "limit":0, "name": "Highlighted"}
    properties:
      tag:
        description: the tags used to enclose the highlighted segments
        type: string
        default: "<b>"
      limit:
        description: limit the segments get highlighted,check %iFind.Utils.Highlight() for details
        type: integer
        default: 0 
      name:
        description: the alias name for the column containing highlighted text
        type: string
        default: "Highlighted"
  RankSpec:
    # TODO: move into proper hierarchy once swagger-ui supports it
    description: The parameters needed for %iFind.Utils.Rank
    type: object
    example: 
      { "name":"Rank" }
    properties:
      name:
        description: the alias name for the column containing rank info
        type: string
        default: "Rank"
  OptionSpec:
    description: The option could be object which includes all the required parameters. However, you could still use "0","1","2","3","4" these simple strings for option for the legacy support
    type: object
    properties:
      mode:
        type: string
        enum: ["0","1","2","3","4","*","normal","stemmed","decompounded","fuzzy","regex"]
        description: the iFind search options. 0/normal search,1/stemmed search,2/decompunded search,3/fuzzy search,4/regex search, "*" indicates use the index setting
      stemmer:
        type: string
        description: the stemming/decompounding class
      arguments:
        type: array
        description: the arguments needed for initialize a stemming/decompounding class
        items:
          type: string
      distance:
        type: string
        description: the fuzzy search threshold.

Method Inventory

Parameters

parameter SNIPPETSIZE = 2;

Methods

classmethod AddSource(namespace As %String, pDomainId As %Integer) as %Status
      summary: |
        Adds a source to the domain
      tags: ["Sources"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            required: ["reference", "text"]
            properties:
              reference:
                description: a string to be used for building the new record's external ID
                type: string
              text:
                description: the text to index
                type: string
              configuration:
                description: name of a valid configuration object to use or the two-letter ISO code for the language to use (if no such configuration exists)
                type: string
                example: en
              virtual:
                description: if true, the source will be added as a virtual one
                type: boolean
                default: 0
                format: integer
              metadata:
                description: map of metadata field values to set for the document
                type: object
      responses:
        200:
          description: Successful response
          schema:
            type: object
            required: ["id"]
            properties:
              id:
                description: source ID of the newly created record
                type: integer
classmethod AddStringToBlacklist(namespace As %String, pDomainId As %Integer, pBlacklistId As %Integer, pElements As %String = "") as %Status
      summary: |
        Adds new elements to a given blacklist
      tags: ["Blacklists"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          in: path
          type: string
          description: ID of the blacklist to extend
          required: true
        - name: string
          in: path
          type: string
          description: element to add to the blacklist
          required: true
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              elements: 
                description: if set, overrides what's passed in through the path parameter
                type: array
                example: []
                items:
                  type: string
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              added:
                description: number of elements added
                type: integer
classmethod ClearBlacklist(namespace As %String, pDomainId As %Integer, pBlacklistId As %Integer) as %Status
      summary: |
        Clears all entries for a given blacklist
      tags: ["Blacklists"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          in: path
          type: string
          description: ID of the blacklist to clear
          required: true
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              cleared:
                type: boolean
                format: integer
classmethod CreateBlacklist(namespace As %String, pDomainId As %Integer, pName As %String = "") as %Status
      summary: |
        Creates a new blacklist
      tags: ["Blacklists"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: name
          in: path
          description: name of the new blacklist
          required: true
          type: string
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              name:
                description: overrides what's passed in through the path parameter if set
                type: string
              description:
                type: string
              elements: 
                type: array
                example: []
                items:
                  type: string
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/BlacklistDetails'
classmethod CreateDictionary(namespace As %String, pDomainId As %Integer, pName As %String = "") as %Status
      summary: |
        Create a new dictionary
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: name
          description: name for the new dictionary
          in: path
          type: string
          required: true
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              name:
                description: if provided, overrides the path parameter
                type: string
              description:
                type: string
              language:
                description: default language for dictionary entries
                $ref: '#/definitions/LanguageCode'
              items:
                description: list of items to add (don't supply id values)
                type: array
                items:
                  $ref: '#/definitions/DictionaryItemDetails'
              match:
                description: if set to true, the dictionary is immediately matched against the domain's sources
                type: boolean
                format: integer
              filter:
                description: if match=1, restricts the sources to be matched
                $ref: '#/definitions/Filter'
      responses:
        200:
          description: Successful response
          schema:
            allOf:
              - $ref: '#/definitions/DictionaryDetails'
              - type: object
                properties:
                  created:
                    type: boolean
                    format: integer
                    default: 1
                  matched:
                    type: boolean
                    format: integer
classmethod CreateDictionaryItems(namespace As %String, pDomainId As %Integer, pDictionaryId As %Integer = 0) as %Status
      summary: |
        Create new dictionary items
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          description: ID of the dictionary to which to add the new item
          in: path
          type: string
          required: true
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          required: true
          schema:
            type: object
            properties:
              dictionaryId:
                description: if provided, overrides the path parameter
                type: string
              items:
                description: list of items to add (don't supply id values)
                type: array
                items:
                  $ref: '#/definitions/DictionaryItemDetails'
              match:
                description: if set to true, the dictionary is immediately matched against the domain's sources
                type: boolean
                format: integer
              filter:
                description: if match=1, restricts the sources to be matched
                $ref: '#/definitions/Filter'
      responses:
        200:
          description: Successful response
          schema:
            title: AddItemsResult
            type: object
            properties:
              dictionary:
                type: object
                title: DictionaryDetails
                description: the dictionary these items were added to
                properties:
                  id:
                    type: integer
                  name:
                    type: string
              items:
                type: array
                items:
                  allOf:
                    - $ref: '#/definitions/DictionaryItemDetails'
                    - type: object
                      properties:
                        error:
                          description: the error message, if this item failed to get created
                          type: string
              matched:
                type: boolean
                format: integer
classmethod CreateDictionaryItemsPOST(namespace As %String, pDomainId As %Integer) as %Status
Simplified version of CreateDictionaryItems() for HTTP POST requests
      summary: |
        Create new dictionary items
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          required: true
          schema:
            type: object
            required: ["dictionaryId", "items"]
            properties:
              dictionaryId:
                description: if provided, overrides the path parameter
                type: string
              items:
                description: list of items to add (don't supply id values)
                type: array
                items:
                  $ref: '#/definitions/DictionaryItemDetails'
              match:
                description: if set to true, the dictionary is immediately matched against the domain's sources
                type: boolean
                format: integer
              filter:
                description: if match=1, restricts the sources to be matched
                $ref: '#/definitions/Filter'
      responses:
        200:
          description: Successful response
          schema:
            title: AddItemsResult
            type: object
            properties:
              dictionary:
                type: object
                title: DictionaryDetails
                description: the dictionary these items were added to
                properties:
                  id:
                    type: integer
                  name:
                    type: string
              items:
                type: array
                items:
                  allOf:
                    - $ref: '#/definitions/DictionaryItemDetails'
                    - type: object
                      properties:
                        error:
                          description: the error message, if this item failed to get created
                          type: string
              matched:
                type: boolean
                format: integer
classmethod CreateDictionaryTerms(namespace As %String, pDomainId As %Integer, pDictionaryItemId As %Integer = 0) as %Status
      summary: |
        Create new dictionary terms
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          description: ID or URI of the dictionary item to which to add the new terms
          in: path
          type: string
          required: true
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          required: true
          schema:
            type: object
            properties:
              dictionaryItemId:
                description: if provided, overrides the corresponding path parameter
                type: string
              terms:
                description: list of terms to add (don't supply id values). An array of strings will be interpreted as simple terms.
                type: array
                items:
                  $ref: '#/definitions/DictionaryTermDetails'
              match:
                description: if set to true, the dictionary is immediately matched against the domain's sources
                type: boolean
                format: integer
              filter:
                description: if match=1, restricts the sources to be matched
                $ref: '#/definitions/Filter'
      responses:
        200:
          description: Successful response
          schema:
            title: AddTermsResult
            type: object
            properties:
              item:
                type: object
                title: DictionaryItemDetails
                description: the dictionary item these terms were added to
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  uri:
                    type: string
                  dictionary:
                    type: object
                    title: DictionaryDetails
                    description: the dictionary these terms were added to
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
              terms:
                type: array
                items:
                  allOf:
                    - $ref: '#/definitions/DictionaryTermDetails'
                    - type: object
                      properties:
                        error:
                          description: the error message, if this term failed to get created
                          type: string
              matched:
                type: boolean
                format: integer
classmethod DropBlacklist(namespace As %String, pDomainId As %Integer, pBlacklistId As %Integer) as %Status
      summary: |
        Drops a given blacklist
      tags: ["Blacklists"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          in: path
          type: string
          description: ID of the blacklist to drop
          required: true
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              dropped:
                type: boolean
                format: integer
classmethod DropDictionary(namespace As %String, pDomainId As %Integer, pDictionaryId As %Integer) as %Status
      summary: |
        Drops a dictionary
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          description: ID of the dictionary to drop
          in: path
          type: integer
          required: true
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              dropped:
                type: boolean
                format: integer
classmethod DropDictionaryItem(namespace As %String, pDomainId As %Integer, pDictionaryItemId As %Integer) as %Status
      summary: |
        Drops a dictionary item
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          description: ID or URI of the dictionary item to drop
          in: path
          type: integer
          required: true
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              dropped:
                type: boolean
                format: integer
classmethod DropDictionaryTerm(namespace As %String, pDomainId As %Integer, pDictionaryTermId As %Integer) as %Status
      summary: |
        Drops a dictionary term
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          description: ID of the dictionary term to drop
          in: path
          type: integer
          required: true
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              dropped:
                type: boolean
                format: integer
classmethod DropSource(namespace As %String, pDomainId As %Integer, pSourceId As %Integer) as %Status
      summary: |
        Deletes a source from the domain
      tags: ["Sources"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: source
          description: the source ID to drop
          in: path
          required: true
          type: integer
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              virtual:
                description: if set, the supplied source ID will be used to look up a virtual source
                type: boolean
                format: integer
                default: 0
      responses:
        200:
          description: Successful response
          schema:
            type: object
            required:
              - deleted
            properties:
              deleted:
                type: boolean
                format: integer
classmethod GetBlacklistDetails(namespace As %String, pDomainId As %Integer, pBlacklistId As %Integer) as %Status
      summary: |
        Retrieves a particular blacklist's contents
      tags: ["Blacklists"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          in: path
          type: integer
          description: ID of the blacklist being queried
          required: true
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/BlacklistDetails'
classmethod GetBlacklists(namespace As %String, pDomainId As %Integer) as %Status
      summary: |
        Retrieves a list of available blacklists
      tags: ["Blacklists"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              includeDetails:
                description: whether or not to retrieve blacklists' contents as well
                type: boolean
                format: integer
              includeCrossDomain: 
                description: whether or not to include cross-domain blacklists
                type: boolean
                format: integer
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/BlacklistList'
classmethod GetCRCs(namespace As %String, pDomainId As %Integer) as %Status
      summary: |
        Retrieves the top CRCs for this domain
      tags: ["Paths and CRCs"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
              filterMode:
                $ref: '#/definitions/FilterMode'
              sortBy:
                description: criterion to use for retrieving the top entities
                type: string
                default: "domainDefault"
                example: "domainDefault"
                enum: ["frequency", "spread", "domainDefault"]
              includeCount:
                $ref: '#/definitions/IncludeCount'
              countOnly:
                $ref: '#/definitions/CountOnly'
                
      responses:
        200:
          description: Successful response
          schema: 
            $ref: '#/definitions/CRCList'
classmethod GetCRCsByEntity(namespace As %String, pDomainId As %Integer, pEntity As %String = "") as %Status
      summary: |
        Retrieves the CRCs containing a designated entity
      tags: ["Paths and CRCs"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: entity
          description: the entity to query for
          in: path
          required: true
          type: string
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              entity:
                description: if set, takes precedence over the path parameter
                type: array
                items:
                  type: string
                default: ""
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
              filterMode:
                $ref: '#/definitions/FilterMode'
              positions:
                description: CRC positions to query
                type: array
                default: ["master", "relation", "slave"]
                example: ["master", "relation", "slave"]
                items:
                  type: string
                  enum: ["master", "relation", "slave"]
              actualFormOnly:
                type: boolean
                format: integer
                description: when this domain supports stemming, set to true to restrict to the supplied actual form only
                default: 0
              includeCount:
                $ref: '#/definitions/IncludeCount'
              countOnly:
                $ref: '#/definitions/CountOnly'
                
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/CRCList'
classmethod GetConfigurations(namespace As %String) as %Status
      summary: |
        Retrieves all the configurations for this namespace, with basic info
      tags: ["Miscellaneous"]
      parameters:
        - name: RequestBody
          description: additional parameters to configure this query
          in: body
          required: false
          schema:
            type: object
            properties:
              includeUserDictionaryContents:
                type: boolean
                description: Whether or not to include user dictionary contents
                default: false
                format: integer
      responses:
        200:
          description: Successful response
          schema: 
            $ref: '#/definitions/ConfigurationList'
classmethod GetDictionaries(namespace As %String, pDomainId As %Integer) as %Status
      summary: |
        Retrieves a list of available dictionaries
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              includeItems:
                description: whether or not to include item and term details as well
                type: boolean
                format: integer
              includeCount:
                $ref: '#/definitions/IncludeCount'
              countOnly:
                $ref: '#/definitions/CountOnly'
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/DictionaryList'
classmethod GetDictionaryDetails(namespace As %String, pDomainId As %Integer, pDictionaryId As %Integer) as %Status
      summary: |
        Retrieves the detailed contents for a given Dictionary
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          description: ID of the dictionary to retrieve
          in: path
          type: integer
          required: true
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/DictionaryDetails'
classmethod GetDictionaryItemDetails(namespace As %String, pDomainId As %Integer, pDictionaryItemId As %Integer) as %Status
      summary: |
        Retrieves the detailed contents for a given Dictionary Item
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          description: ID or URI of the dictionary item to retrieve
          in: path
          type: integer
          required: true
      responses:
        200:
          description: Successful response
          schema:
            allOf:
              - $ref: '#/definitions/DictionaryItemDetails'
              - type: object
                properties:
                  dictionary:
                    type: object
                    properties:
                      id: 
                        type: integer
                      name:
                        type: string
classmethod GetDomainDetails(namespace As %String, pDomainId As %Integer) as %Status
      summary: |
        Retrieve more detailed information about an individual domain
      tags: ["Miscellaneous"]
      parameters:
        - $ref: '#/parameters/domainParam'
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/DomainDetails'
classmethod GetDomains(namespace As %String) as %Status
      summary: |
        Retrieves all the domains for this namespace, with basic info
      tags: ["Miscellaneous"]
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/DomainList'
classmethod GetEntities(namespace As %String, pDomainId As %Integer) as %Status
      summary: |
        Retrieves the top entities for this domain
      tags: ["Entities"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
              filterMode:
                $ref: '#/definitions/FilterMode'
              blacklists:
                $ref: '#/definitions/Blacklists'
              sortBy:
                description: criterion to use for retrieving the top entities
                type: string
                default: "domainDefault"
                example: "domainDefault"
                enum: ["frequency", "spread", "domainDefault", "dominance", "bm25", "tfidf"]
              useStems:
                description: |
                  retrieve stems rather than entities. (only available when the domain has stemming enabled and for certain sortBy values)
                type: integer
                default: 0
                format: integer
              role:
                description: whether to retrieve top concepts, relationships or both (only available for certain sortBy values)
                type: string
                default: "concept"
                enum: ["concept", "relation", "any"]
              includeMetrics:
                description: additional metrics to retrieve, on top of what is automatically retrieved based on the sortBy value
                type: array
                default: []
                items:
                  type: string
                  enum: ["frequency", "spread", "dominance", "tfidf"]
              includeCount:
                $ref: '#/definitions/IncludeCount'
              countOnly:
                $ref: '#/definitions/CountOnly'
                
      responses:
        200:
          description: Successful response
          schema: 
            title: EntityList
            type: object
            properties:
              entities:
                type: array 
                items:
                  title: Entity
                  type: object
                  required:
                    - id
                    - value
                  properties:
                    id:
                      type: integer
                      description: unique entity ID
                    value:
                      type: string
                      description: entity value
                    frequency:
                      type: integer
                      description: number of times the entity occurs in the result set
                    spread:
                      type: integer
                      description: number of distinct sources the entity occurs in in the result set
                    dominance:
                      type: number
                      description: relevance of the entity in this result set
                    tfidf:
                      type: number
                      description: TFIDF-based metric expressing relevance of the entity in this result set
                    bm25:
                      type: number
                      description: BM25-based metric expressing relevance of the entity in this result set
              count:
                type: integer
                description: total number of entities in this domain (if RequestBody.includeCount is true, ignoring page and pageSize)
classmethod GetEntityDetails(namespace As %String, pDomainId As %Integer, pEntity As %String = "") as %Status
      summary: |
        Retrieves details for the supplied entity
      tags: ["Entities"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: entity
          description: the entity whose details need to be returned
          in: path
          required: true
          type: string
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              entity:
                description: if set, overrides the value of the path parameter
                type: string
                default: ""
              filter:
                description: if set, restricts the dataset on which metrics should be based
                $ref: '#/definitions/Filter'
              useStems:
                description: only available when the domain has stemming enabled
                type: boolean
                default: 0
                format: integer
              roles:
                description: roles for which the metrics need to be retrieved
                type: array
                default: ["concept", "relation", "any"]
                example: ["concept", "relation", "any"]
                items:
                  type: string
                  enum: ["concept", "relation", "any"]
              includeMetrics:
                description: metrics to retrieve
                type: array
                default: ["frequency", "spread", "tfidf"]
                example: ["frequency", "spread", "tfidf"]
                items:
                  type: string
                  enum: ["frequency", "spread", "tfidf"]
                
      responses:
        200:
          description: Successful response
          schema: 
            title: EntityDetails
            type: object
            required:
              - id
              - value
            properties:
              id:
                type: integer
                description: unique entity ID
              value:
                type: string
                description: entity value
              metricsAsConcept:
                type: object
                properties:
                  frequency:
                    type: integer
                    description: number of times the entity occurs in the result set
                  spread:
                    type: integer
                    description: number of distinct sources the entity occurs in in the result set
                  tfidf:
                    type: number
                    description: TFIDF-based metric expressing relevance of the entity in this result set
              metricsAsRelation:
                type: object
                properties:
                  frequency:
                    type: integer
                    description: number of times the entity occurs in the result set
                  spread:
                    type: integer
                    description: number of distinct sources the entity occurs in in the result set
                  tfidf:
                    type: number
                    description: TFIDF-based metric expressing relevance of the entity in this result set
              metricsAsAny:
                type: object
                properties:
                  frequency:
                    type: integer
                    description: number of times the entity occurs in the result set
                  spread:
                    type: integer
                    description: number of distinct sources the entity occurs in in the result set
                  tfidf:
                    type: number
                    description: TFIDF-based metric expressing relevance of the entity in this result set
classmethod GetMatchesByItem(namespace As %String, pDomainId As %Integer, pDictionaryItemId As %Integer) as %Status
      summary: |
        Retrieves all dictionary matches for a dictionary item
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          description: the dictionary item ID or URI to query for
          in: path
          required: true
          type: integer
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
                description: optionally filters the results to those matches in sources selected by this filter
              matchFirst:
                description: ensures the domain is matched against the latest dictionaries before retrieving results
                type: boolean
                format: integer
                default: 1
              includeDictionaryDetails:
                description: whether or not to dictionary details as well
                type: boolean
                format: integer
                default: 1
              includeMatchDetails:
                description: whether or not to entity-level match details as well
                type: boolean
                format: integer
                default: 0
              includeSnippets:
                description: whether or not to include the text of the matched sentence
                type: boolean
                format: integer
                default: 1
              highlight:
                $ref: '#/definitions/Highlighting'
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/MatchList'
classmethod GetMatchesBySource(namespace As %String, pDomainId As %Integer, pSourceId As %Integer) as %Status
      summary: |
        Retrieves all dictionary matches for a given source
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          description: the source ID to query for
          in: path
          required: true
          type: integer
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              matchFirst:
                description: ensures this source is matched against the latest dictionaries before retrieving results
                type: boolean
                format: integer
                default: 1
              dictionaries:
                description: if set, limits results to these dictionary IDs
                default: []
                type: array
                items:
                  type: integer
              includeDictionaryDetails:
                description: whether or not to retrieve dictionary details as well
                type: boolean
                format: integer
                default: 1
              includeMatchDetails:
                description: whether or not to retrieve entity-level match details as well
                type: boolean
                format: integer
                default: 0
              includeSnippets:
                description: whether or not to include the text of the matched sentence
                type: boolean
                format: integer
                default: 1
              highlight:
                $ref: '#/definitions/Highlighting'
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/MatchList'
classmethod GetPathsByEntity(namespace As %String, pDomainId As %Integer, pEntity As %String = "") as %Status
      summary: |
        Retrieves the paths containing a designated entity
      tags: ["Paths and CRCs"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: entity
          description: the entity to query for
          in: path
          required: true
          type: string
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              entity:
                description: if set, takes precedence over the path parameter
                type: array
                items:
                  type: string
                default: ""
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
              includeDetails:
                description: whether or not to include details on the entities for each path
                type: boolean
                default: 1
                format: integer
              actualFormOnly:
                type: boolean
                format: integer
                description: when this domain supports stemming, set to true to restrict to the supplied actual form only
                default: 0
              setOperation:
                type: string
                enum: ["union", "intersect"]
                description: when supplying multiple entities, controls how the results for each entity should be combined
              includeCount:
                $ref: '#/definitions/IncludeCount'
              countOnly:
                $ref: '#/definitions/CountOnly'
                
      responses:
        200:
          description: Successful response
          schema:
            title: PathList
            type: object
            properties:
              paths:
                type: array
                items:
                  title: Path
                  properties:
                    id:
                      description: path ID
                      type: integer
                    entities:
                      description: entities in this path
                      type: array
                      items:
                        title: PathEntity
                        type: object
                        required:
                          - id
                          - entity
                        properties:
                          id:
                            description: unique entity ID
                            type: integer
                          entity:
                            description: entity value
                            type: string
                          partId:
                            description: entity occurrence ID
                            type: integer
                          role:
                            description: role of this entity in the path
                            type: string
                            enum: ["concept", "relation", "pathRelevant"]
                          stemId:
                            description: stem ID for this entity, if the domain is configured for stemming
                            type: integer
                          stem:
                            description: stem value of this entity, if the domain is configured for stemming
                            type: string
                          attributes:
                            description: semantic attributes for this entity
                            type: array
                            items:
                              title: AttributeInfo
                              type: object
                              required: ["type", "level"]
                              properties:
                                type:
                                  description: name of the attribute
                                  type: string
                                level:
                                  description: level at which the attribute applies
                                  type: string
                                  enum: ["path", "word"] 
                                words:
                                  description: if level="word", the actual words affected
                                  type: string
                                properties:
                                  description: attribute properties
                                  type: object
              count:
                description: total number of paths, ignoring page and pageSize
                type: integer
classmethod GetRelatedEntities(namespace As %String, pDomainId As %Integer, pEntity As %String = "") as %Status
      summary: |
        Retrieves entities related to a seed entity based on proximity or direct relationships
      tags: ["Entities"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: entity
          description: the seed entity to find related entities for
          in: path
          required: true
          type: string
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              entity:
                description: if set, overrides value of path parameter
                type: string
                default: ""
                example: ""
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
              filterMode:
                $ref: '#/definitions/FilterMode'
              blacklists:
                $ref: '#/definitions/Blacklists'
              sortBy:
                description: criterion to use for retrieving the related entities
                type: string
                default: "proximity"
                example: "proximity"
                enum: ["proximity", "frequency", "spread"]
              includeCount:
                $ref: '#/definitions/IncludeCount'
              countOnly:
                $ref: '#/definitions/CountOnly'
                
      responses:
        200:
          description: Successful response
          schema: 
            $ref: '#/definitions/EntityList'
classmethod GetSentenceDetails(namespace As %String, pDomainId As %Integer, pSentenceId As %Integer) as %Status
      summary: |
        Retrieves the details for a particular sentence
      tags: ["Sentences"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          description: the sentence ID to query for
          in: path
          required: true
          type: integer
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              highlight:
                $ref: '#/definitions/Highlighting'
              virtualSourceId:
                description: if set, the sentence will be looked up in the context of this virtual source
                type: integer
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/SentenceDetails'
classmethod GetSentencesByEntity(namespace As %String, pDomainId As %Integer, pEntity As %String = "") as %Status
      summary: |
        Retrieves the sentences containing a given entity
      tags: ["Sentences"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: entity
          description: the entity to query for
          in: path
          required: true
          type: string
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              entity:
                description: if set, takes precedence over the corresponding path parameter
                type: array
                items:
                  type: string
                default: ""
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
              highlight:
                $ref: '#/definitions/Highlighting'
              includeDetails:
                description: whether or not to include details on the entities for each sentence
                type: boolean
                default: 1
                format: integer
              actualFormOnly:
                type: boolean
                format: integer
                description: when this domain supports stemming, set to true to restrict to the supplied actual form only
                default: 0
              setOperation:
                type: string
                enum: ["union", "intersect"]
                description: when supplying multiple entities, controls how the results for each entity should be combined
              includeCount:
                $ref: '#/definitions/IncludeCount'
              countOnly:
                $ref: '#/definitions/CountOnly'
      responses:
        200:
          description: Successful response
          schema:
            title: SentenceList
            type: object
            required: ["sentences"]
            properties:
              sentences:
                type: array
                items:
                  $ref: '#/definitions/SentenceDetails'
              count:
                description: total number of paths, ignoring page and pageSize (if RequestBody.includeCount is set)
                type: integer
classmethod GetSimilarEntities(namespace As %String, pDomainId As %Integer, pString As %String = "") as %Status
      summary: |
        Retrieves entities similar to a seed string
      tags: ["Entities"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: string
          description: the seed string to find similar entities for
          in: path
          required: true
          type: string
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              string:
                description: if set, overrides value of path parameter
                type: string
                default: ""
                example: ""
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
              filterMode:
                $ref: '#/definitions/FilterMode'
              blacklists:
                $ref: '#/definitions/Blacklists'
              type:
                description: |
                  method to calculate / retrieve similar entities. ("ngrams" requires the domain to be configured for it)
                type: string
                default: "domainDefault"
                example: "domainDefault"
                enum: ["domainDefault", "parts", "ngrams", "words"]
              useStems:
                description: retrieve stems rather than entities. (only available when the domain has stemming enabled and for certain sortBy values)
                type: boolean
                default: 0
                format: integer
              role:
                description: whether to retrieve top concepts, relationships or both (only available for certain sortBy values)
                type: string
                default: "any"
                example: "any"
                enum: ["concept", "relation", "any"]
              includeCount:
                $ref: '#/definitions/IncludeCount'
              countOnly:
                $ref: '#/definitions/CountOnly'
                
      responses:
        200:
          description: Successful response
          schema: 
            $ref: '#/definitions/EntityList'
classmethod GetSimilarSources(namespace As %String, pDomainId As %Integer, pSourceId As %Integer) as %Status
      summary: |
        Retrieves all sources similar to a seed source
      tags: ["Sources"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - $ref: '#/parameters/sourceParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
              highlight:
                $ref: '#/definitions/Highlighting'
              algorithm:
                type: string
                enum: ["simple", "dominantEntities"]
                description: algorithm to use for calculating similar entities
                default: "simple"
              parameters:
                type: array
                items:
                  type: string
                description: additional parameters to tune the algorithm
                default: []
              includeMetadata:
                description: whether or not to include metadata for each retrieved source
                type: boolean
                default: 1
                format: integer
              includeSnippets:
                description: if set to a nonzero value, a snippet of the designated length (in sentences) will be retrieved for each source
                type: integer
                default: {{{SNIPPETSIZE}}}
                
      responses:
        200:
          description: Successful response
          schema:
            allOf:
              - $ref: '#/definitions/SourceList'
              - type: object
                properties:
                  score:
                    type: number
                    description: score expressing the similarity between this record and the seed document
                  percentageMatched:
                    type: number
                  percentageNew:
                    type: number
                  numberOfEntitiesInRefSource:
                    type: integer
                  numberOfEntitiesInCommon:
                    type: integer
                  numberOfEntitiesInThisSource:
                    type: integer
classmethod GetSourceDetails(namespace As %String, pDomainId As %Integer, pSourceId As %Integer) as %Status
      summary: |
        Retrieves the details of a particular source
      tags: ["Sources"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - $ref: '#/parameters/sourceParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              includeMetadata:
                description: whether or not to include metadata for the designated source
                type: boolean
                default: 1
                format: integer
              includeText:
                description: whether or not to include the full source text in the result
                type: boolean
                default: 1
                format: integer
              summarize:
                description: if set, the text returned will be a summary of the full contents, measuring this many sentences
                type: number
              virtual:
                description: if set to true, the source ID will be considered to refer to a virtual source
                type: boolean
                default: 0
                format: integer
              highlight:
                $ref: '#/definitions/Highlighting'
                
      responses:
        200:
          description: Successful response
          schema: 
            title: Source
            type: object
            properties:
              text:
                type: string
                description: textual contents (optionally summarized) of this source
              metadata:
                type: object
                description: metadata map for this source
              virtual:
                type: boolean
                format: integer
                description: whether or not this is a virtual source
classmethod GetSources(namespace As %String, pDomainId As %Integer) as %Status
      summary: |
        Retrieves all sources matching the supplied filter
      tags: ["Sources"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
              highlight:
                $ref: '#/definitions/Highlighting'
              includeMetadata:
                description: whether or not to include metadata for each retrieved source
                type: boolean
                default: 1
                format: integer
              includeSnippets:
                description: if set to a nonzero value, a snippet of the designated length (in sentences) will be retrieved for each source
                type: integer
                default: {{{SNIPPETSIZE}}}
              includeCount:
                $ref: '#/definitions/IncludeCount'
              countOnly:
                $ref: '#/definitions/CountOnly'
                
      responses:
        200:
          description: Successful response
          schema: 
            $ref: '#/definitions/SourceList'
classmethod GetSourcesByCRC(namespace As %String, pDomainId As %Integer, pCRC As %String = "") as %Status
      summary: |
        Retrieves all sources containing the supplied CRC
      tags: ["Sources"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: crc
          in: path
          description: CRC to look for, as a colon-separated sequence of master, relation and slave. If supplied in the request object, that value will take precedence over the path parameter
          type: string
          required: true
          #example: john:likes:bananas
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              crc:
                type: array
                items:
                  $ref: '#/definitions/CRC'
                description: |
                  if supplied, overwrites the value of the "crc" path parameter
                default: ""
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
              highlight:
                $ref: '#/definitions/Highlighting'
              includeMetadata:
                description: whether or not to include metadata for each retrieved source
                type: boolean
                default: 1
                format: integer
              includeSnippets:
                description: if set to true, a snippet made up of all the sentences containing the designated CRCs will be retrieved for each source
                type: boolean
                default: 1
                format: integer
              setOperation:
                type: string
                enum: ["union", "intersect"]
                description: when supplying multiple entities, controls how the results for each entity should be combined
              includeCount:
                $ref: '#/definitions/IncludeCount'
              countOnly:
                $ref: '#/definitions/CountOnly'
                
      responses:
        200:
          description: Successful response
          schema: 
            $ref: '#/definitions/SourceList'
classmethod GetSourcesByEntity(namespace As %String, pDomainId As %Integer, pEntity As %String = "") as %Status
      summary: |
        Retrieves all sources containing the supplied entity
      tags: ["Sources"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: entity
          in: path
          description: entity to look for. If supplied in the request object, that value will take precedence over the path parameter
          type: string
          required: true
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              entity:
                type: array
                items:
                  type: string
                description: |
                  if supplied, overwrites the value of the "entity" path parameter
                default: ""
              page:
                $ref: '#/definitions/PageNumber'
              pageSize:
                $ref: '#/definitions/PageSize'
              filter:
                $ref: '#/definitions/Filter'
              highlight:
                $ref: '#/definitions/Highlighting'
              includeMetadata:
                description: whether or not to include metadata for each retrieved source
                type: boolean
                default: 1
                format: integer
              includeSnippets:
                description: if set to true, a snippet made up of all sentences containing the designated entities will be retrieved for each source
                type: boolean
                default: 1
                format: integer
              actualFormOnly:
                type: boolean
                format: integer
                description: when this domain supports stemming, set to true to restrict to the supplied actual form only
                default: 0
              setOperation:
                type: string
                enum: ["union", "intersect"]
                description: when supplying multiple entities, controls how the results for each entity should be combined
              includeCount:
                $ref: '#/definitions/IncludeCount'
              countOnly:
                $ref: '#/definitions/CountOnly'
                
      responses:
        200:
          description: Successful response
          schema: 
            $ref: '#/definitions/SourceList'
classmethod Highlight(namespace As %String, pDomainId As %Integer = 0) as %Status
      summary: |
        Highlights the supplied text
      tags: ["Miscellaneous"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            required: ["highlight", "text"]
            properties:
              text:
                description: the text to highlight
                example: "This text is in urgent need of fancy markup!"
                type: string
              configuration:
                description: name of a valid configuration object to use or the two-letter ISO code for the language to use (if no such configuration exists)
                type: string
                example: en
              highlight:
                description: highlighting specification
                $ref: '#/definitions/Highlighting'
                example: [ { role: "concept", style: "[]" }, { role: "relation", style: "{}" }]
      responses:
        200:
          description: Successful response
          schema:
            type: object
            required: ["text"]
            properties:
              text:
                description: the highlighted text
                type: string
classmethod HighlightSYS(namespace As %String) as %Status
      summary: |
        Highlights the supplied text
      tags: ["Miscellaneous"]
      parameters:
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            required: ["highlight", "text"]
            properties:
              text:
                description: the text to highlight
                example: "This text is in urgent need of fancy markup!"
                type: string
              configuration:
                description: name of a valid configuration object to use or the two-letter ISO code for the language to use (if no such configuration exists)
                type: string
                example: en
              highlight:
                description: highlighting specification
                $ref: '#/definitions/Highlighting'
                example: [ { role: "concept", style: "[]" }, { role: "relation", style: "{}" }]
      responses:
        200:
          description: Successful response
          schema:
            type: object
            required: ["text"]
            properties:
              text:
                description: the highlighted text
                type: string
classmethod Index(namespace As %String, pDomainId As %Integer = 0) as %Status
      summary: |
        Indexes the supplied text and returns concepts, relations and CRCs
      tags: ["Miscellaneous"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            required: ["highlight", "text"]
            properties:
              text:
                description: the text to index
                example: "This text is in urgent need of fancy markup!"
                type: string
              configuration:
                description: name of a valid configuration object to use or the two-letter ISO code for the language to use (if no such configuration exists)
                type: string
                example: en
              summarize:
                description: if set to a nonzero value, the text returned will be a summary of the full contents, measuring this many sentences
                type: number
                default: 0
              highlight:
                description: highlighting specification
                $ref: '#/definitions/Highlighting'
                example: [ { role: "concept", style: "[]" }, { role: "relation", style: "{}" }]
              includeMatches:
                description: whether or not to retrieve dictionary matches for the indexed record
                type: boolean
                format: integer
                default: 0
              dictionaries:
                description: if set, limits results to these dictionary IDs
                default: []
                type: array
                items:
                  type: integer
              includeDictionaryDetails:
                description: whether or not to retrieve dictionary details as well
                type: boolean
                format: integer
                default: 1
              includeMatchDetails:
                description: whether or not to entity-level match details as well
                type: boolean
                format: integer
                default: 0
      responses:
        200:
          description: Successful response
          schema:
            type: object
            required: ["text"]
            properties:
              text:
                description: the highlighted text
                type: string
              concepts:
                description: list of concepts for this text
                type: array
                items:
                  type: object
                  properties:
                    value:
                      type: string
                    frequency:
                      type: integer
                    dominance:
                      type: integer
              relations:
                description: list of relations for this text
                type: array
                items:
                  type: object
                  properties:
                    value:
                      type: string
                    frequency:
                      type: integer
                    dominance:
                      type: integer
              matches:
                description: list of dictionary matches for this text
                type: array
                items:
                  $ref: '#/definitions/MatchListItem'
classmethod MatchAll(namespace As %String, pDomainId As %Integer) as %Status
      summary: |
        Matches all sources against the current dictionary contents
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              filter:
                $ref: '#/definitions/Filter'
                description: optionally limits the operation to those sources selected by this filter
              dictionaries:
                description: if set, limits the operation to these dictionary IDs
                default: []
                type: array
                items:
                  type: integer
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              matched:
                type: boolean
                format: integer
                default: 1
classmethod MatchSource(namespace As %String, pDomainId As %Integer, pSourceId As %Integer) as %Status
      summary: |
        Matches a particular source against the current dictionary contents
      tags: ["Dictionaries and Matching"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - $ref: '#/parameters/sourceParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              dictionaries:
                description: if set, limits the operation to these dictionary IDs
                default: []
                type: array
                items:
                  type: integer
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              matched:
                type: boolean
                format: integer
                default: 1
classmethod RemoveStringFromBlacklist(namespace As %String, pDomainId As %Integer, pBlacklistId As %Integer, pElements As %String = "") as %Status
      summary: |
        Removes elements from a given blacklist
      tags: ["Blacklists"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: id
          in: path
          type: string
          description: ID of the blacklist to modify
          required: true
        - name: string
          in: path
          type: string
          description: element to remove from the blacklist
          required: true
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              elements: 
                description: if set, overrides what's passed in through the path parameter
                type: array
                example: []
                items:
                  type: string
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              removed:
                description: number of elements removed
                type: integer
classmethod SearchIndex(namespace As %String, table As %String) as %Status
      summary: |
        Search the given iFind index in the given table
      tags: ["iFind"]
      parameters:
        - $ref: '#/parameters/tableParam'
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              query:
                description: This is the only necessary parameter with no default value. The search terms to query against the iFind index.
                type: string
              index:
                description: the iFind index would be searched against, if you don't specify it, the first found iFind index would be used .
                type: string
              option:
                $ref: '#/definitions/OptionSpec'
              distance:
                description: only valid when option is fuzzy search (when option is 3)
                type: string
                example: "3"
              language:
                description: iKnow-supported language model to apply, for example "en"
                type: string
              includeText:
                description: whether the returned columns should include the column beging indexed by 'index'
                type: integer
                default: 0
                enum: [0, 1] 
              columns:
                description: specify the columns which also needed to be returned. For example, ["column1","column2"] 
                type: array
                example: []
                items:
                  type: string
              highlightSpec:
                $ref: '#/definitions/HighlightSpec'
                description: the parameters needed for Highlight
              rankSpec:
                $ref: '#/definitions/RankSpec'
                description: the parameters needed for Rank
              where:
                description: the valid SQL logical condition statement. For example, "column1 = ? AND column2 = ?"
                type: string
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              rows:
                type: array
                default: []
                items:
                  type: object
classmethod SetMetadata(namespace As %String, pDomainId As %Integer, pSourceId As %Integer) as %Status
      summary: |
        Registers metadata values for a given source
      tags: ["Sources"]
      parameters:
        - $ref: '#/parameters/domainParam'
        - name: source
          description: the source ID whose metadata needs updating
          in: path
          required: true
          type: integer
        - name: RequestBody
          description: JSON object with a list of query-specific arguments
          in: body
          schema:
            type: object
            properties:
              metadata:
                description: map of metadata field values to set for this source
                type: object
      responses:
        200:
          description: Successful response
          schema:
            type: object
            required:
              - updated
            properties:
              updated:
                type: boolean
                format: integer

Inherited Members

Inherited Methods

FeedbackOpens in a new tab