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 tohttps://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 toapplication/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 eithertext/plain
ortext/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.
- Metadata part. Must come first, and must have a
- 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:
|
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 |