/entities

Overview

The entities endpoint is used to create, retrieve, update, and delete developer-defined entity objects.

See Entity Overview for detailed information on entities.

URLs and Objects

The following URLs are available:

URL Definition
GET /entities Retrieves a list of all entities for the agent.
GET /entities/{eid} Retrieves the specified entity.
POST /entities Creates a new entity.
POST /entities/{eid}/entries Adds an array of entity entries to the specified entity.
PUT /entities Creates or updates multiple entities.
PUT /entities/{eid} Updates the specified entity.
PUT /entities/{eid}/entries Updates an array of entity entries in the specified entity.
DELETE /entities/{eid} Deletes the specified entity.
DELETE /entities/{eid}/entries Deletes an array of entity entries from the specified entity.

Entity object contains information about an entity, including its ID, name, and entries.

GET /entities

Retrieves a list of all entities for the agent.

GET /entities Sample Request

The following request returns all entities for the agent that is associated with the access token.

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

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN

GET /entities Sample cURL request

curl -k -H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" "https://api.api.ai/v1/entities?v=20150910"

GET /entities Response

The response will be a JSON object with the following fields:

Name Type Description
entities entities Array of objects An array of entity description objects
id String ID of the entity
name String Name of the entity
count int The total number of synonyms in the entity
preview String A string that contains summary information about the entity
status Status object Contains data on how the request succeeded or failed.

GET /entities Sample Response

[
  {
    "id": "33868522-5747-4a31-88fb-3cd13bd18684",
    "name": "Appliances",
    "count": 11,
    "preview": "Coffee Maker <= (coffee maker, coffee machine, coffee), ..."
  },
  {
    "id": "6d6b7d50-7510-4fec-927b-ac3c3aaff009",
    "name": "Utilities",
    "count": 4,
    "preview": "Electricity <= (electricity, electrical), ..."
  }
]

GET /entities/{eid}

Retrieves the specified entity.

{eid} is the ID of the entity to retrieve. You can specify the entity by its name instead of its ID.

GET /entities/{eid} Sample Request

The following request returns the entity with ID of 33868522-5747-4a31-88fb-3cd13bd18684.

GET https://api.api.ai/v1/entities/33868522-5747-4a31-88fb-3cd13bd18684?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN

GET /entities/{eid} Sample cURL Request

curl -k -H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" "https://api.api.ai/v1/entities/33868522-5747-4a31-88fb-3cd13bd18684?v=20150910"

GET /entities/{eid} Response

The response is an entity object.

POST /entities

Creates a new entity.

POST /entities Request

The POST body is an entity object without the "id", "isEnum", and "automatedExpansion" elements.

POST /entities Sample Request

The following request creates an entity that could be used for recognizing appliances.

POST https://api.api.ai/v1/entities?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json; charset=utf-8

POST body:
{
    "name": "Appliances",
    "entries": [{
        "value": "Coffee Maker",
        "synonyms": ["coffee maker", "coffee machine",  "coffee"]
    }, {
        "value": "Thermostat",
        "synonyms": ["Thermostat", "heat", "air conditioning"]
    }, {
        "value": "Lights",
        "synonyms": ["lights", "light", "lamps"]
    }, {
        "value": "Garage door",
        "synonyms": ["garage door", "garage"]
    }]
}

POST /entities Sample cURL request

This curl request creates an entity for utilities such as electricity, gas, and water.

curl -k -H "Content-Type: application/json; charset=utf-8" -H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" --data " {'name':'Utilities','entries':[{'value':'Electricity','synonyms':['electricity','electrical']},{'value':'Gas','synonyms':['gas','natural gas']},{'value':'Water','synonyms':['water']}]}" "https://api.api.ai/v1/entities?v=20150910"

POST /entities Response

POST /entities Response has the following fields:

Name Type Description
id String The ID of the new entity.
status Status object Contains data on how the request succeeded or failed.

POST /entities Sample Response

{
  "id": "6d6b7d50-7510-4fec-927b-ac3c3aaff009",
  "status": {
    "code": 200,
    "errorType": "success"
  }
}

POST /entities/{eid}/entries

