Skip to content

Developer how-to

REST interface

The expert.ai Edge NL API is a software service with a REST interface that accepts and returns JSON objects.

Whenever a client program has to analyze a text, it must request an API resource. This is similar to what you do when you request the page of a site with a Web browser, but the Edge NL API can be local to your computer.

The request contains the API resource path—its URL, or endpoint—and the text of the document to be analyzed, classified and extracted. For this type of request the POST method is used.

Presented with this request, the service responds synchronously (after an amount of time depending on the type of processing requested and the complexity/length of the text) with the processing results.

In this manual you will find all the information about the format of the request and the JSON objects that the API resources return.

Authentication and authorization

The service can be used by any developer registered on the expert.ai developer portal

Any call to the Edge NL API service must contain an authorization token and an execution key. The Edge NL API service can run on a computer without an Internet connection, but the authorization token and the execution key the client program needs to specify must be obtained from the Cloud.

Authorization token

The authorization token is obtained by authenticating to the expert.ai developer portal. Programmatically, this is achieved by requesting this resource from expert.ai Cloud services:

https://developer.expert.ai/oauth2/token

The resource must be requested with the POST method and the body of the request must be a JSON object like this:

{
  "username": "yourusername",
  "password": "yourpassword"
}

with yourusername and yourpassword replaced by the developer credentials.

The Content-Type header of the request must be set to:

application/json; charset=utf-8

The response is the authorization token, which is a plain text like this:

eyJraWQiOiJlZXEzSnB5WWxzeTJ4eTFuQnd4eDVZaEo3YWEwWWdMXC9DaUYyalJGMkxScz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxZnR2YTQ5MjJ2MWlibzQ3M2JxZDRwM3VjcyIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXBpXC9jb250ZXh0cy5yZWFkIiwiYXV0aF90aW1lIjoxNTkzNzc5NTc4LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAuZXUtd2VzdC0xLmFtYXpvbmF3cy5jb21cL2V1LXdlc3QtMV9BVUhnUTA4Q0IiLCJleHAiOjE1OTM3ODMxNzgsImlhdCI6MTU5Mzc3OTU3OCwidmVyc2lvbiI6MiwianRpIjoiM2EwODA0MDEtZGVmMC00NDNmLWI2OWItNGJhNTc5ZGJhOWY1IiwiY2xpZW50X2lkIjoiMWZ0dmE0OTIydjFpYm80NzNicWQ0cDN1Y3MifQ.LLjeg4su7X-ftlC5ReXoCPkQe-Mw2EZmBbG9tex_NZOaDY4tnBJZEgneboI0CcJHXZcZZJZ8U19dG9OcClEpEEytRJFWZ3hGXhSMXYpScn21oSmiyNwNi2f3Tv9t-nRv3ksmlsx7IZZoxTnc0ECXF10bdR55OMF1Z7DZ3k2fyWF2ClD8hAwJQEYKAZq4UfMVDjbYSOA7Hm7SChc3mx5XmLzPFtVSJ4MONjDBZiM5bOUj22dqWnf90-8i9mY5T40HI2JhD99tQI8HCXQWpNxax_dH_5W9AC3MHmNZA_d6xBEna8H8QbjpQdNyhvxN1M1JsJaEvRP7zhRuCqJmhj2sLA

Authorization tokens will expire after a certain time. If the application continues to make requests with an expired token it will get 401 Unauthorized errors from the Edge NL API service. In that case a new token must be requested to replace the old one.

Execution key

While the authorization token identifies the user, the execution key identifies the operation.
It is obtained by requesting this Cloud resource:

https://edgeapi.expert.ai/edge/key/fingerprint

with the GET method, setting the Authorization header like this:

Bearer token

replacing token with the authorization token.
The fingerprint part of the endpoint is the MD5 hash of the text to analyze. So, for example, if the text you want to analyze is:

This is my text

the endpoint will be the following:

https://edgeapi.expert.ai/edge/key/088b19be96ab393523e1553cf8e871e4

The resource output is a JSON object like this:

{
    "key": { "UJ6-7NJJ-IS5F-MNSW-UVEF-W621" }
}

Like the authorization token, the execution key also expires after a certain amount of time.

Request headers

Once the application program has the authorization token and the execution key, it can submit an analysis request to the Edge NL API service.

The authorization token and the execution key must be included in the request's headers like this:

POST /api/analyze HTTP/1.1
Host: 127.0.0.1
Content-Type: application/json
execution-key: UJ6-7NJJ-IS5F-MNSW-UVEF-W621
Authorization: Bearer eyJraWQiOiJlZXEzSnB5WWxzeTJ4eTFuQnd4eDVZaEo3YWEwWWdMXC9DaUYyalJGMkxScz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxZnR2YTQ5MjJ2MWlibzQ3M2JxZDRwM3VjcyIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXBpXC9jb250ZXh0cy5yZWFkIiwiYXV0aF90aW1lIjoxNTkzNzc5NTc4LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAuZXUtd2VzdC0xLmFtYXpvbmF3cy5jb21cL2V1LXdlc3QtMV9BVUhnUTA4Q0IiLCJleHAiOjE1OTM3ODMxNzgsImlhdCI6MTU5Mzc3OTU3OCwidmVyc2lvbiI6MiwianRpIjoiM2EwODA0MDEtZGVmMC00NDNmLWI2OWItNGJhNTc5ZGJhOWY1IiwiY2xpZW50X2lkIjoiMWZ0dmE0OTIydjFpYm80NzNicWQ0cDN1Y3MifQ.LLjeg4su7X-ftlC5ReXoCPkQe-Mw2EZmBbG9tex_NZOaDY4tnBJZEgneboI0CcJHXZcZZJZ8U19dG9OcClEpEEytRJFWZ3hGXhSMXYpScn21oSmiyNwNi2f3Tv9t-nRv3ksmlsx7IZZoxTnc0ECXF10bdR55OMF1Z7DZ3k2fyWF2ClD8hAwJQEYKAZq4UfMVDjbYSOA7Hm7SChc3mx5XmLzPFtVSJ4MONjDBZiM5bOUj22dqWnf90-8i9mY5T40HI2JhD99tQI8HCXQWpNxax_dH_5W9AC3MHmNZA_d6xBEna8H8QbjpQdNyhvxN1M1JsJaEvRP7zhRuCqJmhj2sLA

expert.ai clients

If you use one of the client packages available on GitHub you don't have to worry about getting the authorization token and the execution key, because the client gets them automatically. The only thing you need to do is to provide the client program with the credentials of the registered developer, for example by setting appropriate environment variables.