NAV Navbar

Workflow

Lang.ai algorithm adapts to any language, industry or business case given the adequate training data. The typical workflow for using lang.ai API is the following:

The API

The API is organized around REST. It has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors, although the API libraries convert responses to appropriate language-specific objects.

The service is available at "https://company.lang.ai/api/v1". Replace the example domain with the one you are using in your Lang.ai instance.

Authentication

curl https://company.lang.ai/api/v1/analyze \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST -d '{"text": "The Text", "projectId": "YOUR_PROJECT_ID"}'

Authenticate your account when using the API by including your secret API token in every request. You can create a new API token from the Settings section in your Lang.ai instance. Do not share your secret API tokens in publicly accessible areas such GitHub, client-side code, and so forth.

Keep in mind that generating a new token will invalidate the previously issued ones.

Every request must be authenticated with the your API token.

Rate Limit

To avoid abuse and ensure that the system remains online for every user, every API request will need to provide valid credentials and the requests can be rate limited if they exceed the limitations.

Create projects

This API allows you to create a project by performing a single, multipart request containing both project's metadata and the contents of a dataset.

To use this multipart upload:

  1. Create a POST request to https://company.lang.ai/api/v1/project.
  2. Create the body of the request. Format the body according to the multipart/related content type RFC 2387, which contains two parts:
    • Metadata part. Must come first, and must have a Content-Type header set to application/json; charset=UTF-8. Add the classifier's metadata to this part in JSON format. See the details below.
    • Media part. Must come second, and must have a Content-Type header, which must have either text/plain or text/csv type. Add the file's data to this part. Identify each part with a boundary string, preceded by two hyphens. In addition, add two hyphens after the final boundary string.
  3. Add the following HTTP headers:
    • Content-Type: multipart/related and include the boundary string to identify each part as a parameter (e.g.: multipart/related; boundary=foo).
    • Authorization: Bearer <your-api-token>.
  4. Send the request. Upon success, you'll get a JSON with a single key id, containing the newly created project's id.

Please check our Python implementation example that can be used as a starting point.

HTTP Request

POST https://company.lang.ai/api/v1/project

Request Body (multipart/related)

# Boundary string should be replaced
b'--{boundary_string}
Content-Type: application/json; charset=UTF-8
{
	"name": "My test project",
	"csvOptions": {"textColumn": "csv_text_column", "dateColumn": "csv_date_column"},
	"team_ids": ["team_id_one", "team_id_two"]
}
--{boundary_string}
Content-Type: text/csv
csv_text_column,csv_date_column
First text,2018-04-25
Second text,2018-04-25
--{boundary_string}--
'

# Relevant headers
{
	"Content-Type": "multipart/related; boundary={boundary_string}",
	"Authorization": "Bearer API_TOKEN",
	"Content-Length": "392"
}
Parameter Required Type Description
metadata.name true string The name of the project.
metadata.csvOptions true object Must be an object with two keys:

textColumn – The name of the column from the CSV file containing each document's text.

dateColumn – Optional: the name of the column from the CSV file that contains the document's date.

metadata.team_ids true string[] The list of team id's that will have access to the project.
media true file The data from the file to be uploaded.

Response Body

The response returns the id of the project that is being created.

Field Type Description
id string The id of the project.
{ "id": "project_id" } 

Analyze documents

Returns the classification for a given document and the specified project.

HTTP Request

POST https://company.lang.ai/api/v1/analyze

Request Body

{
  "text": "The text to be analyzed",
  "projectId": "Your project id"
}
Parameter Required Type Description
text true string The text to be classified.
projectId true string The project to be used to classify the text.

Response Body

The response returns a list of zero, one or more tags and intents. Each intent contains the following fields:

Field Type Description
name string The name of the intent.
features string[] The list of features. The sign “>” indicates a second-level feature.
{
  "tags": ["Tag 1", "Tag 2"]
  "intents": [
    {
        "name": "intent",
        "features": ["feature", "feature>feature"],
    }
  ]
}

Save documents

Saves a given document into the specified project. It supports passing metadata that can be later used in the project's Dashboard. New metadata values passed via API will be available to use in the project's setup section.

HTTP Request

POST https://company.lang.ai/api/v1/documents

Request Body

{
  "text": "The text to be analyzed",
  "projectId": "Your project id",
  "metadata": {"key": "value"}, // Optional
  "date": "2019-20-12" // Optional
}
Parameter Required Default Type Description
text true - string The text to be classified.
projectId true - string The project to be used to classify the text.
metadata false - object The metadata information of the document.
date false now string The date of the document. It supports valid IS0 8601 dates. If not passed, the request time is used.

Response Body

The request returns a 201 HTTP code when the document is saved successfully.

Errors

If the request succeeded, the response status will be 200 OK. Otherwise the response status will be 4xx or 5xx as described in the following table:

Error Code Meaning
400 Bad request / Missing fields
401 Unauthorized
404 Project not found
429 Too many requests / Rate limited
500 Internal server error