NAV Navbar
Logo
cURL

FPT.AI API

Introduction

FPT.AI is a conversational platform that allows developers to add a natural language interface to any app or any device. Common applications include:

There are two main components:

FPT.AI is available as a set of open APIs and SaaS products using latest cloud technologies. We offer a free tier for individual developers and comprehensive service packages for enterprise

Tutorial: Fresh food app

Creating application

Suppose you are a programmer and you want to earn extra income by selling fresh, organic foods from your hometown. Due to busy work, you are thinking of using chatbots for receiving orders.

After a week, you have programmed the application to connect with Facebook Messenger, now you need a natural language processing service and you’d like to try FPT.AI for this purpose.

You go to https://developers.fpt.ai to register an account. After receiving the notification email, you click the confirmation link in the email to activate the account.

After logging in to developers.fpt.ai, you start creating the app:

Create application

Create application

After creating the app, you go into the details of the app to start creating train data

Application detail

Creating Intents

To be able to train, you need to create at least 2 intents (as in the notice message).

Create new intent

Create new intent

Create two intents as below:

Create new intent

Creating Entities

Create new entity type

Create new entity type

Create two entity types like this:

Create new entity type

Creating training samples (utterances)

Create new sample

Create new sample

Mark named entities:

Create new sample

Create new sample

Create new sample

Add a few samples to the intent ‘product_info’:

Create new sample

Add some samples for intent ‘purchase’:

Create new sample

Start training

After completing training samples, go back to the application detail interface:

Start training

Testing

After the training is completed (usually after a few minutes), refresh the page and use the test function:

Create new sample

Conclusion

So now you know how to use the interface of FPT.AI to create an application, to create intents/entities, to create training samples and to test the recognition.

Next, you can use the APIs listed below to do all of this programmatically (except for creating the application - you still have to create application manually to get the API token).

Authentication

Every API request sent to FPT.AI must have an Authorization HTTP header with the token of application.

Authorization: Bearer your_application_token

Example request

curl -X GET \
  https://api.fpt.ai/v1/intents \
  -H 'Authorization: Bearer your_application_token'

Intent

List

Gets the list of all available intents for the application.

Example request

curl -X GET \
  https://api.fpt.ai/v1/intents \
  -H 'Authorization: Bearer your_application_token'

Example response

{
  "intents": [
    {
      "label": "Goodbye",
      "description": "bye",
      "intent_code": "93e45bfb388a42ebd0f416825e3dd2d5",
      "created_time": "170508034149",
      "application_code": "0453d39964125a62948f01edc2721ed9"
    },
    {
      "label": "Hello",
      "description": "Hello",
      "intent_code": "08f458c4fc51c21e6bb3b5f7f0c2ba14",
      "created_time": "170508034137",
      "application_code": "0453d39964125a62948f01edc2721ed9"
    }
  ]
}

Request

GET https://api.fpt.ai/v1/intents

Parameters

Parameter Required Description
n/a n/a n/a

Response

Returns a list of available intents for the application.

Create

Creates a new intent with the given parameters.

Example request

curl -X POST \
  https://api.fpt.ai/v1/intents \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
  "label": "go_swimming",
  "description": "Go Swimming"
}'

Example response

{
  "label": "go_swimming",
  "description": "Go Swimming",
  "intent_code": "576634c1860b681ab49412726bc27cda",
  "created_time": "170508041631",
  "application_code": "0453d39964125a62948f01edc2721ed9"
}

Request

POST https://api.fpt.ai/v1/intents

Parameters

Parameter Required Description
label yes name of the intent, must use a-zA-Z0-9_
description yes description of the intent

Response

Returns a JSON object represents the created intent.

Get

Gets an intent with the given name.

Example request

curl -X GET \
  https://api.fpt.ai/v1/intents/Hello \
  -H 'Authorization: Bearer your_application_token'

Example response

{
  "label": "Hello",
  "description": "Hello",
  "intent_code": "08f458c4fc51c21e6bb3b5f7f0c2ba14",
  "created_time": "170508034137",
  "application_code": "0453d39964125a62948f01edc2721ed9"
}

Request

GET https://api.fpt.ai/v1/intents/:intent_label

Parameters

Parameter Required Description
intent_label yes name of the intent

Response

Returns a JSON object that represents the intent.

Delete

Deletes an intent specified by name.

Example request

curl -X DELETE \
  https://api.fpt.ai/v1/intents/Hello \
  -H 'Authorization: Bearer your_application_token'

Example response

HTTP 200 OK

Request

DEL https://api.fpt.ai/v1/intents/:intent_label

Parameters

Parameter Required Description
intent_label yes name of the intent

Response

