Edit

VDS gateway service REST API

Basic Conventions

Charset

UTF-8

HTTP response codes

Code	Description
200	OK. Normal response, the body contains {Response body} from the description for a given request.
500	Internal server error due to failure on gateway service. The response body contains a string with error details.
504	Gateway timed out. This can be caused by a queue broker or a failed model when a model is unable to send a response to gateway service. The response body contains a string with error details.

All other codes are kind of "Runtime Exception" and generated by other services.

Search AutoML models

List HyperModels

GET {GatewayURL}/listHyperModels[?update=true]

Returns a list of published models for a given AutoML service.

Request

Type: GET

The parameters are as follows:

Name	Description	Type	Default value	Required
update	System first re-reads the list of published models from S3, and then returns the updated list of models.	boolean	false	false

Response

Content-Type: application/json

Response body:

Field name	Description	Type
id	Model ID	long
hyperModelName	Model name	String
title	Model title	String
description	Model description	String
created	Upload to local storage timestamp	Timestamp
versions	Available model versions	Set of string

Example response

[
  {
    "id": 16,
    "hyperModelName": "matching-binary-classification",
    "title": "Matching Binary classification",
    "description": "Matching Binary Classification Only Works On Two Entrance",
    "created": 1535630411298,
    "versions": [
      "9.0.0.20-snapshot"
    ]
  },
  {
    "id": 1,
    "hyperModelName": "presentation-information-extraction",
    "title": "Presentation Information Extraction",
    "description": "Presentation Information Extraction",
    "created": 1535618607656,
    "versions": [
      "9.0.0.19",
      "9.0.0.20-snapshot",
      "9.1.0.5",
      "9.1.0.7"
    ]
  },
  {
    "id": 4,
    "hyperModelName": "presentation-company-classification-model",
    "title": "Presentation Company Classification",
    "description": "Presentation Company Classification",
    "created": 1535618607714,
    "versions": [
      "9.0.0.19",
      "9.0.0.20-snapshot",
      "9.1.0.5",
      "9.1.0.7"
    ]
  },
  {
    "id": 7,
    "hyperModelName": "generic-information-extraction",
    "title": "Generic Information Extraction",
    "description": "Generic Information Extraction using auto generated FE in categories",
    "created": 1535618607767,
    "versions": [
      "9.0.0.19",
      "9.0.0.20-snapshot",
      "9.1.0.5",
      "9.1.0.7"
    ]
  },
  {
    "id": 10,
    "hyperModelName": "generic-multi-class-classification",
    "title": "Generic Multi Class Classification",
    "description": "Generic Multi Class Classification",
    "created": 1535618607814,
    "versions": [
      "9.0.0.19",
      "9.0.0.20-snapshot",
      "9.1.0.5",
      "9.1.0.7"
    ]
  },
  {
    "id": 13,
    "hyperModelName": "generic-binary-classification",
    "title": "Generic Binary classification",
    "description": "Generic Binary Classification Only Works On Two Classes",
    "created": 1535618607860,
    "versions": [
      "8.5.5.1",
      "9.0.0.1",
      "9.0.0.11-snapshot",
      "9.0.0.11",
      "9.0.0.19",
      "9.0.0.20-snapshot",
      "9.1.0.5",
      "9.1.0.7"
    ]
  }
] 

Check Eval availability on model

GET {GatewayURL}/isEvalAvailable?name={ModelName}&docsNum={NumberOfDocs}&delta={Delta}

Check if model training is possible with a provided training set.

Request

Type: GET

The parameters are as follows:

Name	Description	Type	Required
name	Model code	String	true
docsNum	Number of documents in a training set	long	true
delta	Number of new documents (delta) in a training set	long	true

Response

Content-Type: text/plain

Response body:

{
    "available":<is available? true/false>,
    "hyperModelVersion":<model version>
}

Field name	Description	Type
available	Training availability	boolean
hyperModelVersion	Model version	string

Example response

{"available":true,"hyperModelVersion":"9.0.0.20-snapshot"}

Or:

{"available":false,"hyperModelVersion":null}

Get HyperModel details

