Low-level use of the API

REST interface

The Studio LDA 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: Studio LDA API is "similar" to a Web site thet runs inside Studio, on 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

Overview

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

If you use one of the SDKs available on GitHub, the only thing you need to do is indicate your user credentials, the library functions will do the rest. If you want to create your own library or learn more, read on!

Any call to the Studio LDA API service must contain an execution key.

To get this key, your client software needs to request it to a Cloud API and requests must be authorized with an authorization token.

The authorization token must be requested to a separate Cloud API to which you connect using your developer credentials.

Authorization token

The authorization token is obtained by requesting this resource:

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

where yourusername and yourpassword must be replaced with your developer credentials.

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

application/json; charset=utf-8

The response is the authorization token.

Authorization tokens expire after a certain time, e.g. 24 hours. If your program continues to make requests to the Studio LDA API with an expired token it will get 401 Unauthorized error. In that case a new token must be requested to replace the old one.

Execution key

The execution key identifies the analysis 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, but you need it only for the needed to analyze a specific document.

Endpoints

The API endpoints are listed in the reference section of this manual.

Request headers

Once the program has the execution key, it can submit an analysis request to the Studio LDA API service.

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

Request body

The body of each request must be a UTF-8 encoded JSON object. In the reference section of this manual you will find all the details on the format of the object based on the type of resource.

HTTP status code

You will find the HTTP status codes listed and described in the reference section of this manual.