We’ve changed our name! API.AI is now Dialogflow. Learn more here.

/entities

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

See Entity Overview for detailed information on entities.

BaseURL

https://api.dialogflow.com/v1/

Entity JSON object

Name Type Description
automatedExpansion Boolean Indicates if the entity can be automatically expanded.
entries Array of objects An array of entry objects.
- synonyms Array of strings This defines the possible synonyms for the entity.
- value String The literal text string provided for the entity's value.
id String A unique identifier for the entity.
isEnum Boolean Indicates if the entity is a mapping or an enum type entity.
isOverridable Boolean Indicates whether this entity can be overridden by a system or developer entity. Default is true.
name String The name of the entity. Entity names can only consist of A-Z, a-z, 0-9, _ (underscore), and - (dash)

GET /entities

Retrieves a summary list of all entities for the agent.

Entities with entries in specific languages can be retrieved by adding the lang parameter and the language/locale code to the request URL.

For example, to get a list of all entities with entries under the Spanish language, you would use the following request URL: https://api.dialogflow.com/v1/entities?v=20150910&lang=es

GET /entities sample

HTTP

GET https://api.dialogflow.com/v1/entities?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json
    

cURL

curl -X GET \
"https://api.dialogflow.com/v1/entities?v=20150910" \
-H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" \
-H "Content-Type: application/json"
    

GET /entities response

GET /entities/{id}

Retrieves the entity with the specified {id}. You can also specify the entity by name instead of ID.

One entity is used across all languages/locales and it uses the same name and ID. To retrieve an entity's language specific entries, add the lang parameter and the language/locale code to the request URL.

For example, to get the Spanish version of the specified entity, you would use the following request URL: https://api.dialogflow.com/v1/entities/613de225-65b2-4fa8-9965-c14ae7673826?v=20150910&lang=es

GET /entities/{id} sample

HTTP

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

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json
    

cURL

curl -X GET \
"https://api.dialogflow.com/v1/entities/33868522-5747-4a31-88fb-3cd13bd18684?v=20150910" \
-H "Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN" \
-H "Content-Type: application/json"
    

GET /entities/{id} response

POST /entities

Creates a new entity.

When you create an entity in a multi-lingual agent, the same entity is used across all languages. The entries are customized per language.

To create an entity and include entries for a specific language, add the lang parameter and the language/locale code to the request URL.

For example, to create a new entity and insert the entries under the Spanish language, you would use the following request URL: https://api.dialogflow.com/v1/entities?v=20150910&lang=es

POST /entities sample

HTTP

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

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json

POST body:
{
  "entries": [{
      "synonyms": ["apple", "red apple"],
      "value": "apple"
    },
    {
      "value": "banana"
    }
  ],
  "name": "fruit"
}
    

cURL

curl -X POST \
'https://api.dialogflow.com/v1/entities?v=20150910' \
-H 'Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
--data '{
  "entries": [{
      "synonyms": ["apple", "red apple"],
      "value": "apple"
    },
    {
      "value": "banana"
    }
  ],
  "name": "fruit"
}'
    

POST /entities/{id}/entries

Creates entries in the entity related to the provided {id}.

To add language specific entries, add the lang parameter and the language/locale code to the request URL.

For example, to add the entries under the Spanish language for the specified entity, you would use the following request URL: https://api.dialogflow.com/v1/entities/613de225-65b2-4fa8-9965-c14ae7673826/entries?v=20150910&lang=es

POST /entities/{id}/entries sample

HTTP

POST https://api.dialogflow.com/v1/entities/cdc72cfd-78da-41cb-8af4-e4237bd93101/entries?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json

POST body:
[
  {
    "synonyms": [
      "kiwi"
    ],
    "value": "kiwi"
  }
]
    

cURL

curl -X POST \
'https://api.dialogflow.com/v1/entities?v=20150910' \
-H 'Authorization: Bearer DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
--data '[
  {
    "synonyms": [
      "kiwi"
    ],
    "value": "kiwi"
  }
]'
    

PUT /entities

Creates or updates multiple entities.

To update language specific entries, add the lang parameter and the language/locale code to the request URL.

For example, to update the specified entity and insert the entries under the Spanish language, you would use the following request URL: https://api.dialogflow.com/v1/entities?v=20150910&lang=es

PUT /entities sample

HTTP