GET {GatewayURL}/hyperModelDetails?name={ModelName}&version={ModelVersion}

Get model details.

Request

Type: GET

The parameters are as follows:

Name	Description	Type	Required
name	Model code	String	true
version	Model version	String	true

Response

Content-Type: text/plain

Response body:

{
  "mainHyperModel": {
    "code": ,
    "version": ,
    "autoMlSdkVersion": ,
    "title": ,
    "description": ,
    "type": ,
    "className": ,
    "minDocs": ,
    "minDelta": ,
    "capabilities": [
       
    ]
  },
  "artifacts": { }
}

Field name	Description	Type
code	Model code	String
version	Model version	String
autoMlSdkVersion	AutoML version	String
title	Model title	String
description	Model description	String
type	Model type: IE or CLASSIFICATION	String
className	Model Java class name with package	String
minDocs	Minimal number of documents for model training	long
minDelta	Minimal number of new documents (delta) for a model to re-train	long
capabilities	Model capabilities, for example, HPO	set<string>
artifacts	Map with keys—model artifact file name, value—MD5 checksum for that file	map<string, string>

Example response

{
  "mainHyperModel": {
    "code": "generic-information-extraction",
    "version": "9.1.0.7",
    "autoMlSdkVersion": "9.1.0.7",
    "title": "Generic Information Extraction",
    "description": "Generic Information Extraction using auto generated FE in categories",
    "type": "IE",
    "className": "com.workfusion.vds.nlp.hypermodel.ie.generic.GenericIeHypermodel",
    "minDocs": 10,
    "minDelta": 10,
    "capabilities": [
      "HPO"
    ]
  },
  "artifacts": {
    "vds-spring-boot-app.jar": "f1cf082242eb855e01aa570dc32c2e50"
  }
}

Deal with AutoML models

Start evaluation

POST {GatewayURL}/startEval

Request to start training with a given EGID.

Request

Type: POST

JSON format:

{
    "modelName" : ,
    "modelVersion" : ,
    "experimentGroupId" : ,
    "parameters" : {
        "answers" : "{escaped JSON }",
        "tableauDbJdbcUrl" : ,
        "tableauDbUser" : ,
        "tableauDbPassword" : 
  }
}

The parameters are as follows:

Name	Description	Validation	Type	Default Value	required
modelName	Model name.	Length: 1–70 First symbol: lowercase/upper case Latin letters. Other symbols: lowercase/uppercase Latin letters, numeric, '_' (underscore), '-' (dash).	String		true
modelVersion	Model version.	Length: 1–40 At least one numeric level version with a dot ('.') separator and an optional qualifier. Qualifier allows numeric, loqwecase Latin letters, '-' (dash) symbols.	String		true
experimentGroupId	EGID	Length: 1-90 Allows numeric, lowercase Latin letters, '-' (dash) symbols, '.' (dot) symbols, '_' (underscore) symbols.	String		true
parameters	Specific configuration for a given training. Contains answers description, HPO configurations, etc. HPO configuration example: hpo.timeLimit — HPO evaluation time limit (in seconds). hpo.fieldsInParallelI — HPO: maximum parallel (simultaneous) fields (sub-models). hpo.scoreFunction — Parameter that defines score function which is objective of HPO.		Map		true
parameters/answers	Model answers meta-information as escaped JSON. Information Extraction JSON format: answers=[ { "allowNA": false, "answerCode": "message", "answerType": "INFO_EXTRACTION", "subAnswers": [ { "allowNA": , "answerCode": , "answerType": , "subAnswers": [ ], "multiValue": , "constantable": , "required": , "properties": { } }, ... ], "multiValue": false, "constantable": false, "required": false, "properties": { } } ], Classification JSON format: [ { "answerCode": , "answerType": , "required": , "multiValue": , "constantable": , "allowNA": , "subAnswers": [], "properties": }, ... ]		Encoded JSON		true
parameters/tableauDbJdbcUrl	wfbi-db URL used to save training statistics in wfbi-service. Statistics are used to build a P/R chart in Control Tower.		boolean		false
parameters/tableauDbUser	wfbi-db user		boolean		false
parameters/tableauDbPassword	wfbi-db password		boolean		false

