Let’s imagine an agent for a retail store app. There is a developer entity that matches items available in the store. Let’s call it @item. The initial version of the entity contains a list of items available in the store at the moment of the agent’s creation. But since the stock of items is updated regularly, it would be very inefficient to update the entity manually.
To keep the entity in sync with the store database, API.AI now offers three additional options in the /entities endpoint that allow you to add, update, and delete entity entries via our API.
Let’s see how it works. Here is the original version of a sample entity we started working with:
Remember that for any of the following operations you’ll need to specify an entity ID (referenced as {eid}) or its name.
Adding Entity Entries
So, the store has two new items for sale, e.g., kefir and ice-cream, and the store owner needs to add new entries to the @item entity.
This can be done with the help of POST /entities/{eid}/entries request.
The POST body should be an array of entity entry objects in JSON format.
POST https://api.api.ai/v1/entities/item/entries?v=20150910
Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json; charset=utf-8
POST body:
[{
"value": "kefir",
"synonyms": ["kefir"]
}, {
"value": "ice-cream",
"synonyms": ["ice-cream", "ice cream"]
}]
As a cURL request, it will look like this:
curl -i -X POST -H "Content-Type:application/json" -H "Authorization:Bearer YOUR_DEVELOPER_ACCESS_TOKEN" \
-d '[{"value": "kefir", "synonyms": ["kefir"]}, {"value": "ice-cream", "synonyms": ["ice-cream", "ice cream"]}]' 'https://api.api.ai/v1/entities/item/entries'
This is how the entity will look in the API.AI developer console after sending this request:
Updating Entity Entries
If you need to add or delete synonyms in already existing entries, you can use PUT /entities/{eid}/entries request.
The PUT body should be an array of entity entry objects in JSON format. The array of synonyms should contain the updated array of synonyms.
For example, you may want to add some spelling variants to the “yogurt” and “kefir” entries.
The cURL request for this will look like this:
curl -i -X PUT -H "Accept:application/json" H "Content-Type:application/json" -H "Authorization:Bearer YOUR_DEVELOPER_ACCESS_TOKEN" \
-d '[{"value":"yogurt", "synonyms": ["yoghurt", "yoghourt"]}, {"value":"kefir", "synonyms": ["kefir", "keefir", "kephir"]}]' 'https://api.api.ai/v1/entities/item/entries'
The result of this manipulation can be seen in the API.AI developer console:
Deleting Entity Entries
Now, let’s imagine some items were sold out and you need to delete the entries from the @item entity.
You can do it with the help of DELETE /entities/{eid}/entries request.
The DELETE body should contain an array of strings corresponding to the reference values of entity entries.
For example, for deleting “milk” and “kefir”, the cURL request will be this:
curl -i -X DELETE -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Bearer YOUR_DEVELOPER_ACCESS_TOKEN" \
-d '["milk", "kefir"]' 'https://api.api.ai/v1/entities/item/entries'
Here’s the result of this request seen in the API.AI developer console:
Related documentation:
