Class Reference
IRIS for UNIX 2019.2
InterSystems: The power behind what matters   
Documentation  Search
  [ENSLIB] >  [%iKnow] >  [REST] >  [v1]
Private  Storage   

class %iKnow.REST.v1 extends Base, Utils

This class offers endpoints for accessing iKnow functionalities over REST.

The API is fully documented using the OpenAPI Specification (also known as Swagger). The description in YAML is available from the "/swagger" endpoint and can be loaded directly into swagger-ui 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
  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.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
1 85


Summary

Methods
%ClassIsLatestVersion %ClassName %DispatchClassMethod %DispatchGetModified
%DispatchGetProperty %DispatchMethod %DispatchSetModified %DispatchSetMultidimProperty
%DispatchSetProperty %ErrorHandler %Extends %GetParameter
%IsA %New %OriginalNamespace %PackageName
%SetModified AcceptsContentType AccessCheck AddSource
AddStringToBlacklist ClearBlacklist ConvertParameter CreateBlacklist
CreateDictionary CreateDictionaryItems CreateDictionaryItemsPOST CreateDictionaryTerms
CreateDomainAPI Decrypt DispatchMap DispatchRequest
DrawCSS3STYLE DrawHEAD DrawSTHEAD DrawSTTitle
DrawSTYLE DrawTitle DrawTitleSection DropBlacklist
DropDictionary DropDictionaryItem DropDictionaryTerm DropSource
Encrypt Error EscapeHTML EscapeURL
GetBlacklistDetails GetBlacklists GetCRCs GetCRCsByEntity
GetConfigurations GetDictionaries GetDictionaryDetails GetDictionaryItemDetails
GetDomainDetails GetDomains GetEntities GetEntityDetails
GetMatchesByItem GetMatchesBySource GetPathsByEntity GetRelatedEntities
GetSentenceDetails GetSentencesByEntity GetSimilarEntities GetSimilarSources
GetSourceDetails GetSources GetSourcesByCRC GetSourcesByEntity
Highlight HighlightSYS Http403 Http404
Http405 Http500 HyperEventCall HyperEventHead
Include Index InsertHiddenField InsertHiddenFields
IsPrivate Link Login MatchAll
MatchSource OnErrorSetup OnHTTPHeader OnHandleCorsRequest
OnHandleOptionsRequest OnLoginPage OnPage OnPageError
OnPostHTTP OnPostHyperEvent OnPreDispatch OnPreHTTP
OnPreHyperEvent OnSecurityTokenPage Page ParseFilter
ParseHighlight ParseList ParseStringArray QuoteJS
RemoveStringFromBlacklist ReportHttpStatusCode ResolveDomainId ResolveTarget
RewriteURL SearchIndex SetMetadata SetResponseHeaderIfEmpty
ShowError StartTimer StatusToJSON StatusToProxyObject
StopTimer SupportedVerbs ThrowError UnescapeHTML
UnescapeURL


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
              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


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.