PUT https://api.dialogflow.com/v1/entities?v=20150910&sessionId=12345

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json

PUT body:
[
  {
    "entries": [
      {
        "synonyms": [
          "kiwi"
        ],
        "value": "kiwi"
      }
    ],
    "name": "fruit"
  }
]
    

cURL

curl -X PUT \
'https://api.dialogflow.com/v1/entities?v=20150910&sessionId=12345' \
-H 'Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
--data '[
  {
    "entries": [
      {
        "synonyms": [
          "kiwi"
        ],
        "value": "kiwi"
      }
    ],
    "name": "fruit"
  }
]'
    

PUT /entities/{id}

Updates the entity related to the provided {id}.

To update language specific entries, add the lang parameter and the language/locale code to the request URL.

For example, to update the specified entity and insert the entries under the Spanish language, you would use the following request URL: https://api.dialogflow.com/v1/entities/613de225-65b2-4fa8-9965-c14ae7673826?v=20150910&lang=es

PUT /entities/{id} sample

HTTP

PUT https://api.dialogflow.com/v1/entities/b9475ab7-7897-4f83-bb6c-044bd7610ea0?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json

PUT body:
[
  {
    "entries": [
      {
        "synonyms": [
          "kiwi"
        ],
        "value": "kiwi"
      }
    ],
    "name": "fruit"
  }
]
    

cURL

curl -X PUT \
'https://api.dialogflow.com/v1/entities/b9475ab7-7897-4f83-bb6c-044bd7610ea0?v=20150910' \
-H 'Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
--data '[
  {
    "entries": [
      {
        "synonyms": [
          "kiwi"
        ],
        "value": "kiwi"
      }
    ],
    "name": "fruit"
  }
]'
    

PUT /entities/{id}/entries

Updates entries in the entity related to the provided {id}.

To update language specific entries, add the lang parameter and the language/locale code to the request URL.

For example, to update the entries under the Spanish language for a specified entity, you would use the following request URL: https://api.dialogflow.com/v1/entities/613de225-65b2-4fa8-9965-c14ae7673826/entries?v=20150910&lang=es

PUT /entities/{id}/entries sample

HTTP

PUT https://api.dialogflow.com/v1/entities/b9475ab7-7897-4f83-bb6c-044bd7610ea0/entries?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json

PUT body:
[
  {
    "synonyms": [
      "kiwi"
    ],
    "value": "kiwi"
  }
]
    

cURL

curl -X PUT \
'https://api.dialogflow.com/v1/entities/b9475ab7-7897-4f83-bb6c-044bd7610ea0?v=20150910' \
-H 'Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
--data '[
  {
    "entries": [
      {
        "synonyms": [
          "kiwi"
        ],
        "value": "kiwi"
      }
    ],
    "name": "fruit"
  }
]'
    

DELETE /entities/{id}

Deletes the specified entity. {id} is the ID of the entity to delete.

DELETE /entities/{id} Sample

HTTP

DELETE https://api.dialogflow.com/v1/entities/b9475ab7-7897-4f83-bb6c-044bd7610ea0?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json
    

cURL

curl -X DELETE \
'https://api.dialogflow.com/v1/entities/b9475ab7-7897-4f83-bb6c-044bd7610ea0?v=20150910' \
-H 'Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json'
    

DELETE /entities/{id}/entries

Deletes entries from the entity specified by {id}.

To delete entries of a specific language, add the lang parameter and the language/locale code to the request URL.

For example, to delete the specified Spanish language entries in the entity, you would use the following request URL: https://api.dialogflow.com/v1/entities/613de225-65b2-4fa8-9965-c14ae7673826/entries?v=20150910&lang=es

DELETE /entities/{id}/entries sample

HTTP

DELETE https://api.dialogflow.com/v1/entities/b9475ab7-7897-4f83-bb6c-044bd7610ea0/entries?v=20150910

Headers:
Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN
Content-Type: application/json

DELETE body:
[
  "apple",
  "orange"
]
    

cURL

curl -X DELETE \
'https://api.dialogflow.com/v1/entities/b9475ab7-7897-4f83-bb6c-044bd7610ea0/entries?v=20150910' \
-H 'Authorization: Bearer YOUR_DEVELOPER_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
--data '[
  "apple",
  "orange"
]'
    

POST, PUT and DELETE responses