{"_id":"5845a4a89f6fbb1b004307ce","__v":0,"category":{"_id":"5845a4a89f6fbb1b004307ba","__v":0,"version":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-30T06:53:33.020Z","from_sync":false,"order":2,"slug":"api-reference","title":"API reference"},"version":{"_id":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","__v":2,"createdAt":"2016-12-05T17:32:24.708Z","releaseDate":"2016-12-05T17:32:24.708Z","categories":["5845a4a89f6fbb1b004307b8","5845a4a89f6fbb1b004307b9","5845a4a89f6fbb1b004307ba","5845a4a89f6fbb1b004307bb","5845a4a89f6fbb1b004307bc","5845a4a89f6fbb1b004307bd","5845a4a89f6fbb1b004307be","5845a4a89f6fbb1b004307bf","5845a4a89f6fbb1b004307c0","592deb23644f060f008e5aa6"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"25.0.0","version":"25"},"user":"54d3006a5616470d0013cc4d","parentDoc":null,"project":"54d3007669578e0d002730c9","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-23T23:54:47.008Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"* [Overview](#overview)\n* [User Entity Object](#user-entity-object)\n* [POST /userEntities](#post-userentities)\n* [PUT /userEntities/{name}](#put-userentitiesname)\n* [GET /userEntities/{name}](#get-userentitiesname)\n* [DELETE /userEntities/{name}](#delete-userentitiesname)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nEntities can be redefined on a user (session ID) level. A good scenario could be when you have a :::at:::playlist entity that has generic playlist. As playlists are user-specific, @playlist entity could be defined in a request or for a given session.\n\nIf user entities are submitted via the /userEntities endpoint, they live in the session for 30 minutes.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"User entities can be submitted in a /query request.\",\n  \"body\": \"This may not be always desirable due to entity size, but user entities could be submitted via a <a href=\\\"https://docs.api.ai/docs/query\\\" target=\\\"_blank\\\">/query</a> endpoint request.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"User Entity Object\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"sessionId\",\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Session ID for a user.\",\n    \"1-0\": \"name\",\n    \"1-1\": \"Entity Name\",\n    \"1-2\": \"Name of the entity.\",\n    \"2-0\": \"extend\",\n    \"2-1\": \"boolean\",\n    \"2-2\": \"A flag identifying whether the additional data should extend or replace the default entity definition.\\n<i class=\\\"fa fa-info-circle\\\"></i> Optional field. If not defined, the default value is `false`.\",\n    \"3-0\": \"entries\",\n    \"3-1\": \"Array of Entity Entry objects\",\n    \"3-2\": \"\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"sessionId\\\":\\\"12345\\\",\\n   \\\"name\\\":\\\"city\\\",\\n   \\\"extend\\\":false,\\n   \\\"entries\\\":[\\n      {\\n         \\\"value\\\":\\\"New York\\\",\\n         \\\"synonyms\\\":[\\n            \\\"New York\\\",\\n            \\\"Big Apple\\\"\\n         ]\\n      }\\n   ]\\n}\",\n      \"language\": \"json\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"POST /userEntities\"\n}\n[/block]\nAdds one or multiple user entities for a session.\n\nEntities JSON:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"sessionId\\\":\\\"12345\\\",\\n   \\\"entities\\\":[\\n      {\\n         \\\"name\\\":\\\"city\\\",\\n         \\\"entries\\\":[\\n            {\\n               \\\"value\\\":\\\"New York\\\",\\n               \\\"synonyms\\\":[\\n                  \\\"New York\\\",\\n                  \\\"Big Apple\\\"\\n               ]\\n            }\\n         ]\\n      },\\n      {\\n         \\\"name\\\":\\\"country\\\",\\n         \\\"entries\\\":[\\n            {\\n               \\\"value\\\":\\\"USA\\\",\\n               \\\"synonyms\\\":[\\n                  \\\"USA\\\"\\n               ]\\n            }\\n         ]\\n      }\\n   ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST -k -H \\\"Content-Type: application/json\\\" -H \\\"Authorization: Bearer CLIENT_ACCESS_TOKEN\\\" \\\"https://api.api.ai/v1/userEntities?v=20150910&sessionId=12345\\\" -d @entities.json\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"PUT /userEntities/{name}\"\n}\n[/block]\nUpdates user entity specified by name.\nAccepts user entity object.\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"GET /userEntities/{name}\"\n}\n[/block]\nGets a user entity object by name.\n\n### GET /userEntities/{name} Sample cURL Request\n\nThe following request retrieves the user entity object for the `@items` user entity for the sessionId \"12345\".\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET -H \\\"Content-Type: application/json\\\" -H \\\"Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN\\\" \\\"https://api.api.ai/v1/userEntities/items?v=20150910&sessionId=12345\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"delete\",\n  \"title\": \"DELETE /userEntities/{name}\"\n}\n[/block]\nDeletes a user entity object with a specified name.","excerpt":"","slug":"userentities","type":"basic","title":"/userEntities"}
* [Overview](#overview) * [User Entity Object](#user-entity-object) * [POST /userEntities](#post-userentities) * [PUT /userEntities/{name}](#put-userentitiesname) * [GET /userEntities/{name}](#get-userentitiesname) * [DELETE /userEntities/{name}](#delete-userentitiesname) [block:api-header] { "type": "basic", "title": "Overview" } [/block] Entities can be redefined on a user (session ID) level. A good scenario could be when you have a @playlist entity that has generic playlist. As playlists are user-specific, @playlist entity could be defined in a request or for a given session. If user entities are submitted via the /userEntities endpoint, they live in the session for 30 minutes. [block:callout] { "type": "warning", "title": "User entities can be submitted in a /query request.", "body": "This may not be always desirable due to entity size, but user entities could be submitted via a <a href=\"https://docs.api.ai/docs/query\" target=\"_blank\">/query</a> endpoint request." } [/block] [block:api-header] { "type": "basic", "title": "User Entity Object" } [/block] [block:parameters] { "data": { "0-0": "sessionId", "h-0": "Field name", "h-1": "Type", "h-2": "Description", "0-1": "String", "0-2": "Session ID for a user.", "1-0": "name", "1-1": "Entity Name", "1-2": "Name of the entity.", "2-0": "extend", "2-1": "boolean", "2-2": "A flag identifying whether the additional data should extend or replace the default entity definition.\n<i class=\"fa fa-info-circle\"></i> Optional field. If not defined, the default value is `false`.", "3-0": "entries", "3-1": "Array of Entity Entry objects", "3-2": "" }, "cols": 3, "rows": 4 } [/block] For example: [block:code] { "codes": [ { "code": "{\n \"sessionId\":\"12345\",\n \"name\":\"city\",\n \"extend\":false,\n \"entries\":[\n {\n \"value\":\"New York\",\n \"synonyms\":[\n \"New York\",\n \"Big Apple\"\n ]\n }\n ]\n}", "language": "json", "name": null } ] } [/block] [block:api-header] { "type": "post", "title": "POST /userEntities" } [/block] Adds one or multiple user entities for a session. Entities JSON: [block:code] { "codes": [ { "code": "{\n \"sessionId\":\"12345\",\n \"entities\":[\n {\n \"name\":\"city\",\n \"entries\":[\n {\n \"value\":\"New York\",\n \"synonyms\":[\n \"New York\",\n \"Big Apple\"\n ]\n }\n ]\n },\n {\n \"name\":\"country\",\n \"entries\":[\n {\n \"value\":\"USA\",\n \"synonyms\":[\n \"USA\"\n ]\n }\n ]\n }\n ]\n}", "language": "json" } ] } [/block] [block:code] { "codes": [ { "code": "curl -X POST -k -H \"Content-Type: application/json\" -H \"Authorization: Bearer CLIENT_ACCESS_TOKEN\" \"https://api.api.ai/v1/userEntities?v=20150910&sessionId=12345\" -d @entities.json", "language": "curl" } ] } [/block] [block:api-header] { "type": "put", "title": "PUT /userEntities/{name}" } [/block] Updates user entity specified by name. Accepts user entity object. [block:api-header] { "type": "get", "title": "GET /userEntities/{name}" } [/block] Gets a user entity object by name. ### GET /userEntities/{name} Sample cURL Request The following request retrieves the user entity object for the `@items` user entity for the sessionId "12345". [block:code] { "codes": [ { "code": "curl -X GET -H \"Content-Type: application/json\" -H \"Authorization: Bearer YOUR_CLIENT_ACCESS_TOKEN\" \"https://api.api.ai/v1/userEntities/items?v=20150910&sessionId=12345\"", "language": "curl" } ] } [/block] [block:api-header] { "type": "delete", "title": "DELETE /userEntities/{name}" } [/block] Deletes a user entity object with a specified name.