Returns HTTP Status 200 if the request succeed.

Update

Updates an intent specified by its name with the given parameters. You can update the description only.

Example request

curl -X PUT \
  https://api.fpt.ai/v1/intents/hello \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
    "description": "your new description"
  }'

Example response:

{
  "label": "hello",
  "description": "your new description",
  "intent_code": "3e9e0ca2d0e08536da13d8c958a1e997",
  "created_time": "2017-05-08 04:46:38",
  "application_code": "0453d39964125a62948f01edc2721ed9"
}

Request

PUT https://api.fpt.ai/v1/intents/:intent_label

Parameters

Parameter Required Description
intent_label yes name of the intent
description yes new description of the intent

Response

Returns a JSON object that represents the updated intent.

Entity

List

Gets the list of all available entities for the application.

Example request

curl -X GET \
  https://api.fpt.ai/v1/entities \
  -H 'Authorization: Bearer your_application_token'

Example response

{
  "entities": [
    {
      "name": "Name",
      "description": "Name",
      "entity_type_code": "fe218e525a69207279437f8992ca9400",
      "application_code": "0453d39964125a62948f01edc2721ed9",
      "created_time": "2017-05-08 10:43:34"
    }
  ]
}

Request

GET https://api.fpt.ai/v1/entities

Parameters

Parameter Required Description
n/a n/a n/a

Response

Returns a list of available entities for the application.

Create

Creates a new entity with the given parameters.

Example request

curl -X POST \
  https://api.fpt.ai/v1/entities \
  -H 'Authorization: Bearer your_application_token'
  -d '{
    "name": "play_football",
    "description": "Play football"
}'

Example response

{
  "name": "play_football",
  "description": "Play football",
  "entity_type_code": "61b30994cc71dfcf5fe122c046a27b05",
  "application_code": "0453d39964125a62948f01edc2721ed9",
  "created_time": "2017-05-08 14:35:16"
}

HTTP Request

POST https://api.fpt.ai/v1/entities

Parameters

Parameter Required Description
name yes name of the entity, must use a-zA-Z0-9_
description yes description of the entity

Response

Returns a JSON object represents the created entity.

Get

Gets an entity with the given name.

Example request

curl -X GET \
  https://api.fpt.ai/v1/entities/play_football \
  -H 'Authorization: Bearer your_application_token'

Example response

{
  "name": "play_football",
  "description": "Play football",
  "entity_type_code": "61b30994cc71dfcf5fe122c046a27b05",
  "application_code": "0453d39964125a62948f01edc2721ed9",
  "created_time": "2017-05-08 14:35:16"
}

HTTP Request

GET https://api.fpt.ai/v1/entities/:name

Parameters

Parameter Required Description
name yes name of the entity

Response

Returns a JSON object that represents the intent.

Delete

Deletes an entity specified by name.

Example request

curl -X DELETE \
  https://api.fpt.ai/v1/entities/play_football \
  -H 'Authorization: Bearer your_application_token'

Example response

HTTP 200 OK

HTTP Request

DEL https://api.fpt.ai/v1/entities/:name

Parameters

Parameter Required Description
name yes name of the entity

Response

Returns HTTP Status 200 if the request succeed.

Update

Updates an entity specified by its name with the given parameters. You can update the description only.

Example request

curl -X PUT \
  https://api.fpt.ai/v1/entities/play_football \
  -H 'Authorization: Bearer your_application_token'
  -d {
    "description": "my new description"
}

Example response

{
  "name": "play_football",
  "description": "my new description",
  "entity_type_code": "61b30994cc71dfcf5fe122c046a27b05",
  "application_code": "0453d39964125a62948f01edc2721ed9",
  "created_time": "2017-05-08 14:35:16"
}

Request

PUT https://api.fpt.ai/v1/entities/:name

Parameters

Parameter Required Description
name yes name of the entity
description yes new description of the entity

Response

Returns a JSON object that represents the updated entity.

System Entities

Description

System entities that provided by FPT.AI includes:

Support English and Vietnamese

Date/Time

sys_datetime: matches date, time, intervals or date and time together.

sys_datetime_period: matches a date time interval. For instance, “từ 1 đến 3 giờ chiều”. Format of the returned object (hh:mm:ss) 13:00:00/15:00:00

Example request Date/Time Vietnamese

curl -X POST \
  https://api.fpt.ai/v1/recognize \
  -H 'Authorization: Bearer your_application_token' \
  -d '{ "content":"chiều mai","language":"vi" }'

Example response Date/Time Vietnamese

    "entities": [
        {
            "type": "sys_datetime",
            "begin_offset": 0
            "value": "chiều mai",
            "real_value": "2017-08-11T13:00:00.000+07:00",
            "confidence": 1
        }
    ]