Adds entries to the specified entity.

{eid} is the ID of the entity to which the entries will be added. You can specify the entity by its name instead of its ID.

POST /entities/{eid}/entries Request

The POST body is an array of entity entry objects in JSON format.

POST /entities/{eid}/entries cURL Sample Request

The following request adds two entries to the entity with the ID cdc72cfd-78da-41cb-8af4-e4237bd93101.

curl -i -X POST -H "Content-Type:application/json" -H "Authorization:Bearer YOUR_DEVELOPER_ACCESS_TOKEN" -d '[{"value": "parrot","synonyms": ["parrot", "parrots"]},{"value": "rabbit","synonyms": ["rabbit", "rabbits"]}]' 'https://api.api.ai/v1/entities/cdc72cfd-78da-41cb-8af4-e4237bd93101/entries?v=20150910'

PUT /entities

Creates or updates an array of entities.

PUT /entities Request

The PUT body consists of an array of entity objects without the "id", "isEnum", and "automatedExpansion" elements.

[
   {
      "name":"cat",
      "entries":[
         {
            "value":"cat",
            "synonyms":[
               "cat",
               "kitty"
            ]
         }
      ]
   },
   {
      "name":"dog",
      "entries":[
         {
            "value":"dog",
            "synonyms":[
               "dog",
               "puppy"
            ]
         }
      ]
   }
]

PUT /entities Sample cURL request

curl -k -X PUT -H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" -H "Content-Type: application/json" --data "[{'name': 'cat', 'entries': [{'value':'cat', 'synonyms':['cat', 'kitty']} ]}, {'name': 'dog', 'entries': [{'value':'dog', 'synonyms':['dog', 'puppy']} ]}]" "https://api.api.ai/v1/entities?v=20150910"

PUT /entities/{eid}

Updates the specified entity.

{eid} is the ID of the entity to update. You can specify the entity by its name instead of its ID.

PUT /entities/{eid} Request

The PUT body is an entity object.

PUT /entities/{eid} Sample Request

The following request updates an entity of ID 80f817e8-23fb-4e8e-ba62-eca1fcef7c3a, changing the name to "Utility-Types".

PUT https://api.api.ai/v1/entities/80f817e8-23fb-4e8e-ba62-eca1fcef7c3a?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json; charset=utf-8

PUT body:
{
  "id":"80f817e8-23fb-4e8e-ba62-eca1fcef7c3a",
  "name": "Utility-Types",
  "entries": [
    {
      "value": "Electricity",
      "synonyms": [
        "electricity",
        "electrical"
      ]
    },
    {
      "value": "Gas",
      "synonyms": [
        "gas",
        "natural gas",
      ]
    },
    {
      "value": "Water",
      "synonyms": [
        "water"
      ]
    }
  ]
}

PUT /entities/{eid} Sample cURL request

curl -k -X PUT -H "Content-Type: application/json; charset=utf-8" -H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" --data "{'id':'80f817e8-23fb-4e8e-ba62-eca1fcef7c3a','name':'Utility-Types','entries':[{'value':'Electricity','synonyms':['electricity','electrical']},{'value':'Gas','synonyms':['gas']},{'value':'Water','synonyms':['water']}]}" "https://api.api.ai/v1/entities/80f817e8-23fb-4e8e-ba62-eca1fcef7c3a?v=20150910"

PUT /entities/{eid} Response

Name Type Description
status Status object Contains data on how the request succeeded or failed.

PUT /entities/{eid}/entries

Updates entity entries.

{eid} is the ID of the entity in which entries will be updated. You can specify the entity by its name instead of its ID.

PUT /entities/{eid}/entries Request

The PUT body is an array of entity entry objects in JSON format.

PUT /entities/{eid}/entries Sample cURL Request

The following request updates the @color entity entry corresponding to the reference value "blue".

curl -i -X PUT -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Bearer YOUR_DEVELOPER_ACCESS_TOKEN" -d '[{"value":"blue", "synonyms": ["blue", "turquoise"]}]' 'https://api.api.ai/v1/entities/color/entries?v=20150910'

