Skip to content

Synchronous workflows

NL Flow API exposes one analysis resource to use a workflow published in synchronous mode.
The returned resource contains the output of the workflow for a given input and the response time experienced by the client program amounts to the workflow's processing time plus the transmit & receive network overhead.
Because the client program hangs until it receives the workflow's output, this mode is called synchronous.

Analysis resource endpoint

The endpoint of the analysis resource is:

https://host/api/v1/runtime/workflow/workflowId/action/analyze

where you have to replace:

  • host with the host name or IP address of the NL Flow runtime.
  • workflowId with the workflow ID.

To get the endpoint you can access the NL Flow application and:

  1. Open the workflow in the Workflows view of the dashboard.
  2. Display identifying information.
  3. Copy the value of the Sync field under Document analysis endpoint.

To get a verbose output in case of errors add this query string parameter to the URL:

verboseErrorOutput=true

HTTP verb

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

Request headers

In every 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 the workflow.
Learn more about API keys in the article dedicated to this topic inside the NL Flow manual.

An additional X-Correlation-Id header is optional and used for troubleshooting purposes.
Its value can be any string and must be unique for each request and can be mentioned when asking for support in case of unexpected errors. Support personnel can then track API calls based on this value when examining the NL Flow API logs.

Request body

The body of document analysis requests must be an UTF-8 encoded JSON object. It is the input to the workflow and represents the document to analyze.
The object must contain all the keys that the workflow needs to use. They can be the keys expected by the first block of each flow: in the NL Flow application documentation you can find the description of the keys expected by the blocks, for example model blocks and processor blocks. Alternatively, they can be the keys defined in the workflow's input format.

Response

The response body the UTF-8 encoded JSON object which is the output of the workflow.