Example request Date/Time English

curl -X POST \
  https://api.fpt.ai/v1/recognize \
  -H 'Authorization: Bearer your_application_token' \
  -d '{ "content":"tomorrow morning","language":"en" }'

Example response Date/Time English

{
  "entities": [
    {
      "value": "Tomorrow morning", "begin_offset": 0, "type": 
      "sys_datetime_period", "real_value": "from  11082017T04:00:00.000+07:00  to  11082017T12:00:00.000+07:00"
      "confidence": 1
    }
  ]
}

Email

sys_email : Recognize email in a sentence

Example request Email Vietnamese

curl -X POST \
  https://api.fpt.ai/v1/recognize \
  -H 'Authorization: Bearer your_application_token' \
  -d '{ "content":"email của tôi là nguynminhhiep@fpt.con.vn",
        "language":"vi" 
      }'

Example response Email Vietnamese

{
  "entities": [
    {
      "value": "email của tôi là nguynminhhiep@fpt.con.vn",
      "begin_offset": 16, "type": "sys_email",
      "real_value": "nguynminhhiep@fpt.con.vn"
      "confidence": 1
    }
  ]
}

Example request Email English

curl -X POST \
  https://api.fpt.ai/v1/recognize \
  -H 'Authorization: Bearer your_application_token' \
  -d '{ "content":"my email is tokuda@fpt.con.vn",
        "language":"en" 
      }'

Example response Email English

{
  "entities": [
    {
      "value": "my email is tokuda@fpt.con.vn",
      "begin_offset": 12, "type": "sys_email",
      "real_value": "tokuda@fpt.con.vn"
      "confidence": 1
    }
  ]
}

Number

sys_number: matches float, integer, cardinal numbers. For example, “mười”, “10”, “hai”, etc. The returned object is 10, 10, 2

Example request Number Vietnamese

curl -X POST \
  https://api.fpt.ai/v1/recognize \
  -H 'Authorization: Bearer your_application_token' \
  -d '{ "content":"Cho tôi mười cái bánh ngọt",
        "language":"vi" 
      }'

Example response Number Vietnamese

{
  "entities": [
    {
      "value": "mười",
      "begin_offset": 8, "type": "sys_number",
      "real_value": "10"
      "confidence": 1
    }
  ]
}

Example request Number English

curl -X POST \
  https://api.fpt.ai/v1/recognize \
  -H 'Authorization: Bearer your_application_token' \
  -d '{ "content":"Give me ten pizzas, please!",
        "language":"en" 
      }'

Example response Number English

{
  "entities": [
    {
      "value": "ten",
      "begin_offset": 8, "type": "sys_number",
      "real_value": "10"
      "confidence": 1
    }
  ]
}

Request

POST https://api.fpt.ai/v1/recognize/entity

Parameters

Parameter Required Description
content yes text to recognize
language yes language of content

Response

Returns a JSON object that contains recognized entities with confidence values.

Utterance

List

Gets the list of all available utterances for the intent specified by name.

Example request

curl -X GET \
  https://api.fpt.ai/v1/intents/Hello/utterances \

Example response:

{
  "utterances": [
    {
      "content": "chao ban Son",
      "intent_sample_code": "4548c3bb226db5218c40233cfeee6e33",
      "created_time": "170508044651"
    },
    {
      "content": "Xin chao, Trung",
      "intent_sample_code": "62503c0142214dc7a81ddfc6fa3740a3",
      "created_time": "170508044705"
    }
  ]
}

Request

GET https://api.fpt.ai/v1/intents/:intent_label/utterances

Parameters

Parameter Required Description
intent_label yes name of the intent

Response

Returns a list of available utterances for the intent.

Create

Creates new utterances for the intent specified by name, with the given parameters.

Example request

curl -X POST \
  https://api.fpt.ai/v1/intents/go_swimming/utterances \
  -d '{
  "utterances": ["Mình muốn đi bơi", "Đi bơi đi anh em ơi"]
}'

Example response

HTTP 200

HTTP Request

POST https://api.fpt.ai/v1/intents/:intent_label/utterances

Parameters

Parameter Required Description
intent_label yes name of t
utterances yes an array of utterances

Response

Returns HTTP Status 200 if request succeed.

Delete

Deletes an utterrence specified by its code.

Example request

curl -X DELETE \
  https://api.fpt.ai/v1/intents/Hello/4548c3bb226db5218c40233cfeee6e33 \
  -H 'Authorization: Bearer your_application_token'

Example response

HTTP 200 OK

Request

DEL https://api.fpt.ai/v1/intents/:intent_label/:utterance_code

