Platform NL Flow API

Introduction

The Platform NL Flow API allows you to use Platform workflows programmatically.

The NL Flow API is a RESTful API whose resources correspond to published workflows.

Requirements

A workflow can be accessed through the REST API if it has been published and associated to a API key.

Document analysis

Request this resource to analyze a document with the workflow.

Endpoint

The API endpoint for document analysis is:

https://{{HOST}}/api/v1/workflow/{{WORKFLOW ID}}/action/analyze

where you have to replace:

{{HOST}} with the host name or IP address of the Platform workflow runtime.
{{WORKFLOW ID}} with the workflow ID.

To get the actual endpoint, open the workflow settings in the NL Flow Web application and select the Information tab.

HTTP verb

The document analysis resource must be requested with the POST verb.

Request headers

In every API request you must set the following headers:

Content-type: application/json; charset=utf-8
X-API-KEY: {{API KEY}}

where you have to replace {{API KEY}} with the API key associated with your workflow.

Warning

You have to take note of the API key when you generate it, because it's not possible to retrieve it afterwards, even if there's always the possibility to re-generate it.

Request body

The body of document analysis requests must be an UTF-8 encoded JSON object.
The structure of the object varies based on the first block of the workflow.
If the first block is a ML model, use this structure:

{
    "text": "{{TEXT}}"
}

where {{TEXT}} must be replaced with the plain text to process.
If the first block is a symbolic model that is not configured to accept a sectioned text, use the structure above, otherwise use the following:

{
    "text": "{{TEXT}}"
    "sections": {{SECTIONS}}
}

where {{TEXT}} must be replaced with the plain text to process and {{SECTIONS}} must be specified to define the boundaries of text sections. sections is an array of objects with these properties:

name (string): name of the section
start (integer): zero-based position of the first character in the section
end (integer): zero-based position of the first character after the section

for example:

"sections": [
    {
        "name": "TITLE",
        "start": 0,
        "end": 61
    },
    {
        "name": "BODY",
        "start": 62,
        "end": 2407
    }
]

If the first block of the workflow is the Tika Converter or the Extract Converter processor, use this structure:

{
    "path": "{{FILE PATH}}",
    "base64": "{{BASE64}}"
}

where {{FILE PATH}} must be replaced with the name of the file to process—or its path—and {{BASE64}} with the Base64 encoding of the file.

Note

The value of path is only indicative and it's not used to retrieve the file: the file corresponds to the value of the base64 key.

If the first block is the URL Converter processor, use this structure:

{
    "url": "{{URL}}"
}

where {{URL}} must be replaced with the URL of the page to process. Note that in this case NL Flow API must have access to the URL because it needs to retrieve the corresponding document.

Request options

In the case of a workflow starting with a thesaurus model, you can add an option to the request to obtain detailed information about extracted concepts. The request JSON must have this structure:

{
    "text": "{{TEXT}}",
    "options": {
        "custom": {
            "normalizeToConceptId": true
        }
    }
}

Read the article in the manual of the NL Flow application to have more information about this extra output.

Response

The structure of the response reflects the inner working and the layout of the workflow.
The format of the response body, therefore, depends on how the workflow is made and what it does: typically it is a JSON object containing the results of the process in terms of categories and/or extractions, but, in fact, it can be something very different in the case of JavaScript post-processing or custom-type models.
Test the workflow in the NL Flow Web application to examine the output and so be able to parse API responses in your program.

The output of your workflow, except when a test block is present, is that of the last block of the flow.
Learn more about the output of the different block types in the reference documentation.
In the case of the presence of the test block within the workflow, the output is always that of that block, regardless of which is the last block of the flow.

Workflow status

Request this resource to know about the status of a workflow.

API endpoint

The API endpoint for workflow status is:

Workflow status:

https://{{HOST}}/api/v1/wokflow/{{WORKFLOW ID}}/action/status

where you have to replace:

{{HOST}} with the host name or IP address of the Platform workflow runtime.
{{WORKFLOW ID}} with the workflow ID.

To get the actual endpoint, open the workflow settings in the NL Flow Web application and select the Information tab.

HTTP verb

The workflow status resource must be requested with the GET verb.

Request headers

In every API request you must set this header:

X-API-KEY: {{API KEY}}

where you have to replace {{API KEY}} with the API key associated with your workflow.

Response

The answer is a JSON object like this:

{
    "desiredStatus": "PUBLISHED",
    "actualStatus": "ORANGE",
    "details": {
        "stream": {
            "id": "benthos",
            "desired": 1,
            "actual": 1,
            "status": "GREEN"
        },
        "services": [
            {
                "id": "cogito-1-0--9ccf18ea",
                "desired": 1,
                "actual": 0,
                "status": "RED"
            }
        ]
    }
}

Its properties are:

desiredStatus: target workflow status of the workflow, e.g. PUBLISHED
actualStatus: current workflow status with respect to the color-code used in the Workflow Web application, namely:
- GREEN: workflow is fully published and usable
- YELLOW: workflow is partially published, but already usable: instances of multi-instance blocks have not been activated yet
- ORANGE: workflow is being published, some necessary parts are not active, so the workflow is not usable
details: details on the publication status of the workflow components. Contains:
- stream: information on the data stream, i.e. the service that deals with the passage of data from one block to another. Its properties are:
  - id: data stream ID
  - desired: number of target instances
  - actual: number of currently active instances
  - status current status of the service with respect to the color-code used in the Workflow Web application, namely:
    - GREEN: all target instances are active
    - ORANGE: some instances are active, some other are not active yet
    - RED: no active instance
- services: information about the services corresponding to the workflow blocks. It is an array, each item of which corresponds to a service and has these properties:
  - id: service ID
  - desired: number of target instances
  - actual: number of currently active instances
  - actual current status of the service with respect to the color-code used in the Workflow Web application, namely:
    - GREEN: all target instances are active
    - ORANGE: some instances are active, some other are not active yet
    - RED: no active instance

Test the API

To test the API using Postman:

Go to the test page of the Workflow application.
Download the sample collection.
Import the collection in Postman.
Inside the collection, open the Analyze request and set the X-API-KEY header to the API key associated with the workflow.
Save the request.
Set the request body.
Select Send to call the API.