Skip to content

How to use the API

Programmatic use

The Natural Language API is a cloud-based service with a REST interface. This means that the program must be able to access the Web and carry out an HTTP conversation with the API interface.
Whenever the program has to analyze or classify a document, it must request the most suitable API resource, similarly to what you do when you request the page of a site with a Web browser.

If you use one of the SDKs available on the developer portal, the details of the conversation are hidden, otherwise the program must use an HTTP client to request the API resources. In both cases what happens is the same: the program, via the—explicit or hidden—HTTP client, transmits a request to the API server.
The request contains the address of the resource of interest—its URL, or endpoint—and the text of the document to be analyzed or classified. For this type of request the POST method is used.

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

If the program uses an SDK, the interpretation of the result is simple because it involves examining the properties of an object. Otherwise it must be considered that the result is a JSON object that should be "de-serialized" in order to parse it.

In this manual you will find all the information on the format of the request and on the JSON objects that the API resources return, so you can easily create your own parser.

Authentication and authorization

Each API request must contain an authorization token. The bearer authentication mechanism is used, so the token must be obtained with an authentication operation and then specified as a header in each request.

The authentication operation is carried out by requesting—with a conversation identical to that described above—a special resource that is not strictly part of the API because it is shared by all the cloud services.

It's address is:

This resource must also be requested with the POST method and the body must be a JSON object like this:

  "username": "yourusername",
  "password": "yourpassword"

with yourusername and yourpassword replaced by the developer credentials obtained by registering on the developer portal.

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

application/json; charset=utf-8

The response is the token and is a plain text like this:


The application program must therefore "know" the credentials of the developer and obtain the authorization token through them.
If you use an SDK, the details of the authentication and authorization dialogue are hidden. Otherwise, when the program requests analysis or classification resources it must include the Authorization header in each request using this format:

Bearer token

with token replaced by the actual token.

As mentioned above, authorization tokens have a duration, they expire after a certain time.
If the application continues to make requests with an expired token it will get 401 Unautorized errors. In that case it must request a new token to replace the old one.

The next step

You're now ready to discover all the API capabilities.