Response

Content-Type: application/json

Response body:

{
    "evalJobId": ,
    "modelVersion": ,
    "correlationId":
}

Field name	Description	Type
evalJobId	Always 0	long
modelVersion	Started training model version	String
correlationId	AutoML services correlation ID	String

Example response

{
  "evalJobId" : 0,
  "version" : "1.2.3",
  "correlationId" : "startEval/gjlsXdEPRmWal7aH1m271g"
}

Check evaluation status

GET {GatewayURL}/evalStatus?egid={ExperimentJobId}

Get evaluated training status.

Request

Type: GET

The parameters are as follows:

Name	Description	Validation	Type	Default value	Required
egid	Trained model EGID	Length: 1-90 Allow numeric, lower case latin later, - (dash) symbols, . (dot) symbols, _ (underscore) symbols.	String		true

Response

Content-Type: application/json

Response body:

{
    "evalStatus": ,
    "errorMessage": ,
    "results": {
        model training statistics result
        <egid>: {
            "tag": ,
            "extracted": ,
            "gold": ,
            "correct": ,
            "precision": ,
            "recall": ,
            "f1": ,
            "rpcAuc": ,
            "rpcOver80Auc": ,
            "rpcOver90Auc": ,
            "rocAuc": ,
            "mse":
        },
        ...
    }
}

Possible evalStatus:

• IN_PROGRESS: Evaluation is processed.
• TERMINATED: Evaluation was manually stopped by vds-services.
• COMPLETED: Evaluation successfully completed. Response may contain either results or errorMessage (in case, results are not available).
• FAILED: Evaluation job failed. errorMessage will contain failure details.
• ERROR: There is some retryable error during process check evalStatus on the vds-service side. errorMessage will contain error details.

Example response

{
 "evalStatus": "COMPLETED",
 "errorMessage": null,
 "results": {
   "1234567890": [
     {
       "tag": "No",
       "precision": 0.9291375497567447,
       "recall": 0.9882352941176471,
       "f1": 0.9577756592235942
     },
     {
       "tag": "Yes",
       "precision": 0.5,
       "recall": 0.4,
       "f1": 0.4444444444444445
     }
   ]
 }
}

Error response with an error message

{
    "evalStatus": "ERROR",
    "errorMessage": "Can't read status file /opt/workfusion/vds-data/eval/wfuser/4324/process/process.status : /opt/workfusion/vds-data/eval/wfuser/4324/process/process.status",
    "results": null
}

Stop Eval job

POST {GatewayURL}/stopEval

Request to force stop model training.

Request

Type: POST

JSON format:

{
    "experimentGroupId":
}

The parameters are as follows:

Name	Description	Validation	Type	Required
experimentGroupId	Trained model EGID	Length: 1–90 characters. Allow numeric, lowercase latin letters, - (dash) symbols, . (dot) symbols, _ (underscore) symbols.	String	true

Response

Always without body.

HTTP 200

Extract v1

POST {GatewayURL}/extract

Send request to process model execution.

Request

Type: POST

JSON format:

{
  "modelId" : ,
  "modelVersion" : ,
  "experimentGroup" : ,
  "experimentId" : ,
  "document" : ,
  "contextInfo": ,
  "parameters": {
    
  }
}

The parameters are as follows:

Name	Description	Validation	Type	Required
modelId	Executed model name.	Length: 1–70 characters. First character: lower- or uppercase Latin letters. Other characters: lower- or uppercase Latin letters, numeric, '_' (underscore), '-' (dash).	String	true
modelVersion	Executed model version.	Length: 1–40 characters. At least one numeric level version with a dot ('.') separator and an optional qualifier. Qualifiers allow numeric, lowercase Latin letters, '-' (dash) symbols.	String	true
experimentGroup	EGID.	Length: 1–90 characters. Allows numeric, lowercase Latin letters, '-' (dash) symbols, '.' (dot) symbols, '_' (underscore) symbols.	String	true
experimentId	Experiment ID. Used for backward compatibility. For v9.1 send combined-results.	Length: ≥1 character.	String	true
document	Escaped JSON: document content wrapped with JSON. { "textParts" : ["{Document Content}"] }		String	true
contextInfo			String	false
parameters	Execution parameters. modelResponseTimeout — model response timeout in seconds. modelRetryCount.		Map	fasle

