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:

In order to build a custom classifier you will need to create a project passing a dataset. This can be any collection of customer interactions or any other type of text.
The algorithm will automatically extract intents and features that that you can group in tags inside your project section.
Once the project is successfully created, the lang.ai API can be used in real time to analyze and save new documents (e.g. support tickets, chatbot messages, etc.) in your project.

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 an 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:

Create a POST request to https://company.lang.ai/api/v1/project.
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.
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>.
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,metadata_column,another_metadata
First text,2018-04-25,my metadata,lorem 
Second text,2018-04-25,another metadata,ipsum
--{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. You may include extra CSV columns to be used as metadata.

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

List projects

Returns the list of projects.

HTTP Request

GET https://company.lang.ai/api/v1/projects

Request Body

The request doesn't require a JSON body.

Response Body

The response returns a list of zero, one or more projects. Each project contains the following fields:

[
  {
    "status": "Processing",
    "id": "sWP2ll1v16lLdMxM",
    "name": "My first project",
    "createdAt": "2021-03-22T13:54:55Z"  
  },
  {
    "status": "Completed",
    "id": "l3wNMwIXM1S046Sy",
    "name": "My second project",
    "createdAt": "2021-03-23T13:54:55Z"  
  }
]

Field	Type	Description
status	string	The project status: Errored, Processing, Completed.
id	string	The ID of the project.
name	string	The name of the project.
createdAt	string	The creation date of the project.

List project tags

Returns the list of the project's tags.

HTTP Request

GET https://company.lang.ai/api/v1/projects/:projectId

Request Body

The request doesn't require a JSON body.

Response Body

The response returns the project information as well as the list of zero, one or more tags.


{
  "status": "Completed",
  "id": "l3wNMwIXM1S046Sy",
  "name": "My second project",
  "createdAt": "2021-03-23T13:54:55Z", 
  "tags": [{
    "id": "tqGMbCpTBZOJaram",
    "name": "My first tag",
    "createdAt": "2021-04-21T12:40:50.892265Z",
    "updatedAt": "2021-04-25T11:35:43.512464Z",
    "isDraft": false
  }]
}

Field	Type	Description
status	string	The project status: Errored, Processing, Completed.
id	string	The ID of the project.
name	string	The name of the project.
createdAt	string	The creation date of the project.
tags	tag[]	An array of tags.
tag[].id	string	The ID of the tag.
tag[].name	string	The name of the tag.
tag[].createdAt	string	The creation date of the tag.
tag[].updatedAt	string	The last update date of the tag.
tag[].isDraft	boolean	Whether or not the tag is draft. Learn more.

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.

{
  "tags": [
    {
        "id": "tqGMbCpTBZOJaram",
        "name": "My first tag"
    }
  ],
  "intents": [
    {
        "name": "intent",
        "features": ["feature", "feature>feature"]
    }
  ]
}

Field	Type	Description
intents	intent[]	An array of intents.
intent[].name	string	The name of the intent.
intent[].features	string[]	An array of features. The sign “>” indicates a second-level feature.
tags	tag[]	An array of tags.
tag[].id	string	The ID of the tag.
tag[].name	string	The name of the tag.

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", "another_key": "value"}, // Optional
  "date": "2019-20-12", // Optional
  "id": "The ID of the document to save." // 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.
id	false	-	string	ID of the document to save. If a document with the same ID already exists, it will be overwritten.

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": [
    {
        "id": "tqGMbCpTBZOJaram",
        "name": "My first tag"
    }
  ],
  "intents": [
    {
        "name": "intent",
        "features": ["feature", "feature>feature"]
    }
  ]
}

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