Parameters

Parameter Required Description
intent_label yes name of the intent that has the utterance
utterance_code yes code of the utterance

Response

Returns HTTP Status 200 if the request succeed.

Update

Updates an utterance with the given paramenters to label its entity values.

Example request

curl -X PUT \
  https://api.fpt.ai/v1/intents/hello/utterances/4548c3bb226db5218c40233cfeee6e33 \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
    "entity_name": "Name",
    "entity_value": "Son",
    "entity_position": 9
}'

Example response

{
  "entity_type_code": "fe218e525a69207279437f8992ca9400",
  "entity_value": "Son",
  "entity_position": 9,
  "entity_sample_code": "c182e6670fb096722be5163c3188492a",
  "intent_sample_code": "4548c3bb226db5218c40233cfeee6e33",
  "created_time": "170508044717"
}

Request

PUT https://api.fpt.ai/v1/intents/:intent_label/utterances/:utterance_code

Query Parameters

Parameter Required Description
intent_label yes name of intent contains the utte
utterance_code yes code of the utterance
entity_name yes name of the entity
entity_value yes value of the entity in the utterance
entity_position yes (int) the starting position of entity value in the utterance

Response

Returns a JSON object that represents the updated utterance.

Train

All

Requests FPT.AI to train/re-retrain for both intent model and entity model for the application.

Note: You MUST have at least 2 intents to train.

Example request

curl -X POST \
  https://api.fpt.ai/v1/train \
  -H 'Authorization: Bearer your_application_token' \

Example response

{
  "message": "training request is accepted"
}

Request

POST https://api.fpt.ai/v1/train

Parameters

Parameter Required Description
N/A n/a n/a

Response

Returns a JSON message represents the training status.

Intent

Requests FPT.AI to train/re-retrain intent model for the application.

Note: You MUST have at least 2 intents to train.

Example request

curl -X POST \
  https://api.fpt.ai/v1/train/intent \
  -H 'Authorization: Bearer your_application_token' \

Example response

{
  "message": "training request is accepted"
}

Request

POST https://api.fpt.ai/v1/train/intent

Parameters

Parameter Required Description
N/A n/a n/a

Response

Returns a JSON message represents the training status.

Entity

Requests FPT.AI to train/re-retrain intent model for the application.

Example request

curl -X POST \
  https://api.fpt.ai/v1/train/entity \
  -H 'Authorization: Bearer your_application_token' \

Example response

{
  "message": "training request is accepted"
}

Request

POST https://api.fpt.ai/v1/train/entity

Parameters

Parameter Required Description
n/a n/a n/a

Response

Returns a JSON message represents the training status.

Recognize

All

Requests FPT.AI to recognize for both intents of and entities in the given text.

Example request

curl -X POST \
  https://api.fpt.ai/v1/recognize \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
  "text": "Bơi ở Hạ Long"
}'

Example response

{
  "entities": [
    {
      "type": "Place",
      "value": "Hạ Long",
      "confidence": 1
    }
  ],
  "intents": [
    {
      "label": "go_swimming",
      "confidence": 0.7611
    },
    {
      "label": "Goodbye",
      "confidence": 0.153
    },
    {
      "label": "play_football",
      "confidence": 0.0859
    }
  ]
}

Request

POST https://api.fpt.ai/v1/recognize

Parameters

Parameter Required Description
text yes text to recognize

Response

Returns a JSON object that contains recognized intents and entities with confidence values.

Intent

Requests FPT.AI to recognize for intents of the given text.

Example request

curl -X POST \
  https://api.fpt.ai/v1/recognize/intent \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
  "text": "đá bóng"
}'

Example response

{
  "intents": [
    {
      "label": "go_swimming",
      "confidence": 0.8867
    },
    {
      "label": "play_football",
      "confidence": 0.0842
    },
    {
      "label": "Goodbye",
      "confidence": 0.0611
    }
  ]
}

Request

POST https://api.fpt.ai/v1/recognize/intent

Paramenters

Parameter Required Description
text yes text to recognize

Response

Returns a JSON object that contains recognized intents with confidence values.

Entity

Requests FPT.AI to recognize for entities in the given text.

Example request

curl -X POST \
  https://api.fpt.ai/v1/recognize/entity \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
  "text": "bơi ở Sầm Sơn"
}'

Example response

{
  "entities": [
    {
      "type": "Place",
      "value": "Sầm Sơn",
      "confidence": 1
    }
  ]
}

Request

POST https://api.fpt.ai/v1/recognize/entity

Paramenters

Parameter Required Description
text yes text to recognize

Response

Returns a JSON object that contains recognized entities with confidence values.