Response

Content-Type: text/plain

Response body: Sent as is from model execution.

Example response: Information Extraction

{
  "metaInfo": {
    "model": {
      "coreVersion": "9.0.0"
    }
  },
  "finalScore": 0.7259317496761855,
  "sumScore": 11.614907994818967,
  "tagsCounter": 16.0,
  "taggedText": "....tagget document content...",
  "estimatedAccuracy": 1.0,
  "tags": [
    {
      "score": 0.7269902669327943,
      "end": 47,
      "tag": "invoice_number",
      "text": "925812821",
      "estimatedAccuracy": 1.0,
      "begin": 38
    },
    {
      "score": 0.730115596106869,
      "end": 67,
      "tag": "vendor_name",
      "text": "Workfusion",
      "estimatedAccuracy": 1.0,
      "begin": 57
    },
    {
      "score": 0.7295706389306622,
      "tabnumber": "0",
      "end": 481,
      "tag": "order_service",
      "text": "Social Media Marketing",
      "estimatedAccuracy": 1.0,
      "begin": 459
    },
    {
      "score": 0.7307832408624205,
      "tabnumber": "0",
      "end": 531,
      "tag": "order_description",
      "text": "Facebook and Twitter marketing campaign",
      "estimatedAccuracy": 1.0,
      "begin": 492
    },
    {
      "score": 0.7303006087314289,
      "tabnumber": "0",
      "end": 571,
      "tag": "order_total",
      "text": "6.00",
      "estimatedAccuracy": 1.0,
      "begin": 566
    }
  ],
  "group": "invoice_number|order_description|order_service|order_total|vendor_name"
}

Example response: Classification

{
  "score": 0.6996566987216492,
  "metaInfo": {
    "model": {
      "coreVersion": "9.1.0.5"
    }
  },
  "category": "Microsoft",
  "estimatedAccuracy": 1.0
}

Extract v2

POST {GatewayURL}/extract-v2

Send request to process model execution.

The same as extract v1 structured response with correlationId.

{
  "result": extract result (see extract-v1 result) as string,
  "correlationId": automl services correlationId
}

Request

Type: POST

JSON format:

{
  "modelId" : ,
  "modelVersion" : ,
  "experimentGroup" : ,
  "experimentId" : ,
  "document" : ,
  "contextInfo": ,
  "parameters": {
    
  }
}

The parameters are as follows:

Name	Description	Validation	Type	Required
modelId	Executed model name.	Length: 1–70 characters. First character: lower- or uppercase Latin letters. Other characters: lower- or uppercase Latin letters, numeric, '_' (underscore), '-' (dash).	String	true
modelVersion	Executed model version.	Length: 1-40 characters. At least one numeric level version with dot ('.') separator and optional qualifier. Qualifier allow numeric, lowercase Latin later, '-' (dash) symbols.	String	true
experimentGroup	EGID.	Length: 1-90 characters. Allow numeric, lowercase latin later, '-' (dash) symbols, '.' (dot) symbols, '_' (underscore) symbols.	String	true
experimentId	Experiment ID, used for backward compatibility. For 9.1 send combined-results.	Length: ≥1 characters.	String	true
document	Escaped JSON: document content wrapped with JSON. { "textParts" : ["{Document Content}"] }		String	true
contextInfo				false
parameters	Execution parameters. modelResponseTimeout — model response timeout in seconds. modelRetryCount.		Map	false

Response

Content-Type: application/json

Response body:

{
    "result": ,
    "correlationId":
}

Example response: Information Extraction