Delete /entities/{eid}

Deletes the specified entity.

{eid} is the ID of the entity to delete. You can specify the entity by its name instead of its ID.

DELETE /entities/{eid} Sample Request

The following request deletes an entity of ID 80f817e8-23fb-4e8e-ba62-eca1fcef7c3a.

DELETE https://api.api.ai/v1/entities/80f817e8-23fb-4e8e-ba62-eca1fcef7c3a?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN

DELETE /entities/{eid} Sample cURL Request

curl -k -X DELETE -H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" "https://api.api.ai/v1/entities/6d6b7d50-7510-4fec-927b-ac3c3aaff009?20150910?v=20150910"

DELETE /entities/{eid} Response

Name Type Description
status Status object Contains data on how the request succeeded or failed.

DELETE /entities/{eid}/entries

Deletes entity entries.

{eid} is the ID of the entity from which entries will be deleted. You can specify the entity by its name instead of its ID.

DELETE /entities/{eid}/entries Request

The DELETE body is an array of strings corresponding to the reference values of entity entries to be deleted.

DELETE /entities/{eid}/entries Sample cURL Request

The following request deletes the entry with the reference value "blue" from the @color entity.

curl -i -X DELETE -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Bearer YOUR_DEVELOPER_ACCESS_TOKEN" -d '["blue"]' 'https://api.api.ai/v1/entities/color/entries?v=20150910'

Entity Object

The entity JSON object contains all information about an entity, including its ID, name, and entries.

The entity object has the following fields:

Name Type Description
id String A unique identifier for the entity.
name Legal Name The name of the entity.
entries Array of objects An array of entry objects, which contain reference values and synonyms.
value String
  • For mapping entities: a canonical name to be used in place of synonyms.
    Example: "New York"
  • For enum type entities: a string that can contain references to other entities (with or without aliases).
    Example: "@sys.color:color @size:size @clothes:clothes"
synonyms Array of strings that can include simple strings (for words and phrases) or references to other entites (with or without aliases).
  • For mapping entities: an array of synonyms.
    Example: ["New York", "NYC", "big Apple"]
  • For enum type entities: a string that is identical to the value string.
    Example: "@sys.color:color @size:size @clothes:clothes"
isEnum Boolean Indicates if the entity is a mapping or an enum type entity.
automatedExpansion Boolean Indicates if the entity can be automatically expanded.

Sample Mapping Entity Object

{
  "id": "1de251bf-46a6-4056-af9c-96b6ca89dfd0",
  "name": "appliances",
  "entries": [
    {
      "value": "coffee maker",
      "synonyms": [
        "coffee maker",
        "coffee"
      ]
    },
    {
      "value": "thermostat",
      "synonyms": [
        "thermostat",
        "heat",
        "air conditioning"
      ]
    },
    {
      "value": "lights",
      "synonyms": [
        "lights",
        "light",
        "lamps"
      ]
    },
    {
      "value": "garage door",
      "synonyms": [
        "garage door",
        "garage"
      ]
    }
  ],
  "isEnum": false,
  "automatedExpansion": false
}

Sample Enum Type Composite Entity Object

{
  "id": "0f2c0b53-8681-4e76-9f26-04947bbc48d9",
  "name": "item",
  "entries": [
    {
      "value": "@sys.color:color @size:size @clothes:clothes",
      "synonyms": [
        "@sys.color:color @size:size @clothes:clothes"
      ]
    },
    {
      "value": "@sys.color:color @clothes:clothes of @size:size",
      "synonyms": [
        "@sys.color:color @clothes:clothes of @size:size"
      ]
    }
  ],
  "isEnum": true,
  "automatedExpansion": false
}

Array of Entity Entry Objects

Array of entity entry objects contains information about entity entries.

Each object has the following fields:

Name Type Description
value String
synonyms Array of strings

Sample Array of Mapping Entity Entry Objects

[{
    "value": "dog",
    "synonyms": [
        "dog",
        "dogs"
    ]
}, {
    "value": "cat",
    "synonyms": [
        "cat",
        "cats",
        "kitten",
        "kittens"
    ]
}]