{
    "result": "{\"finalScore\":0.7089883111865313,\"metaInfo\":{\"model\":{\"coreVersion\":\"9.1.0.7\"}},\"sumScore\":11.3438129789845,\"tagsCounter\":16.0,\"taggedText\":\"....escaped tagget document content...\",\"tags\":[{\"score\":0.7299440303344772,\"end\":29,\"tag\":\"invoice_number\",\"text\":\"2017716471\",\"estimatedAccuracy\":1.0,\"begin\":19},{\"score\":0.729544460617881,\"end\":49,\"tag\":\"vendor_name\",\"text\":\"Workfusion\",\"estimatedAccuracy\":1.0,\"begin\":39},{\"score\":0.7042747485809453,\"end\":103,\"tag\":\"vendor_address\",\"text\":\"48 Wall Street, 7th floor NY 10005, USA\",\"estimatedAccuracy\":1.0,\"begin\":57},{\"score\":0.729553212733637,\"end\":127,\"tag\":\"vendor_phone\",\"text\":\"+1 646.453.7974\",\"estimatedAccuracy\":1.0,\"begin\":112},{\"score\":0.7295532127336369,\"end\":150,\"tag\":\"vendor_email\",\"text\":\"workfusion.com\",\"estimatedAccuracy\":1.0,\"begin\":136},{\"score\":0.7279212423514653,\"end\":218,\"tag\":\"client_name\",\"text\":\"John Doe\",\"estimatedAccuracy\":1.0,\"begin\":210},{\"score\":0.8280361705781263,\"end\":279,\"tag\":\"client_address\",\"text\":\"ONE INFINITE LOOP CUPERTINO, CA, 95014, USA\",\"estimatedAccuracy\":1.0,\"begin\":236},{\"score\":0.7290248082888097,\"end\":315,\"tag\":\"client_email\",\"text\":\"john.doe@example.com\",\"estimatedAccuracy\":1.0,\"begin\":295},{\"score\":0.7306786830670211,\"end\":348,\"tag\":\"invoice_date\",\"text\":\"September 14, 2017\",\"estimatedAccuracy\":1.0,\"begin\":330},{\"score\":0.41744306611758286,\"tabnumber\":\"0\",\"end\":466,\"tag\":\"order_service\",\"text\":\"Social Media Marketing\",\"estimatedAccuracy\":1.0,\"begin\":444},{\"score\":0.6451484680861542,\"tabnumber\":\"0\",\"end\":516,\"tag\":\"order_description\",\"text\":\"Facebook and Twitter marketing campaign\",\"estimatedAccuracy\":1.0,\"begin\":477},{\"score\":0.7420578802071846,\"tabnumber\":\"0\",\"end\":558,\"tag\":\"order_total\",\"text\":\"75.00\",\"estimatedAccuracy\":1.0,\"begin\":553},{\"score\":0.7289033559851236,\"end\":615,\"tag\":\"invoice_taxes\",\"text\":\"20%\",\"estimatedAccuracy\":1.0,\"begin\":612},{\"score\":0.7258799693208309,\"end\":632,\"tag\":\"invoice_taxes_amount\",\"text\":\"15.00\",\"estimatedAccuracy\":1.0,\"begin\":627},{\"score\":0.7168188809850041,\"end\":667,\"tag\":\"invoice_currency\",\"text\":\"$90.00\",\"estimatedAccuracy\":0.0,\"begin\":661},{\"score\":0.729030788996621,\"end\":667,\"tag\":\"invoice_amount\",\"text\":\"90.00\",\"estimatedAccuracy\":1.0,\"begin\":662}],\"group\":\"client_address|client_email|client_name|invoice_amount|invoice_currency|invoice_date|invoice_number|invoice_taxes|invoice_taxes_amount|order_description|order_service|order_total|vendor_address|vendor_email|vendor_name|vendor_phone\"}",
    "correlationId": "extract-v2/uheQrhVKSiO7SGc54XxLtw"
}

Example response: Classification

{
  "result": "{\"score\":0.6996566987216492,\"metaInfo\":{\"model\":{\"coreVersion\":\"9.1.0.5\"}},\"category\":\"Microsoft\",\"estimatedAccuracy\":1.0}",
  "correlationId": "extract-v2/Pl0j0QyoQW-D0dgLkjP8iw"
}