Curl Node Java Python

Conversation

API Reference
The IBM Watson Conversation Service API Reference page

Introduction

The IBM Watson™ Conversation service combines machine learning, natural language understanding, and integrated dialog tools to create conversation flows between your apps and your users.

API Endpoint

https://gateway.watsonplatform.net/conversation/api/v1

The code examples on this tab use the client library that is provided for Node.js.

GitHub

https://github.com/watson-developer-cloud/node-sdk

Node Package Manager

npm install watson-developer-cloud

The code examples on this tab use the client-side library that is provided for Java.

GitHub

https://github.com/watson-developer-cloud/java-sdk

Maven

<dependency>
  <groupId>com.ibm.watson.developer_cloud</groupId>
  <artifactId>java-sdk</artifactId>
  <version>3.3.1</version>
</dependency>

Gradle

compile 'com.ibm.watson.developer_cloud:java-sdk:3.3.1'

The code examples on this tab use the client-side library that is provided for Python.

GitHub

https://github.com/watson-developer-cloud/python-sdk

pip

pip install -I watson-developer-cloud==0.26.1

API explorer

To interact with this REST API, use the Conversation service API explorer. Use the explorer to test your calls to the API and to view live responses from the server.

Authentication

You authenticate to the Conversation API by providing the username and password that are provided in the service credentials for the service instance that you want to use. The API uses Basic Authentication.

After creating an instance of the Conversation service, select Service Credentials from the left navigation for its dashboard to see the username and password that are associated with that instance. For more information, see Service credentials for Watson services.

Applications can also use tokens to establish authenticated communications with Watson services without embedding their service credentials in every call. You write an authentication proxy in Bluemix to obtain a token for your client application, which can then use the token to call the service directly. You use your service credentials to obtain a token for that service. For more information, see Tokens for authentication.

Replace {username} and {password} with your credentials. Replace {version} with the version of the API that you want to use (for example, 2017-05-26).


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/{method}"

var watson = require('watson-developer-cloud');

var conversation = watson.conversation({
  username: '{username}',
  password: '{password}',
  version: 'v1',
  version_date: '{version}'
});
      

ConversationService service = new ConversationService("{version}");
service.setUsernameAndPassword("{username}", "{password}");
      

from watson_developer_cloud import ConversationV1

conversation = ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '{version}'
)
      

Versioning

API requests require a version parameter that takes a date in the format version=YYYY-MM-DD. Whenever we change the API in a backwards-incompatible way, we release a new minor version of the API.

Send the version parameter with every API request. The service uses the API version for the date you specify, or the most recent version before that date. Don't default to the current date. Instead, specify a date that matches a version that is compatible with your app, and don't change it until your app is ready for a later version.

The current version is 2017-05-26.

Workspaces

List workspaces

List the workspaces associated with a Conversation service instance.

GET /v1/workspaces
listWorkspaces(params, callback())
list_workspaces()

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
page_limit query integer The number of records to return in each page of results. The default page limit is 100.
include_count query boolean Whether to include information about the number of records returned.
sort query string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id.
cursor query string A token identifying the last object from the previous page of results.
Name Description
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id.
cursor string A token identifying the last object from the previous page of results.
Name Description
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id.
cursor string A token identifying the last object from the previous page of results.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

conversation.listWorkspaces(function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
 });
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.list_workspaces()

print(json.dumps(response, indent=2))
      

Response

Returns information about all workspaces associated with the service instance.

Name Description
workspaces An array of Workspace objects describing the workspaces associated with the service instance.
pagination A Pagination object defining the pagination data for the returned objects.
Workspace
Name Description
name string The name of the workspace.
language string The language of the workspace.
created string The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
workspace_id string The workspace ID.
description string The description of the workspace.
metadata object Any metadata related to the workspace.
learning_opt_out boolean Whether training data from the workspace can be used by IBM for general service improvements. Training data includes artifacts such as intents and entities. true indicates that workspace training data is not to be used.
Pagination
Name Description
refresh_url string The URL that will return the same page of results.
next_url string The URL that will return the next page of results, if any.
total integer Reserved for future use.
matched integer Reserved for future use.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "workspaces": [
    {
      "name": "Car_Dashboard",
      "created": "2016-07-13T12:26:55.781Z",
      "updated": "2016-11-29T21:46:38.969Z",
      "language": "en",
      "metadata": {
        "runtime_version": "2017-05-26"
      },
      "description": "Cognitive Car workspace which allows multi-turn conversations to perform tasks in the car.",
      "workspace_id": "0a0c06c1-8e31-4655-9067-58fcac5134fc",
      "learning_opt_out": false
    },
    {
      "name": "testing",
      "created": "2016-09-01T21:20:26.514Z",
      "updated": "2016-11-29T21:46:38.969Z",
      "language": "en",
      "metadata": {
        "runtime_version": "2017-05-26"
      },
      "description": null,
      "workspace_id": "e42c8e5c-eb34-4b65-99f0-59f9329b66ec",
      "learning_opt_out": false
    },
    {
      "name": "workspace-example",
      "created": "2016-07-11T17:06:57.089Z",
      "updated": "2016-11-29T21:46:38.969Z",
      "language": "en",
      "metadata": {
        "runtime_version": "2017-05-26"
      },
      "description": "Example workspace to try out the service",
      "workspace_id": "293b58fc-3c5b-4ac5-a8f4-8d52c393d875",
      "learning_opt_out": false
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces?version=2017-05-26"
  }
}
        

Create workspace

Create a workspace based on JSON input. You must provide JSON data defining the content of the new workspace.

This operation is limited to 30 requests per 30 minutes.

POST /v1/workspaces
createWorkspace(params, callback())

  
create_workspace(name=None, description=None, language=None, intents=None, entities=None, dialog_nodes=None, counterexamples=None, metadata=None)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace body json CreateWorkspace A CreateWorkspace object defining the content of the new workspace.
CreateWorkspace
Name Description
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
intents CreateIntent[ ] An array of objects defining the intents for the workspace.
entities CreateEntity[ ] An array of objects defining the entities for the workspace.
dialog_nodes DialogNode[ ] An array of objects defining the nodes in the workspace dialog.
counterexamples CreateCounterexample[ ] An array of objects defining input examples that have been marked as irrelevant input.
metadata object Any metadata related to the workspace.
learning_opt_out boolean Whether training data from the workspace can be used by IBM for general service improvements. Training data includes artifacts such as intents and entities. true indicates that workspace training data is not to be used.
Name Description
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
metadata object Any metadata related to the workspace.
entities CreateEntity[ ] An array of objects defining the entities for the workspace.
intents CreateIntent[ ] An array of objects defining the intents for the workspace.
dialog_nodes DialogNode[ ] An array of objects defining the nodes in the workspace dialog.
counterexamples CreateCounterexample[ ] An array of objects defining input examples that have been marked as irrelevant input.
Name Description
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
intents CreateIntent[ ] An array of objects defining the intents for the workspace.
entities CreateEntity[ ] An array of objects defining the entities for the workspace.
dialog_nodes DialogNode[ ] An array of objects defining the nodes in the workspace dialog.
counterexamples CreateCounterexample[ ] An array of objects defining input examples that have been marked as irrelevant input.
metadata object Any metadata related to the workspace.
CreateEntity
Name Description
entity string The name of the entity (for example, beverage).
description string The description of the entity.
metadata object Any metadata related to the entity.
values CreateValue[ ] An array of entity values.
fuzzy_match boolean Whether to use fuzzy matching for the entity.
CreateIntent
Name Description
intent string The name of the intent.
description string The description of the intent.
examples CreateExample[ ] An array of user input examples for the intent.
DialogNode
Name Description
dialog_node string The dialog node ID.
description string The description of the dialog node.
conditions string The condition that triggers the dialog node.
parent string The ID of the parent dialog node.
previous_sibling string The ID of the previous sibling dialog node.
output object The output from the dialog node.
context object The context (if defined) for the dialog node.
metadata object The metadata (if any) for the dialog node.
next_step DialogNodeNextStep The next step to execute following this dialog node.
created string The timestamp for creation of the dialog node.
updated string The timestamp for the most recent update to the dialog node.
actions DialogNodeAction[ ] Any actions to be invoked by the dialog node.
title string The alias used to identify the dialog node.
type string How the dialog node is processed (standard, event_handler, frame, slot, or response_condition).
event_name string How an event_handler node is processed.
variable string The location in the dialog context where output is stored.
CreateCounterexample
Name Description
text string The text of a user input example marked as irrelevant input.
CreateExample
Name Description
text string The text of a user input example.
CreateValue
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
patterns string[ ] An array containing patterns for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).
DialogNodeNextStep
Name Description
behavior string How the next_step node will be processed. Currently, the only valid value is jump_to.
dialog_node string The dialog node to process next.
selector string Which part of the dialog node to process next (condition, client, user_input, or body.
DialogNodeAction
Name Description
name string The name of the action.
type string The type of action to invoke (client or server).
parameters object A map of key/value pairs to be provided to the action. client, user_input, or body.
result_variable string The location in the dialog context where the result of the action is stored.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"name\":\"API test\",\"intents\":[],\"entities\":[],\"language\":\"en\",\"description\":\"Example workspace created via API.\",\"dialog_nodes\":[]}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var workspace = {
  name: 'API test',
  description: 'Example workspace created via API.'
};

conversation.createWorkspace(workspace, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
 });
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.create_workspace(
  name = 'API test',
  description = 'Example workspace created via API'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the workspace that was created.

Name Description
name string The name of the workspace.
language string The language of the workspace.
created string The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
workspace_id string The workspace ID.
description string The description of the workspace.
metadata object Any metadata that is required by the workspace.
learning_opt_out boolean Whether training data from the workspace can be used by IBM for general service improvements. Training data includes artifacts such as intents and entities. true indicates that workspace training data is not to be used.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 30 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "name": "API test",
  "created": "2017-01-31T18:02:19.070Z",
  "updated": "2017-01-31T18:02:19.070Z",
  "language": "en",
  "metadata": null,
  "description": "Example workspace created via API.",
  "workspace_id": "245edf96-b89f-46ac-b647-c6618b2eb5f0",
  "learning_opt_out": false
}
        

Delete workspace

Delete a workspace from the service instance.

This operation is limited to 30 requests per 30 minutes.

DELETE /v1/workspaces/{workspace_id}
deleteWorkspace(params, callback())

  
delete_workspace(workspace_id)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
Name Description
workspace_id string Unique identifier of the workspace.
Name Description
workspace_id string Unique identifier of the workspace.

Example request


curl -X DELETE -u "{username}":"{password}" --header "Accept: text/html" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/394927d3-bf81-40d8-8cb5-368a13f60fee?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '394927d3-bf81-40d8-8cb5-368a13f60fee'
};

conversation.deleteWorkspace(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.delete_workspace(
  workspace_id = '394927d3-bf81-40d8-8cb5-368a13f60fee'
)

print(json.dumps(response, indent=2))
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Rate limit

This operation is limited to 30 requests per 30 minutes. For more information, see Rate limiting.

Example response


{}
        

Get workspace

Get information about a workspace, optionally including all workspace content.

GET /v1/workspaces/{workspace_id}
getWorkspace(params, callback())
get_workspace(workspace_id, export=None)

  

Request

Name Description
workspace_id path string Unique identifier of the workspace.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
export query boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
Name Description
workspace_id string Unique identifier of the workspace.
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
Name Description
workspace_id string Unique identifier of the workspace.
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/394927d3-bf81-40d8-8cb5-368a13f60fee?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '394927d3-bf81-40d8-8cb5-368a13f60fee'
};

conversation.getWorkspace(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
   });
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.get_workspace(
  workspace_id = '394927d3-bf81-40d8-8cb5-368a13f60fee'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the workspace, including the workspace name, description, language, creation and update timestamps, and workspace ID. If the export parameter is true, the response also includes all workspace content (such as intents, entities, and dialog nodes) in JSON format.

Name Description
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
metadata object Any metadata that is required by the workspace.
created string The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
workspace_id string The workspace ID.
status string The current status of the workspace (Non Existent, Training, Failed, Available, or Unavailable).
intents IntentExport[ ] An array of objects describing the intents for the workspace.
entities EntityExport[ ] An array of objects describing the entities for the workspace.
counterexamples Counterexample[ ] An array of objects describing the user input examples that have been marked as irrelevant input.
dialog_nodes DialogNode[ ] An array of objects describing the dialog nodes for the workspace.
learning_opt_out boolean Whether training data from the workspace can be used by IBM for general service improvements. Training data includes artifacts such as intents and entities. true indicates that workspace training data is not to be used.
IntentExport
Name Description
intent string The name of the intent.
created string The timestamp for creation of the intent.
updated string The timestamp for the last update to the intent.
description string The description of the intent.
examples Example[ ] An array of objects describing the user input examples for the intent.
EntityExport
Name Description
entity string The name of the entity (for example, beverage).
created string The timestamp for creation of the entity.
updated string The timestamp for the last update to the entity.
description string The description of the entity.
metadata object Any metadata related to the entity.
fuzzy_match boolean Whether fuzzy matching is used for the entity.
values ValueExport[ ] An array of objects describing the entity values.
Counterexample
Name Description
text string The text of the user input example.
created string The timestamp for creation of the user input example.
updated string The timestamp for the last update to the user input example.
DialogNode
Name Description
dialog_node string The dialog node ID.
description string The description of the dialog node.
conditions string The condition that triggers the dialog node.
parent string The ID of the parent dialog node.
previous_sibling string The ID of the previous sibling dialog node.
output object The output from the dialog node.
context object The context (if defined) for the dialog node.
metadata object The metadata (if any) for the dialog node.
next_step DialogNodeNextStep The next step to execute following this dialog node.
created string The timestamp for creation of the dialog node.
updated string The timestamp for the most recent update to the dialog node.
actions DialogNodeAction[ ] Any actions to be invoked by the dialog node.
title string The alias used to identify the dialog node.
type string How the dialog node is processed (standard, event_handler, frame, slot, or response_condition).
event_name string How an event_handler node is processed.
variable string The location in the dialog context where output is stored.
Example
Name Description
text string The text of the example.
created string The timestamp for creation of the example.
updated string The timestamp for the last update to the example.
ValueExport
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
patterns string[ ] An array containing patterns for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).
DialogNodeNextStep
Name Description
behavior string How the next_step node will be processed. Currently, the only valid value is jump_to.
dialog_node string The dialog node to process next.
selector string Which part of the dialog node to process next (condition, client, user_input, or body.
DialogNodeAction
Name Description
name string The name of the action.
type string The type of action to invoke (client or server).
parameters object A map of key/value pairs to be provided to the action. client, user_input, or body.
result_variable string The location in the dialog context where the result of the action is stored.

Response codes

Status Description
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Rate limit

With export=false, this operation is limited to 6000 requests per 5 minutes. With export=true, the limit is 20 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "name": "API test",
  "created": "2017-02-01T15:28:10.145Z",
  "updated": "2017-02-01T15:28:10.145Z",
  "language": "en",
  "status": "Available",
  "metadata": null,
  "description": "Example workspace.",
  "workspace_id": "394927d3-bf81-40d8-8cb5-368a13f60fee",
  "learning_opt_out": false
}
        

Update workspace

Update an existing workspace with new or modified data. You must provide JSON data defining the content of the updated workspace.

Any elements included in the new JSON will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are included in the new JSON.) For example, if you update an entity, the previous version of the entity (including all of its values and synonyms) is discarded and replaced with the new version specified in the JSON input.

POST /v1/workspaces/{workspace_id}
updateWorkspace(params, callback())

  
update_workspace(workspace_id, name=None, description=None, language=None, intents=None, entities=None, dialog_nodes=None, counterexamples=None, metadata=None)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace_id path string Unique identifier of the workspace.
workspace body json UpdateWorkspace The JSON data defining the new and updated workspace content.
UpdateWorkspace
Name Description
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
intents CreateIntent[ ] An array of objects defining the intents for the workspace.
entities CreateEntity[ ] An array of objects defining the entities for the workspace.
dialog_nodes DialogNode[ ] An array of objects defining the nodes in the workspace dialog.
counterexamples CreateCounterexample[ ] An array of objects defining input examples that have been marked as irrelevant input.
metadata object Any metadata that is required by the workspace.
learning_opt_out boolean Whether training data from the workspace can be used by IBM for general service improvements. Training data includes artifacts such as intents and entities. true indicates that workspace training data is not to be used.
Name Description
workspace_id string Unique identifier of the workspace.
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
metadata object Any metadata that is required by the workspace.
entities CreateEntity[ ] An array of objects defining the entities for the workspace.
intents CreateIntent[ ] An array of objects defining the intents for the workspace.
dialog_nodes DialogNode[ ] An array of objects defining the nodes in the workspace dialog.
counterexamples CreateCounterexample[ ] An array of objects defining input examples that have been marked as irrelevant input.
Name Description
workspace_id string Unique identifier of the workspace.
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
intents CreateIntent[ ] An array of objects defining the intents for the workspace.
entities CreateEntity[ ] An array of objects defining the entities for the workspace.
dialog_nodes DialogNode[ ] An array of objects defining the nodes in the workspace dialog.
counterexamples CreateCounterexample[ ] An array of objects defining input examples that have been marked as irrelevant input.
metadata object Any metadata that is required by the workspace.
CreateEntity
Name Description
entity string The name of the entity (for example, beverage).
description string The description of the entity.
metadata object Any metadata related to the entity.
values CreateValue[ ] An array of entity values.
fuzzy_match boolean Whether to use fuzzy matching for the entity.
CreateIntent
Name Description
intent string The name of the intent.
description string The description of the intent.
examples CreateExample[ ] An array of user input examples for the intent.
DialogNode
Name Description
dialog_node string The dialog node ID.
description string The description of the dialog node.
conditions string The condition that triggers the dialog node.
parent string The ID of the parent dialog node.
previous_sibling string The ID of the previous sibling dialog node.
output object The output from the dialog node.
context object The context (if defined) for the dialog node.
metadata object The metadata (if any) for the dialog node.
next_step DialogNodeNextStep The next step to execute following this dialog node.
created string The timestamp for creation of the dialog node.
updated string The timestamp for the most recent update to the dialog node.
actions DialogNodeAction[ ] Any actions to be invoked by the dialog node.
title string The alias used to identify the dialog node.
type string How the dialog node is processed (standard, event_handler, frame, slot, or response_condition).
event_name string How an event_handler node is processed.
variable string The location in the dialog context where output is stored.
CreateCounterexample
Name Description
text string The text of a user input example marked as irrelevant input.
CreateExample
Name Description
text string The text of a user input example.
CreateValue
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
patterns string[ ] An array containing patterns for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).
DialogNodeNextStep
Name Description
behavior string How the next_step node will be processed. Currently, the only valid value is jump_to.
dialog_node string The dialog node to process next.
selector string Which part of the dialog node to process next (condition, client, user_input, or body.
DialogNodeAction
Name Description
name string The name of the action.
type string The type of action to invoke (client or server).
parameters object A map of key/value pairs to be provided to the action. client, user_input, or body.
result_variable string The location in the dialog context where the result of the action is stored.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"name\":\"API test\",\"intents\":[],\"entities\":[],\"language\":\"en\",\"description\":\"Example workspace updated via API.\",\"dialog_nodes\":[]}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/394927d3-bf81-40d8-8cb5-368a13f60fee?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '394927d3-bf81-40d8-8cb5-368a13f60fee',
  name: 'API test',
  description: 'Example workspace updated via API.'
};

conversation.updateWorkspace(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
   });
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.update_workspace(
  workspace_id = '394927d3-bf81-40d8-8cb5-368a13f60fee',
  name = 'Update Test',
  description = 'Example workspace updated via API.'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the workspace that was updated.

Name Description
name string The name of the workspace.
language string The language of the workspace.
created string The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
workspace_id string The workspace ID.
description string The description of the workspace.
metadata object Any metadata that is required by the workspace.
learning_opt_out boolean Whether training data from the workspace can be used by IBM for general service improvements. Training data includes artifacts such as intents and entities. true indicates that workspace training data is not to be used.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 30 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "name": "API test",
  "created": "2017-02-01T15:28:10.145Z",
  "updated": "2017-02-01T21:49:32.690Z",
  "language": "en",
  "metadata": null,
  "description": "Example workspace updated via API.",
  "workspace_id": "394927d3-bf81-40d8-8cb5-368a13f60fee",
  "learning_opt_out": false
}
        

Messages

Send message

Get a response to a user's input.

POST /v1/workspaces/{workspace_id}/message
message(params, callback())
ServiceCall<MessageResponse> message(MessageOptions messageOptions)
message(workspace_id, message_input=None, context=None, entities=None, intents=None, output=None, alternate_intents=False)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
message body json MessageRequest A MessageRequest object that provides the input text and optional context.
MessageRequest
Name Description
input InputData The user input.
alternate_intents boolean Whether to return more than one intent. Set to true to return all matching intents. For example, return all intents when the confidence is not high to allow users to choose their intent. The default value is false.
context Context State information for the conversation. To maintain state, include the Context object from the previous response when sending multiple requests for the same conversation.
entities RuntimeEntity[ ] Entities to use when evaluating the message. Include entities from the previous response to continue using those entities rather than detecting entities in the new input.
intents RuntimeIntent[ ] Intents to use when evaluating the user input. Include the intents from the previous response to continue using those intents rather than trying to recognize intents in the new input.
output OutputData System output. Include the output from the previous response to maintain intermediate informationif you have several requests within the same dialog turn.
Name Description
workspace_id string Unique identifier of the workspace.
input InputData The user input.
alternate_intents boolean Whether to return more than one intent. Default is false.

Set to true to return all matching intents. For example, return all intents when the confidence is not high to allow users to choose their intent.

context Context State information for the conversation. When you send multiple requests for the same conversation, include the Context object from the response.
entities RuntimeEntity[ ] The portion of the user's input that you can use to provide a different response or action to an intent. Include entities from the prevoius response when they do not need to change so that Watson does not try to identify them.
intents RuntimeIntent[ ] An array of name-confidence pairs for the user input. Include the intents from the request when they do not need to change so that Watson does not try to identify them.
output OutputData System output. Include the output from the request when you have several requests within the same dialog turn to pass back in the intermediate information.

Pass the parameters as a Java MessageOptions object with the messageOptions argument.

Name Description
alternateIntents boolean Whether to return more than one intent. Default is false.

Set to true to return all matching intents. For example, return all intents when the confidence is not high to allow users to choose their intent.

context Context State information for the conversation. When you send multiple requests for the same conversation, include the context from the response.
entities RuntimeEntity[ ] The portion of the user's input that you can use to provide a different response or action to an intent. Include the entities from the previous response when they do not need to change so that Watson does not try to identify them.
input InputData The user input.
intents RuntimeIntent[ ] An array of name-confidence pairs for the user input. Include the intents from the request when they do not need to change so that Watson does not try to identify them.
output OutputData System output. Include the output from the request when you have several requests within the same dialog turn to pass back in the intermediate information.
workspaceId string Unique identifier of the workspace.
Name Description
workspace_id string Unique identifier of the workspace.
message_input InputData The user input.
alternate_intentsboolean Whether to return more than one intent. Default is false.

Set to true to return all matching intents. For example, return all intents when the confidence is not high to allow users to choose their intent.

context Context State information for the conversation. When you send multiple requests for the same conversation, include the Context object from the response.
entities RuntimeEntity[ ] The portion of the user's input that you can use to provide a different response or action to an intent. Include entities from the previous response when they do not need to change so that Watson does not try to identify them.
intents RuntimeIntent[ ] An array of name-confidence pairs for the user input. Include the Intents from the request when they do not need to change so that Watson does not try to identify them.
output OutputData System output. Include the output from the request when you have several requests within the same dialog turn to pass back in the intermediate information.
InputData
Name Description
text string The text of the user input.
Context
Name Description
conversation_id string The unique identifier of the conversation.
system SystemResponse For internal use only.
RuntimeEntity
Name Description
entity string An entity detected in the input.
location integer[ ] An array of zero-based character offsets that indicate where the detected entity values begin and end in the input text.
value string The term in the input that was recognized as an entity value.
confidence number A decimal percentage that represents Watson's confidence in the entity.
metadata object Any metadata for the entity.
RuntimeIntent
Name Description
intent string The name of the recognized intent.
confidence number A decimal percentage that represents the confidence that Watson has in this intent. Higher values represent higher confidences.
OutputData
Name Description
log_messages LogMessage[ ] Up to 50 messages logged with the request. Returns an empty array if no messages are returned.
text string[ ] An array of responses to the user. Returns an empty array if no responses are returned.
nodes_visited string[ ] An array of the nodes that were triggered to create the response. This information is useful for debugging and for visualizing the path taken through the node tree.
LogMessage
Name Description
level string The severity of the message (info, error, or warn).
msg string The text of the log message.

Example request (Includes the context object returned with the previous response)


curl -X POST -u "{username}":"{password}" --header "Content-Type:application/json" --data "{\"input\": {\"text\": \"Hello\"}}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/message?version=2017-05-26"

Example request


var watson = require('watson-developer-cloud');

var conversation = watson.conversation({
  username: '{username}',
  password: '{password}',
  version: 'v1',
  version_date: '2017-05-26'
});

conversation.message({
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  input: {'text': 'Hello'}
},  function(err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});

Conversation service = new Conversation(Conversation.VERSION_DATE_2017_05_26);
service.setUsernameAndPassword("{username}",
                               "{password}");

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";

InputData input = new InputData.Builder("Hello").build();
MessageOptions options = new MessageOptions.Builder(workspaceId).input(input).build();

MessageResponse response = service.message(options).execute();

System.out.println(response);
      
import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2017-05-26'
)

response = conversation.message(
    workspace_id='9978a49e-ea89-4493-b33d-82298d3db20d',
    message_input={
        'text': 'Hello'
    }
)

print(json.dumps(response, indent=2))

Response

Returns the last user input, the recognized intents and entities, and the updated context and system output. The response can include properties that are added by dialog node output or by the client app.

Name Description
input MessageInput The user input from the request.
intents RuntimeIntent[ ] An array of intents recognized in the user input, sorted in descending order of confidence. Returns an empty array if no intents are recognized.
entities RuntimeEntity[ ] An array of entities identified in the user input. Returns an empty array if no entities are identified.
alternate_intents boolean Whether to return more than one intent. Included in the response only when sent with the request.
context Context State information for the conversation.
output OutputData Output from the dialog, including the response to the user, the nodes that were triggered, and log messages.
MessageInput
Name Description
text string The text of the user input.
RuntimeIntent
Name Description
intent string The name of the recognized intent.
confidence number A decimal percentage that represents the confidence that Watson has in this intent. Higher values represent higher confidences.
RuntimeEntity
Name Description
entity string The recognized entity.
location integer[ ] An array of zero-based character offsets that indicate where the detected entity values begin and end in the input text.
value string The term in the input that was recognized as an entity value.
confidence number A decimal percentage that represents Watson's confidence in the entity.
metadata object Any metadata for the entity.
Context
Name Description
conversation_id string The unique identifier of the conversation.
system SystemResponse For internal use only.
OutputData
Name Description
log_messages LogMessage[ ] Up to 50 messages logged with the request. Returns an empty array if no messages are returned.
text string[ ] An array of responses to the user. Returns an empty array if no responses are returned.
nodes_visited string[ ] An array of the nodes that were triggered to create the response. This information is useful for debugging and for visualizing the path taken through the node tree.
LogMessage
Name Description
level string The severity of the message (info, error, or warn).
msg string The text of the message.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Rate limit

There is no rate limit for this operation.

Example response


{
  "intents": [
    {
      "intent": "hello",
      "confidence": 0.8742280006408691
    }
  ],
  "entities": [],
  "input": {
    "text": "Hello"
  },
  "output": {
    "text": [
      "Hi! What can I do for you?"
    ],
    "nodes_visited": [
      "node_2_1501875253968"
    ],
    "log_messages": []
  },
  "context": {
    "conversation_id": "59aebcf9-3df2-4f85-8632-cf8e4c760260",
    "system": {
      "dialog_stack": [
        {
          "dialog_node": "root"
        }
      ],
      "dialog_turn_counter": 1,
      "dialog_request_counter": 1,
      "_node_output_map": {
        "node_2_1501875253968": [
          0
        ]
      },
      "branch_exited": true,
      "branch_exited_reason": "completed"
    }
  }
}
        

Counterexamples

List counterexamples

List the counterexamples for a workspace. Counterexamples are examples that have been marked as irrelevant input.

GET /v1/workspaces/{workspace_id}/counterexamples
getCounterExamples(params, callback())
list_counterexamples(workspace_id, page_limit=None, include_count=None, sort=None, cursor=None)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace_id path string Unique identifier of the workspace.
page_limit query integer The number of records to return in each page of results. The default page limit is 100.
include_count query boolean Whether to include information about the number of records returned.
sort query string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are text and updated.
cursor query string A token identifying the last object from the previous page of results.
Name Description
workspace_id string The workspace ID.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are text and updated.
cursor string A token identifying the last object from the previous page of results.
Name Description
workspace_id string The workspace ID.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are text and updated.
cursor string A token identifying the last object from the previous page of results.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d'
};

conversation.getCounterExamples(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.list_counterexamples(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about all counterexamples for the workspace.

Name Description
counterexamples An array of Counterexample objects describing the examples marked as irrelevant input.
pagination A Pagination object defining the pagination data for the returned objects.
Counterexample
Name Description
text string The text of the example.
created string The timestamp for creation of the example.
updated string The timestamp for the last update to the example.
Pagination
Name Description
refresh_url string The URL that will return the same page of results.
next_url string The URL that will return the next page of results, if any.
total integer Reserved for future use.
matched integer Reserved for future use.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "counterexamples": [
    {
      "text": "What are you wearing?",
      "created": "2017-03-07T19:02:33.513Z",
      "updated": "2017-03-07T19:02:33.513Z"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples?version=2017-05-26"
  }
}
        

Create counterexample

Add a new counterexample to a workspace. Counterexamples are examples that have been marked as irrelevant input.

POST /v1/workspaces/{workspace_id}/counterexamples
createCounterExample(params, callback())
create_counterexample(workspace_id, text)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace_id path string Unique identifier of the workspace.
counterexample body json CreateCounterexample A CreateCounterexample object defining the content of the new user input example to be marked as irrelevant input.
CreateCounterexample
Name Description
text string The text of a user input example to be marked as irrelevant input.
Name Description
workspace_id string Unique identifier of the workspace.
text string The text of a user input example to be marked as irrelevant input.
Name Description
workspace_id string Unique identifier of the workspace.
text string The text of a user input example to be marked as irrelevant input.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"text\":\"Make me a sandwich\"}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  text: 'Make me a sandwich'
};

conversation.createCounterExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.create_counterexample(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  text = 'Make me a sandwich'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the counterexample.

Name Description
text string The text of the counterexample.
created string The timestamp for creation of the counterexample.
updated string The timestamp for the last update to the counterexample.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "text": "Make me a sandwich",
  "created": "2017-03-07T20:13:33.850Z",
  "updated": "2017-03-07T20:13:33.850Z"
}
        

Delete counterexample

Delete a counterexample from a workspace. Counterexamples are examples that have been marked as irrelevant input.

DELETE /v1/workspaces/{workspace_id}/counterexamples/{text}
deleteCounterExample(params, callback())

  
delete_counterexample(workspace_id, text)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
text path string The text of a user input counterexample, with spaces and special characters in URL encoding.
workspace_id path string Unique identifier of the workspace.
Name Description
workspace_id string Unique identifier of the workspace.
text string The text of a user input counterexample.
Name Description
workspace_id string Unique identifier of the workspace.
text string The text of a user input counterexample.

Example request


curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples/Make%20me%20a%20sandwich?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  text: 'Make me a sandwich'
};

conversation.deleteCounterExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.delete_counterexample(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  text = 'Make me a sandwich'
)

print(json.dumps(response, indent=2))
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{}
        

Get counterexample

Get information about a counterexample. Counterexamples are examples that have been marked as irrelevant input.

GET /v1/workspaces/{workspace_id}/counterexamples/{text}
getCounterExample(params, callback())

  
get_counterexample(workspace_id, text)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
text path string The text of the user input example, with spaces and special characters in URL encoding.
workspace_id path string Unique identifier of the workspace.
Name Description
workspace_id string Unique identifier of the workspace.
text string The text of the user input example.
Name Description
workspace_id string Unique identifier of the workspace.
text string The text of the user input example.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples/What%20are%20you%20wearing%3F?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  text: 'What are you wearing?'
};

conversation.getCounterExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.get_counterexample(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  text = 'What are you wearing?'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the counterexample, including the example text and creation and update timestamps.

Name Description
text string The text of the counterexample.
created string The timestamp for creation of the user input example.
updated string The timestamp for the last update to the user input example.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Example response


{
  "text": "What are you wearing?",
  "created": "2017-03-07T19:02:33.513Z",
  "updated": "2017-03-07T19:02:33.513Z"
}
        

Update counterexample

Update the text of a counterexample. Counterexamples are examples that have been marked as irrelevant input.

POST /v1/workspaces/{workspace_id}/counterexamples/{text}
updateCounterExample(params, callback())
update_counterexample(workspace_id, text, new_text=None)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
text path string The current text of the counterexample, with spaces and special characters in URL encoding.
workspace_id path string Unique identifier of the workspace.
counterexample body json UpdateExample An UpdateCounterexample object defining the new text for the counterexample.
UpdateCounterexample
Name Description
text string The updated text for the counterexample.
Name Description
workspace_id string Unique identifier of the workspace.
old_text string The current text of the counterexample.
text string The updated text for the counterexample.
Name Description
workspace_id string Unique identifier of the workspace.
text string The current text of the counterexample.
new_text string The updated text for the counterexample.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"text\":\"Make me a cheeseburger!\"}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples/Make%20me%20a%20sandwich?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  old_text: 'Make me a sandwich',
  text: 'Make me a cheeseburger!'
};

conversation.updateCounterExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.update_counterexample(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  text = 'Make me a sandwich',
  new_text = 'Make me a cheeseburger!'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the counterexample that was updated.

Name Description
text string The text of the counterexample.
created string The timestamp for creation of the counterexample.
updated string The timestamp for the last update to the counterexample.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "text": "Make me a cheeseburger!",
  "created": "2017-03-07T20:36:48.681Z",
  "updated": "2017-03-07T21:09:46.047Z"
}
        

Entities

List entities

List the entities for a workspace.

GET /v1/workspaces/{workspace_id}/entities
getEntities(params, callback())
list_entities(workspace_id, export=None, page_limit=None, include_count=None, sort=None, cursor=None)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace_id path string Unique identifier of the workspace.
export query boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
page_limit query integer The number of records to return in each page of results. The default page limit is 100.
include_count query boolean Whether to include information about the number of records returned.
sort query string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are entity and updated.
cursor query string A token identifying the last object from the previous page of results.
Name Description
workspace_id string The workspace ID.
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are entity and updated.
cursor string A token identifying the last object from the previous page of results.
Name Description
workspace_id string The workspace ID.
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are entity and updated.
cursor string A token identifying the last object from the previous page of results.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d'
};

conversation.getEntities(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.list_entities(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about all entities defined for the workspace.

Name Description
entities An array of EntityExport objects describing the entities defined for the workspace.
pagination A Pagination object defining the pagination data for the returned objects.
EntityExport
Name Description
entity string The name of the entity (for example, beverage).
created string The timestamp for creation of the entity.
updated string The timestamp for the last update to the entity.
description string The description of the entity.
metadata object Any metadata related to the entity.
fuzzy_match boolean Whether fuzzy matching is used for the entity.
values ValueExport[ ] An array of objects describing the entity values.
Pagination
Name Description
refresh_url string The URL that will return the same page of results.
next_url string The URL that will return the next page of results, if any.
total integer Reserved for future use.
matched integer Reserved for future use.
ValueExport
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
patterns string[ ] An array containing patterns for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

With export=false, this operation is limited to 1000 requests per 30 minutes. With export=true, the limit is 200 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "entities": [
    {
      "entity": "animal",
      "created": "2017-04-10T14:36:49.177Z",
      "updated": "2017-04-10T14:36:49.177Z",
      "metadata": null,
      "description": null
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/entities?version=2017-05-26"
  }
}
        

Create entity

Create a new entity.

POST /v1/workspaces/{workspace_id}/entities
createEntity(params, callback())
create_entity(workspace_id, entity, description=None, metadata=None, values=None, fuzzy_match=None)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace_id string The workspace ID.
entity body json CreateEntity A CreateEntity object defining the content of the new entity.
CreateEntity
Name Description
entity string The name of the entity (for example, beverage).
description string The description of the entity.
metadata object Any metadata related to the entity.
values CreateValue[ ] An array of entity values.
fuzzy_match boolean Whether to use fuzzy matching for the entity.
Name Description
workspace_id string The workspace ID.
entity string The name of the entity (for example, beverage).
description string The description of the entity.
metadata object Any metadata related to the entity.
fuzzy_match boolean Whether to use fuzzy matching for the entity.
values CreateValue[ ] An array of entity values.
Name Description
workspace_id string The workspace ID.
entity string The name of the entity (for example, beverage).
description string The description of the entity.
metadata object Any metadata related to the entity.
values CreateValue[ ] An array of entity values.
fuzzy_match boolean Whether to use fuzzy matching for the entity.
CreateValue
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
patterns string[ ] An array containing patterns for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"entity\": \"beverage\",\"values\":[{\"value\":\"water\"},{\"value\":\"orange juice\"},{\"value\":\"soda\"}]}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  values: [
    {
      value: 'water'
    },
    {
      value: 'orange juice'
    },
    {
      value: 'soda'
    }
  ]
};

conversation.createEntity(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.create_entity(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage',
  values = [
    {'value': 'water'},
    {'value': 'orange juice'},
    {'value': 'soda'}
  ]
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the entity that was created.

Name Description
entity string The name of the entity (for example, beverage).
created string The timestamp for creation of the entity.
updated string The timestamp for the last update to the entity.
description string The description of the entity.
metadata object Any metadata related to the entity.
fuzzy_match boolean Whether fuzzy matching is used for the entity.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "entity": "beverage",
  "created": "2017-04-12T15:10:34.037Z",
  "updated": "2017-04-12T15:10:34.037Z",
  "metadata": null,
  "description": null
}
        

Delete entity

Delete an entity from a workspace.

DELETE /v1/workspaces/{workspace_id}/entities/{entity}
deleteEntity(params, callback())
delete_entity(workspace_id, entity)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
entity path string The name of the entity (for example, beverage).
workspace_id path string Unique identifier of the workspace.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).

Example request


curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage'
};

conversation.deleteEntity(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.delete_entity(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage'
)

print(json.dumps(response, indent=2))
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{}
        

Get entity

Get information about an entity, optionally including all entity content.

GET /v1/workspaces/{workspace_id}/entities/{entity}
getEntity(params, callback())
get_entity(workspace_id, entity, export=None)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
entity path string The name of the entity (for example, beverage).
workspace_id path string Unique identifier of the workspace.
export query boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage'
};

conversation.getEntity(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.get_entity(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the entity, including the entity name, description, and creation and update timestamps. If the export parameter is true, the response also includes all entity content (such as values and synonyms).

Name Description
entity string The name of the entity (for example, beverage).
created string The timestamp for creation of the entity.
updated string The timestamp for the last update to the entity.
description string The description of the entity.
metadata object Any metadata related to the entity.
fuzzy_match boolean Whether fuzzy matching is used for the entity.
values ValueExport[ ] An array of objects describing the entity values.
ValueExport
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
patterns string[ ] An array containing patterns for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).

Response codes

Status Description
400 Bad Request Invalid request

Rate limit

With export=false, this operation is limited to 6000 requests per 5 minutes. With export=true, the limit is 200 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "entity": "beverage",
  "created": "2017-04-12T15:12:48.445Z",
  "updated": "2017-04-12T15:12:48.445Z",
  "metadata": null,
  "description": null
}
        

Update entity

Update an existing entity with new or modified data. You must provide JSON data defining the content of the updated entity.

Any elements included in the new JSON will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are included in the new JSON.) For example, if you update the values for an entity, the previously existing values are discarded and replaced with the new values specified in the JSON input.

POST /v1/workspaces/{workspace_id}/entities/{entity}
updateEntity(params, callback())
update_entity(workspace_id, entity, new_entity=None, new_description=None, new_metadata=None, new_fuzzy_match=None, new_values=None)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
entity path string The name of the entity to update.
workspace_id path string The workspace ID.
new_entity body json UpdateEntity An UpdateEntity object defining the updated content of the entity.
UpdateEntity
Name Description
entity string The name of the entity (for example, beverage).
description string The description of the entity.
metadata object Any metadata related to the entity.
fuzzy_match boolean Whether to use fuzzy matching for the entity.
values CreateValue[ ] An array of entity values.
Name Description
workspace_id path string The workspace ID.
old_entity string The name of the entity to update.
entity string The updated name of the entity (for example, beverage).
description string The updated description of the entity.
metadata object Updated metadata related to the entity.
fuzzy_match boolean Whether to use fuzzy matching for the entity.
values CreateValue[ ] An array of entity values.
Name Description
workspace_id path string The workspace ID.
entity string The name of the entity to update.
new_entity string The updated name of the entity (for example, beverage).
new_description string The updated description of the entity.
new_metadata object Updated metadata related to the entity.
new_fuzzy_match boolean Whether to use fuzzy matching for the entity.
new_values CreateValue[ ] An array of entity values.
CreateValue
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
patterns string[ ] An array containing patterns for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"description\":\"Liquid refreshment\"}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  old_entity: 'beverage',
  entity: 'beverage',
  description: 'Liquid refreshment'
};

conversation.updateEntity(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.update_entity(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage',
  new_description = 'Liquid refreshment'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the entity that was updated.

Name Description
entity string The name of the entity (for example, beverage).
created string The timestamp for creation of the entity.
updated string The timestamp for the last update to the entity.
description string The description of the entity.
metadata object Any metadata related to the entity.
fuzzy_match boolean Whether fuzzy matching is used for the entity.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "entity": "beverage",
  "created": "2017-04-12T14:51:52.508Z",
  "updated": "2017-04-12T14:53:38.687Z",
  "metadata": null,
  "description": "Liquid refreshment"
}
        

Values

List entity values

List the values for an entity.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values
getValues(params, callback())
list_values(workspace_id, entity, export=None, page_limit=None, include_count=None, sort=None, cursor=None)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
entity path string The name of the entity (for example, beverage).
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
export query boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
page_limit query integer The number of records to return in each page of results. The default page limit is 100.
include_count query boolean Whether to include information about the number of records returned.
sort query string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are value and updated.
cursor query string A token identifying the last object from the previous page of results.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are value and updated.
cursor string A token identifying the last object from the previous page of results.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are value and updated.
cursor string A token identifying the last object from the previous page of results.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage'
};

conversation.getValues(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.list_values(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about all values defined for the specified entity.

Name Description
values ValueExport[ ] An array of entity values.
pagination A Pagination object defining the pagination data for the returned objects.
ValueExport
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
patterns string[ ] An array containing patterns for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).
Pagination
Name Description
refresh_url string The URL that will return the same page of results.
next_url string The URL that will return the next page of results, if any.
total integer Reserved for future use.
matched integer Reserved for future use.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "values": [
    {
      "type": "synonyms",
      "value": "orange juice",
      "created": "2017-03-22T15:01:30.947Z",
      "updated": "2017-03-22T15:01:30.947Z",
      "metadata": null
    },
    {
      "type": "synonyms",
      "value": "soda",
      "created": "2017-03-22T15:01:30.947Z",
      "updated": "2017-03-22T15:01:30.947Z",
      "metadata": null
    },
    {
      "type": "synonyms",
      "value": "water",
      "created": "2017-03-22T15:01:30.947Z",
      "updated": "2017-03-22T15:01:30.947Z",
      "metadata": null
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values?version=2017-05-26"
  }
}
        

Add entity value

Add a new value to an entity.

POST /v1/workspaces/{workspace_id}/entities/{entity}/values
createValue(params, callback())
create_value(workspace_id, entity, value, metadata=None, synonyms=None)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
entity path string The name of the entity (for example, beverage).
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
value body json CreateValue A CreateValue object defining the new entity value.
CreateValue
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
patterns string[ ] An array containing patterns for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"value\":\"beer\"}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'beer'
};

conversation.createValue(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.create_value(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage',
  value = 'beer'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the entity value that was added.

Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "type": "synonyms",
  "value": "beer",
  "created": "2017-03-22T16:31:05.199Z",
  "updated": "2017-03-22T16:31:05.199Z",
  "metadata": null
}
        

Delete entity value

Delete a value from an entity.

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
deleteValue(params, callback())

  
delete_value(workspace_id, entity, value)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
entity path string The name of the entity (for example, beverage).
value path string The text of the entity value, with spaces and special characters in URL encoding.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.

Example request


curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/orange%20juice?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'orange juice'
};

conversation.deleteValue(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.delete_value(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage',
  value = 'orange juice'
)

print(json.dumps(response, indent=2))
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{}
        

Get entity value

Get information about an entity value.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
getValue(params, callback())

  
get_value(workspace_id, entity, value, export=None)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
entity path string The name of the entity (for example, beverage).
value path string The text of the entity value, with spaces and special characters in URL encoding.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
export query boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/orange%20juice?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'orange juice'
};

conversation.getValue(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.get_value(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage',
  value = 'orange juice'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the entity value, including the value text and creation and update timestamps. If the export parameter is true, the response also includes any synonyms for the entity value.

Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
patterns string[ ] An array containing patterns for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Example response


{
  "type": "synonyms",
  "value": "orange juice",
  "created": "2017-03-22T19:30:04.856Z",
  "updated": "2017-03-22T19:30:04.856Z",
  "metadata": null
}
        

Update entity value

Update an existing entity value with new or modified data. You must provide JSON data defining the content of the updated entity value.

Any elements included in the new JSON will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are included in the new JSON.) For example, if you update the synonyms for an entity value, the previously existing synonyms are discarded and replaced with the new synonyms specified in the JSON input.

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
updateValue(params, callback())
update_value(workspace_id, entity, value, new_value=None, new_metadata=None, new_synonym=None)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
entity path string The name of the entity (for example, beverage).
value path string The current text of the entity value, with spaces and special characters in URL encoding.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
new_value body json UpdateValue An UpdateValue object defining the updated content for the entity value.
UpdateValue
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
old_value string The current text of the entity value.
value string The updated text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The current text of the entity value.
new_value string The updated text of the entity value.
new_metadata object Any metadata related to the entity value.
new_synonyms string[ ] An array containing any synonyms for the entity value.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"synonyms\":[\"pop\",\"soft drink\"]}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/soda?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  old_value: 'soda',
  value: 'soda',
  synonyms: [
    'pop',
    'soft drink'
  ]
};

conversation.updateValue(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.update_value(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage',
  value = 'soda',
  new_synonyms = ['pop', 'soft drink']
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the entity value that was updated.

Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "type": "synonyms",
  "value": "soda",
  "created": "2017-03-23T15:13:58.834Z",
  "updated": "2017-03-23T15:13:58.834Z",
  "metadata": null
}
        

Synonyms

List synonyms

List the synonyms for an entity value.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms
getSynonyms(params, callback())
list_synonyms(workspace_id, entity, value, page_limit=None, include_count=None, sort=None, cursor=None)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
entity path string The name of the entity (for example, beverage).
value path string The text of the entity value, with spaces and special characters in URL encoding.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
page_limit query integer The number of records to return in each page of results. The default page limit is 100.
include_count query boolean Whether to include information about the number of records returned.
sort query string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are synonym and updated.
cursor query string A token identifying the last object from the previous page of results.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are synonym and updated.
cursor string A token identifying the last object from the previous page of results.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are synonym and updated.
cursor string A token identifying the last object from the previous page of results.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/soda/synonyms?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

const params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'soda'
};

conversation.getSynonyms(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.list_synonyms(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage',
  value = 'soda'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about all synonyms defined for the specified entity value.

Name Description
synonyms Synonym[ ] An array of synonyms.
pagination A Pagination object defining the pagination data for the returned objects.
Synonym
Name Description
synonym string The text of the synonym.
created string The timestamp for the creation of the synonym.
updated string The timestamp for the last update to the synonym.
Pagination
Name Description
refresh_url string The URL that will return the same page of results.
next_url string The URL that will return the next page of results, if any.
total integer Reserved for future use.
matched integer Reserved for future use.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "synonyms": [
    {
      "created": "2017-04-12T14:58:09.029Z",
      "synonym": "pop",
      "updated": "2017-04-12T14:58:09.029Z"
    },
    {
      "created": "2017-04-12T14:58:09.029Z",
      "synonym": "soft drink",
      "updated": "2017-04-12T14:58:09.029Z"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/entities/beverage/values/soda/synonyms?version=2017-05-26"
  }
}
        

Add synonym

Add a new synonym to an entity value.

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms
createSynonym(params, callback())
create_synynonym(workspace_id, entity, value, synonym)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
entity path string The name of the entity (for example, beverage).
value path string The text of the entity value, with spaces and special characters in URL encoding.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
synonym body json CreateSynonym A CreateSynonym object defining the new synonym.
CreateSynonym
Name Description
synonym string The text of the synonym.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
synonym string The text of the synonym.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
synonym string The text of the synonym.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"synonym\":\"OJ\"}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/orange%20juice/synonyms?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'orange juice',
  synonym: 'OJ'
};

conversation.createSynonym(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.create_synonym(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage',
  value = 'orange juice',
  synonym = 'OJ'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the synonym that was added.

Name Description
synonym string The text of the synonym.
created string The timestamp for the creation of the synonym.
updated string The timestamp for the last update to the synonym.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "created": "2017-04-12T15:02:29.188Z",
  "synonym": "OJ",
  "updated": "2017-04-12T15:02:29.188Z"
}
        

Delete synonym

Delete a synonym from an entity value.

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
deleteSynonym(params, callback())

  
delete_synonym(workspace_id, entity, value, synonym)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
entity path string The name of the entity (for example, beverage).
value path string The text of the entity value, with spaces and special characters in URL encoding.
synonym path string The text of the synonym, with spaces and special characters in URL encoding.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
synonym string The text of the synonym.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
synonym string The text of the synonym.

Example request


curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/orange%20juice/synonyms/OJ?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'orange juice',
  synonym: 'OJ'
};

conversation.deleteSynonym(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.delete_synonym(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage',
  value = 'orange juice',
  synonym = 'OJ'
)

print(json.dumps(response, indent=2))
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{}
        

Get synonym

Get information about a synonym of an entity value.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
getSynonym(params, callback())

  
get_synonym(workspace_id, entity, value, synonym)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
entity path string The name of the entity (for example, beverage).
value path string The text of the entity value, with spaces and special characters in URL encoding.
synonym path string The text of the synonym, with spaces and special characters in URL encoding.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
synonym string The text of the synonym.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
synonym string The text of the synonym.

Example request


@curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/orange%20juice/synonyms/OJ?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'orange juice',
  synonym: 'OJ'
};

conversation.getSynonym(params, function(err, response) {
  if (err) {
      console.error(err);
  } else {
      console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.get_synonym(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage',
  value = 'orange juice',
  synonym = 'OJ'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the synonym, including the synonym text and creation and update timestamps.

Name Description
synonym string The text of the synonym.
created string The timestamp for the creation of the synonym.
updated string The timestamp for the last update to the synonym.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Example response


{
  "created": "2017-04-12T15:05:45.662Z",
  "synonym": "OJ",
  "updated": "2017-04-12T15:05:45.662Z"
}
        

Update synonym

Update an existing entity value synonym with new text.

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
updateSynonym(params, callback())
update_synonym(workspace_id, entity, value, synonym, new_synonym=None)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
entity path string The name of the entity (for example, beverage).
value path string The text of the entity value, with spaces and special characters in URL encoding.
synonym path string The current text of the synonym, with spaces and special characters in URL encoding.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
new_synonym body json UpdateSynonym An UpdateSynonym object defining the new synonym text.
UpdateSynonym
Name Description
synonym string The updated text of the synonym.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
old_synonym string The current text of the synonym.
synonym string The updated text of the synonym.
Name Description
workspace_id string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
synonym string The current text of the synonym.
new_synonym string The updated text of the synonym.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"synonym\":\"O.J.\"}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/orange%20juice/synonyms/OJ?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'orange juice',
  old_synonym: 'OJ',
  synonym: 'O.J.'        };

conversation.updateSynonym(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.update_synonym(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity = 'beverage',
  value = 'orange juice',
  synonym = 'OJ',
  new_synonym = 'O.J.'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the synonym that was updated.

Name Description
synonym string The text of the synonym.
created string The timestamp for the creation of the synonym.
updated string The timestamp for the last update to the synonym.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "created": "2017-04-12T15:05:45.662Z",
  "synonym": "O.J.",
  "updated": "2017-04-12T15:06:50.408Z"
}
        

Intents

List intents

List the intents for a workspace.

GET /v1/workspaces/{workspace_id}/intents
getIntents(params, callback())
list_intents(workspace_id, export=None, page_limit=None, include_count=None, sort=None, cursor=None)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace_id string The workspace ID.
export query boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
page_limit query integer The number of records to return in each page of results. The default page limit is 100.
include_count query boolean Whether to include information about the number of records returned.
sort query string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are intent and updated.
cursor query string A token identifying the last object from the previous page of results.
Name Description
workspace_id string The workspace ID.
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are intent and updated.
cursor string A token identifying the last object from the previous page of results.
Name Description
workspace_id string The workspace ID.
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are intent and updated.
cursor string A token identifying the last object from the previous page of results.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d'
};

conversation.getIntents(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.list_intents(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about all intents defined for the workspace.

Name Description
intents An array of IntentExport objects describing the intents defined for the workspace.
pagination A Pagination object defining the pagination data for the returned objects.
IntentExport
Name Description
intent string The name of the intent.
created string The timestamp for creation of the intent.
updated string The timestamp for the last update to the intent.
description string The description of the intent.
examples Example[ ] An array of objects describing the user input examples for the intent.
Pagination
Name Description
refresh_url string The URL that will return the same page of results.
next_url string The URL that will return the next page of results, if any.
total integer Reserved for future use.
matched integer Reserved for future use.
Example
Name Description
text string The text of the example.
created string The timestamp for creation of the example.
updated string The timestamp for the last update to the example.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

With export=false, this operation is limited to 2000 requests per 30 minutes. With export=true, the limit is 400 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "intents": [
    {
      "intent": "goodbye",
      "created": "2017-08-18T18:09:36.155Z",
      "updated": "2017-08-18T18:09:41.755Z",
      "description": null
    },
    {
      "intent": "hello",
      "created": "2017-08-18T18:05:48.153Z",
      "updated": "2017-08-18T18:06:06.004Z",
      "description": null
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents?version=2017-08-21"
  }
}
        

Create intent

Create a new intent.

POST /v1/workspaces/{workspace_id}/intents
createIntent(params, callback())
create_intent(workspace_id, intent, description=None, examples=None)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace_id string The workspace ID.
intent body json CreateIntent A CreateIntent object defining the content of the new intent.
CreateIntent
Name Description
intent string The name of the intent.
description string The description of the intent.
examples CreateExample[ ] An array of user input examples for the intent.
Name Description
workspace_id string The workspace ID.
intent string The name of the intent.
description string The description of the intent.
examples CreateExample[ ] An array of user input examples for the intent.
Name Description
workspace_id string The workspace ID.
intent string The name of the intent.
description string The description of the intent.
examples CreateExample[ ] An array of user input examples for the intent.
CreateExample
Name Description
text string The text of a user input example.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"intent\":\"hello\",\"examples\":[{\"text\":\"Good morning\"},{\"text\":\"Hi there\"}]}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  examples: [
    {
      text: 'Good morning'
    },
    {
      text: 'Hi there'
    }
  ]
};

conversation.createIntent(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.create_intent(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent = 'hello',
  examples = [
    {'text': 'Good morning'},
    {'text': 'Hi there'}
  ]
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the intent that was created.

Name Description
intent string The name of the intent.
created string The timestamp for creation of the intent.
updated string The timestamp for the last update to the intent.
description string The description of the intent.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 2000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "intent": "hello",
  "created": "2017-02-16T18:36:31.809Z",
  "updated": "2017-02-16T18:36:31.809Z",
  "description": null
}
        

Delete intent

Delete an intent from a workspace.

DELETE /v1/workspaces/{workspace_id}/intents/{intent}
deleteIntent(params, callback())

  
delete_intent(workspace_id, intent)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
intent path string The intent name (for example, pizza_order).
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).

Example request


curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello'
};

conversation.deleteIntent(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.delete_intent(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent = 'hello'
)

print(json.dumps(response, indent=2))
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 2000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{}
        

Get intent

Get information about an intent, optionally including all intent content.

GET /v1/workspaces/{workspace_id}/intents/{intent}
getIntent(params, callback())

  
workspace_id, intent, export=None

Request

Name Description
workspace_id path string Unique identifier of the workspace.
intent path string The intent name (for example, pizza_order).
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
export query boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
export boolean Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included. The default value is false.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello'
};

conversation.getIntent(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.get_intent(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent = 'hello'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the intent, including the intent name, description, and creation and update timestamps. If the export parameter is true, the response also includes all intent content (such as user input examples).

Name Description
intent string The name of the intent.
created string The timestamp for creation of the intent.
updated string The timestamp for the last update to the intent.
description string The description of the intent.
examples Example[ ] An array of objects describing the user input examples for the intent.
Example
Name Description
text string The text of the user input example.
created string The timestamp for creation of the user input example.
updated string The timestamp for the last update to the user input example.

Response codes

Status Description
400 Bad Request Invalid request

Rate limit

With export=false, this operation is limited to 6000 requests per 5 minutes. With export=true, the limit is 400 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "intent": "hello",
  "created": "2017-02-16T22:08:13.352Z",
  "updated": "2017-02-16T22:08:13.352Z",
  "description": null
}
        

Update intent

Update an existing intent with new or modified data. You must provide JSON data defining the content of the updated intent.

Any elements included in the new JSON will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are included in the new JSON.) For example, if you update the user input examples for an intent, the previously existing examples are discarded and replaced with the new examples specified in the JSON input.

POST /v1/workspaces/{workspace_id}/intents/{intent}
updateIntent(params, callback())
update_intent(workspace_id, intent, new_intent=None, new_description=None, new_examples=None)

Request

Name Description
workspace_id path string The workspace ID.
intent path string The name of the intent to update.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
new_intent body json UpdateIntent An UpdateIntent object defining the updated content of the intent.
UpdateIntent
Name Description
intent string The name of the intent.
description string The description of the intent.
examples CreateExample[ ] An array of user input examples for the intent.
Name Description
workspace_id string The workspace ID.
old_intent string The name of the intent to update.
intent string The updated name of the intent.
description string The updated description of the intent.
examples CreateExample[ ] An array of user input examples for the intent.
Name Description
workspace_id string The workspace ID.
intent string The name of the intent to update.
new_intent string The updated name of the intent.
new_description string The updated description of the intent.
new_examples CreateExample[ ] An array of user input examples for the intent.
CreateExample
Name Description
text string The text of a user input example.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"intent\":\"hello\",\"examples\":[{\"text\":\"Good afternoon\"}],\"description\":\"Updated intent\"}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  old_intent: 'hello',
  intent: 'hello',
  examples: [
    {
      text: 'Good afternoon'
    }
  ],
  description: 'Updated intent'
};

conversation.updateIntent(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.update_intent(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent = 'hello',
  new_examples = [
    {'text': 'Good afternoon'}
  ],
  new_description = 'Updated intent'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the intent that was updated.

Name Description
intent string The name of the intent.
created string The timestamp for creation of the intent.
updated string The timestamp for the last update to the intent.
description string The description of the intent.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 2000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "intent": "hello",
  "created": "2017-02-16T22:08:13.352Z",
  "updated": "2017-02-16T22:41:45.400Z",
  "description": "Updated intent"
}
        

Examples

List examples

List the user input examples for an intent.

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples
getExamples(params, callback())
list_examples(workspace_id, intent, page_limit=None, include_count=None, sort=None, cursor=None)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
intent path string The intent name (for example, pizza_order).
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
page_limit query integer The number of records to return in each page of results. The default page limit is 100.
include_count query boolean Whether to include information about the number of records returned.
sort query string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are text and updated.
cursor query string A token identifying the last object from the previous page of results.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are text and updated.
cursor string A token identifying the last object from the previous page of results.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
page_limit integer The number of records to return in each page of results. The default page limit is 100.
include_count boolean Whether to include information about the number of records returned.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are text and updated.
cursor string A token identifying the last object from the previous page of results.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?version=2017-05-26&export=true"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

const params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello'
};

conversation.getExamples(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.list_examples(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent = 'hello'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about all user input examples defined for the specified intent.

Name Description
examples An array of Example objects describing the examples defined for the intent.
pagination A Pagination object defining the pagination data for the returned objects.
Example
Name Description
text string The text of the user input example.
created string The timestamp for creation of the user input example.
updated string The timestamp for the last update to the user input example.
Pagination
Name Description
refresh_url string The URL that will return the same page of results.
next_url string The URL that will return the next page of results, if any.
total integer Reserved for future use.
matched integer Reserved for future use.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "examples":[
    {
      "text": "Good afternoon",
      "created": "2017-02-16T22:41:45.400Z",
      "updated": "2017-02-16T22:41:45.400Z"
    },
    {
      "text": "hi there",
      "created": "2017-02-20T19:00:03.160Z",
      "updated": "2017-02-20T19:00:03.160Z"
    }
  ],
  "pagination":{
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?version=2017-05-26&export=true"
  }
}
        

Create example

Add a new user input example to an intent.

POST /v1/workspaces/{workspace_id}/intents/{intent}/examples
createExample(params, callback())
create_example(workspace_id, intent, text)

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
intent path string The intent name (for example, pizza_order).
workspace_id path string Unique identifier of the workspace.
example body json CreateExample A CreateExample object defining the content of the new user input example.
CreateExample
Name Description
text string The text of a user input example.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
text string The text of the new user input example.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
text string The text of the new user input example.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"text\":\"Howdy!\"}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  text: 'Howdy!'
};

conversation.createExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.create_example(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent = 'hello',
  text = 'Howdy!'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the user input example that was added.

Name Description
text string The text of the user input example.
created string The timestamp for creation of the user input example.
updated string The timestamp for the last update to the user input example.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "text": "Howdy!",
  "created": "2017-02-20T21:19:42.210Z",
  "updated": "2017-02-20T21:19:42.210Z"
}
        

Delete example

Delete a user input example from an intent.

DELETE /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
deleteExample(params, callback())

  
delete_example(workspace_id, intent, text)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
intent path string The intent name (for example, pizza_order).
text path string The text of the user input example, with spaces and special characters in URL encoding.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
text string The text of the user input example.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
text string The text of the user input example.

Example request


curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples/Good%20afternoon?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  text: 'Good afternoon'
};

conversation.deleteExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.delete_example(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent = 'hello',
  text = 'Good afternoon'
)

print(json.dumps(response, indent=2))
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{}
        

Get example

Get information about a user input example.

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
getExample(params, callback())

  
get_example(workspace_id, intent, text)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
intent path string The intent name (for example, pizza_order).
text path string The text of the user input example, with spaces and special characters in URL encoding.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
text string The text of the user input example.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
text string The text of the user input example.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples/Good%20afternoon?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  text: 'Good afternoon'
};

conversation.getExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.get_example(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent = 'hello',
  text = 'Good afternoon'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the user input example, including the example text and creation and update timestamps.

Name Description
text string The text of the user input example.
created string The timestamp for creation of the user input example.
updated string The timestamp for the last update to the user input example.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Example response


{
  "text": "Good afternoon",
  "created": "2017-02-21T18:51:41.785Z",
  "updated": "2017-02-21T18:51:41.785Z"
}
        

Update example

Update the text of a user input example.

POST /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
updateExample(params, callback())
update_example(workspace_id, intent, text, new_text=None)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
intent path string The intent name (for example, pizza_order).
text path string The current text of the user input example, with spaces and special characters in URL encoding.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
example body json UpdateExample An UpdateExample object defining the new text for the user input example.
UpdateExample
Name Description
text string The updated text for the user input example.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
old_text string The current text of the user input example, with spaces and special characters in URL encoding.
text string The updated text for the user input example.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
text string The current text of the user input example, with spaces and special characters in URL encoding.
new_text string The updated text for the user input example.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"text\":\"Hello there!\"}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples/hi%20there?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  old_text: 'Hi there',
  text: 'Hello there!'        };

conversation.updateExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.update_example(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent = 'hello',
  text = 'Hi there',
  new_text = 'Hello there!'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about the user input example that was updated.

Name Description
text string The text of the user input example.
created string The timestamp for creation of the user input example.
updated string The timestamp for the last update to the user input example.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "text": "Hello there!",
  "created": "2017-02-20T19:00:03.160Z",
  "updated": "2017-02-21T20:06:54.552Z"
}
        

Dialog nodes

List dialog nodes

List the dialog nodes for a workspace.

GET /v1/workspaces/{workspace_id}/dialog_nodes

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace_id path string Unique identifier of the workspace.
page_limit query integer The number of records to return in each page of results. The default page limit is 100.
include_count query boolean Whether to include information about the number of records returned.
sort query string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are dialog_node and updated.
cursor query string A token identifying the last object from the previous page of results.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/dialog_nodes?version=2017-05-26"

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about all dialog nodes for the workspace.

Name Description
dialog_nodes An array of DialogNode objects describing the dialog nodes defined for the workspace.
pagination A Pagination object defining the pagination data for the returned objects.
DialogNode
Name Description
dialog_node string The dialog node ID.
description string The description of the dialog node.
conditions string The condition that triggers the dialog node.
parent string The ID of the parent dialog node.
previous_sibling string The ID of the previous sibling dialog node.
output object The output from the dialog node.
context object The context (if defined) for the dialog node.
metadata object The metadata (if any) for the dialog node.
next_step DialogNodeNextStep The next step to execute following this dialog node.
created string The timestamp for creation of the dialog node.
updated string The timestamp for the most recent update to the dialog node.
actions DialogNodeAction[ ] Any actions to be invoked by the dialog node.
title string The alias used to identify the dialog node.
type string How the dialog node is processed (standard, event_handler, frame, slot, or response_condition).
event_name string How an event_handler node is processed.
variable string The location in the dialog context where output is stored.
Pagination
Name Description
refresh_url string The URL that will return the same page of results.
next_url string The URL that will return the next page of results, if any.
total integer Reserved for future use.
matched integer Reserved for future use.
DialogNodeNextStep
Name Description
behavior string How the next_step node will be processed. Currently, the only valid value is jump_to.
dialog_node string The dialog node to process next.
selector string Which part of the dialog node to process next (condition, client, user_input, or body.
DialogNodeAction
Name Description
name string The name of the action.
type string The type of action to invoke (client or server).
parameters object A map of key/value pairs to be provided to the action. client, user_input, or body.
result_variable string The location in the dialog context where the result of the action is stored.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "dialog_nodes": [
    {
      "go_to": null,
      "title": null,
      "output": {
        "text": {
          "values": [
            "Hi! How can I help you?"
          ]
        }
      },
      "parent": null,
      "context": null,
      "created": "2017-04-10T14:36:49.177Z",
      "updated": "2017-06-23T20:42:30.794Z",
      "metadata": null,
      "conditions": "#hello",
      "description": null,
      "dialog_node": "greeting",
      "previous_sibling": null
    }
  ]
}
        

Create dialog node

Create a new dialog node.

POST /v1/workspaces/{workspace_id}/dialog_nodes

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace_id string The workspace ID.
dialog_node body json CreateDialogNode A CreateDialogNode object defining the content of the new dialog node.
CreateDialogNode
Name Description
dialog_node string The dialog node ID.
description string The description of the dialog node.
conditions string The condition that will trigger the dialog node.
parent string The ID of the parent dialog node (if any).
previous_sibling string The ID of the previous sibling dialog node (if any).
output object The output from the dialog node. See here for more information about how to specify dialog node output.
context object The context for the dialog node.
metadata object The metadata for the dialog node.
next_step DialogNodeNextStep An object describing the next step to be executed in dialog processing.
actions DialogNodeAction[ ] An object describing any actions to be invoked by the dialog node.
title string The alias used to identify the dialog node.
type string How the dialog node is processed. The valid values are standard, event_handler, frame, slot, and response_condition.
event_name string How an event_handler node is processed.
variable string The location in the dialog context where output is stored.
DialogNodeNextStep
Name Description
behavior string How the next_step reference is processed. Currently, the only valid value is jump_to.
dialog_node string The dialog node to process next.
selector string Which part of the dialog node to process next. The valid values are condition, client, user_input, and body.
DialogNodeAction
Name Description
name string The name of the action.
type string The type of action to invoke. The valid values are client and server. The default value is client.
parameters object A map of key/value pairs to be provided to the action.
result_variable string The location in the dialog context where the result of the action is stored.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"dialog_node\":\"greeting\",\"conditions\":\"#hello\",\"output\":{\"text\":\"Hi! How can I help you?\"},\"title\":\"greeting\"}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/dialog_nodes?version=2017-05-26"

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the dialog node that was created.

Name Description
dialog_node string The dialog node ID.
description string The description of the dialog node.
conditions string The condition that triggers the dialog node.
parent string The ID of the parent dialog node.
previous_sibling string The ID of the previous sibling dialog node.
output object The output from the dialog node.
context object The context of the dialog node.
metadata object The metadata of the dialog node.
next_step DialogNodeNextStep The next step to execute following this dialog node.
created string The timestamp for creation of the dialog node.
updated string The timestamp for the most recent update to the dialog node.
actions DialogNodeAction[ ] Any actions to be invoked by the dialog node.
title string The alias used to identify the dialog node.
type string How the dialog node is processed (standard, event_handler, frame, slot, or response_condition).
event_name string How an event_handler node is processed.
variable string The location in the dialog context where output is stored.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "go_to": null,
  "title": "Greeting",
  "output": {
    "text": "Hi! How can I help you?"
  },
  "parent": null,
  "context": null,
  "created": "2017-06-28T17:09:31.523Z",
  "updated": "2017-06-28T17:09:31.523Z",
  "metadata": null,
  "conditions": "#hello",
  "description": null,
  "dialog_node": "greeting",
  "previous_sibling": null
}
        

Delete dialog node

Delete a dialog node from a workspace.

DELETE /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}

  

  

  

Request

Name Description
workspace_id path string Unique identifier of the workspace.
dialog_node path string The dialog node ID (for example, get_order).
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.

Example request


curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/dialog_nodes/greeting?version=2017-05-26"

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Example response


{}
        

Get dialog node

Get information about a dialog node.

GET /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}

  

  

  

Request

Name Description
workspace_id path string Unique identifier of the workspace.
dialog_node path string The dialog node ID (for example, get_order).
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.

Example request


curl -H "X-Watson-Origin: wea-conversational-ui" -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/dialog_nodes/greeting?version=2017-05-26"

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the dialog node.

Name Description
dialog_node string The dialog node ID.
description string The description of the dialog node.
conditions string The condition that triggers the dialog node.
parent string The ID of the parent dialog node.
previous_sibling string The ID of the previous sibling dialog node.
output object The output from the dialog node.
context object The context (if defined) for the dialog node.
metadata object The metadata (if any) for the dialog node.
next_step DialogNodeNextStep The next step to execute following this dialog node.
created string The timestamp for creation of the dialog node.
updated string The timestamp for the most recent update to the dialog node.
actions DialogNodeAction[ ] Any actions to be invoked by the dialog node.
title string The alias used to identify the dialog node.
type string How the dialog node is processed (standard, event_handler, frame, slot, or response_condition).
event_name string How an event_handler node is processed.
variable string The location in the dialog context where output is stored.

Response codes

Status Description
400 Bad Request Invalid request

Rate limit

This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Example response


{
  "title": "Greeting",
  "output": {
    "text": "Hi! How can I help you?"
  },
  "parent": null,
  "context": null,
  "created": "2017-06-28T17:09:31.523Z",
  "updated": "2017-06-28T17:09:31.523Z",
  "metadata": null,
  "next_step": null,
  "conditions": "#hello",
  "description": null,
  "dialog_node": "greeting",
  "previous_sibling": null
}
        

Update dialog node

Update an existing dialog node with new or modified data.

POST /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}

Request

Name Description
workspace_id path string The workspace ID.
dialog_node path string The ID of the dialog node to update.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
new_dialog_node body json UpdateDialogNode An UpdateDialogNode object defining the updated content of the dialog node.
UpdateDialogNode
Name Description
dialog_node string The dialog node ID.
description string The description of the dialog node.
conditions string The condition that will trigger the dialog node.
parent string The ID of the parent dialog node (if any).
previous_sibling string The ID of the previous sibling dialog node (if any).
output object The output from the dialog node. See here for more information about how to specify dialog node output.
context object The context for the dialog node.
metadata object The metadata for the dialog node.
next_step DialogNodeNextStep An object describing the next step to be executed in dialog processing.
title string The alias used to identify the dialog node.
type string How the dialog node is processed. The valid values are standard, event_handler, frame, slot, and response_condition.
event_name string How an event_handler node is processed.
variable string The location in the dialog context where output is stored.
actions DialogNodeAction[ ] An object describing any actions to be invoked by the dialog node.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"output\":{\"text\":\"Hi! How can I help you?\"}}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/dialog_nodes/greeting?version=2017-05-26"

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the dialog node that was updated.

Name Description
dialog_node string The dialog node ID.
description string The description of the dialog node.
conditions string The condition that triggers the dialog node.
parent string The ID of the parent dialog node.
previous_sibling string The ID of the previous sibling dialog node.
output object The output from the dialog node.
context object The context (if defined) for the dialog node.
metadata object The metadata (if any) for the dialog node.
next_step DialogNodeNextStep The next step to execute following this dialog node.
created string The timestamp for creation of the dialog node.
updated string The timestamp for the most recent update to the dialog node.
actions DialogNodeAction[ ] Any actions to be invoked by the dialog node.
title string The alias used to identify the dialog node.
type string How the dialog node is processed (standard, event_handler, frame, slot, or response_condition).
event_name string How an event_handler node is processed.
variable string The location in the dialog context where output is stored.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Example response


{
  "title": "Greeting",
  "output": {
    "text": "What can I do for you?"
  },
  "parent": null,
  "context": null,
  "created": "2017-06-28T17:09:31.523Z",
  "updated": "2017-06-28T19:57:05.300Z",
  "metadata": null,
  "next_step": null,
  "conditions": "#hello",
  "description": null,
  "dialog_node": "greeting",
  "previous_sibling": null
}
        

Logs

List log events in a workspace

List the events from the log of a specific workspace.

GET /v1/workspaces/{workspace_id}/logs
getLogs(params, callback())
list_logs(workspace_id, sort=None, filter=None, page_limit=None, cursor=None)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
filter query string A cacheable parameter that limits the results to those matching the specified filter. For more information, see Filter query reference.
sort query string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). The only supported value is request_timestamp.
page_limit query integer The number of records to return in each page of results. The default page limit is 100.
cursor query string A token identifying the last object from the previous page of results.
Name Description
workspace_id string The workspace ID.
filter string A cacheable parameter that limits the results to those matching the specified filter. For more information, see Filter query reference.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). The only supported value is request_timestamp.
cursor string A token identifying the last object from the previous page of results.
Name Description
workspace_id string The workspace ID.
sort string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). The only supported value is request_timestamp.
filter string A cacheable parameter that limits the results to those matching the specified filter. For more information, see Filter query reference.
page_limit integer The number of records to return in each page of results. The default page limit is 100.
cursor string A token identifying the last object from the previous page of results.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/logs?version=2017-05-26"

var watson = require("watson-developer-cloud");

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2017-05-26'
});

const params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d'
};

conversation.getLogs(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }

});
Coming soon.
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.list_logs(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d'
)

print(json.dumps(response, indent=2))
      

Response

Returns information about requests (user input) received, and responses sent, by the workspace.

Name Description
logs An array of LogExport objects describing log events.
pagination A LogPagination object defining the pagination data for the returned objects.
LogExport
Name Description
request MessageRequest A request received by the workspace, including the user input and context.
response MessageResponse The response sent by the workspace, including the output text, detected intents and entities, and context.
log_id string A unique identifier for the logged event.
request_timestamp string The timestamp for receipt of the message.
response_timestamp string The timestamp for the system response to the message.
workspace_id string The unique identifier of the workspace where the request was made.
language string The language of the workspace where the request was made..
LogPagination
Name Description
next_url string The URL that will return the next page of results, if any.
matched integer Reserved for future use.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

If the cursor parameter is not specified, this operation is limited to 40 requests per 30 minutes. If the cursor parameter is specified, the limit is 120 requests per minute. For more information, see Rate limiting.

Example response


{
  "logs": [
    {
      "request": {
        "input": {
          "text": "Good morning"
        }
      },
      "response": {
        "intents": [
          {
            "intent": "hello",
            "confidence": 1
          }
        ],
        "entities": [],
        "input": {
          "text": "Good morning"
        },
        "output": {
          "text": [
            "Hi! What can I do for you?"
          ],
          "nodes_visited": [
            "node_2_1501875253968"
          ],
          "log_messages": []
        },
        "context": {
          "conversation_id": "30001db8-d2f9-4530-9e81-80fc75725209",
          "system": {
            "dialog_stack": [
              {
                "dialog_node": "root"
              }
            ],
            "dialog_turn_counter": 1,
            "dialog_request_counter": 1,
            "_node_output_map": {
              "node_2_1501875253968": [
                0
              ]
            },
            "branch_exited": true,
            "branch_exited_reason": "completed"
          }
        }
      },
      "language": "en",
      "workspace_id": "9978a49e-ea89-4493-b33d-82298d3db20d",
      "request_timestamp": "2017-09-13T16:39:56.284Z",
      "response_timestamp": "2017-09-13T16:39:58.828Z",
      "log_id": "dcceece9-acfc-49aa-94c3-ddc2b9776cbe"
    }
  ],
  "pagination": {}
}
        

Error handling

The Conversation service uses standard HTTP response codes to display whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Equivalent exceptions are listed with the individual methods. The exceptions typically include the error message returned by the service. All methods can throw the following common exceptions.

Common exceptions thrown

The WatsonException exception catches the error message from the API response.

Exception Description
IllegalArgumentException An illegal or null argument was passed to a method.
UnauthorizedException Access is denied due to invalid credentials. (HTTP response code 401.)

Error format

Name Description
error string General description of the error.
errors ErrorDetail[ ] A collection of objects describing specific constraint violations associated with the error.
ErrorDetail
Name Description
message string The description of a specific constraint violation.
path string The location of the constraint violation.

Example error


{
  "error": "Resource not found"
}
        

Pagination

Some API requests might return a large number of results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. GET requests for the following resources use pagination:

  • /v1/workspaces
  • /v1/workspaces/{workspace_id}/counterexamples
  • /v1/workspaces/{workspace_id}/intents
  • /v1/workspaces/{workspace_id}/intents/{intent}/examples

The default page size is 100 objects. To use a different page size, use the page_limit query parameter.

To change the attribute by which results are sorted, use the sort query parameter. If you include multiple sort parameters on the same query, the results are sorted first by the first sorting attribute, then the second, and so on.

The supported sorting attributes vary by endpoint; for more information, see the API Reference information for each request.

For any request that uses pagination, the response includes a pagination object that specifies pagination information. This object includes two URLs you can use to make subsequent requests:

  • refresh_url: the URL for requesting the same page of results again.
  • next_url: the URL for requesting the next page of results. The next_url property is omitted if there no more results.

These URLs retain the same page_limit and sort parameters that were used for the initial request.

Example request


curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?version=2017-05-26&page_limit=2&sort=-modified"
        

var watson = require( 'watson-developer-cloud' );

var conversation = new watson.ConversationV1({
    username: '{username}',
    password: '{password}',
    version_date: '2017-05-26'
});

const params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  page_limit: 2,
  sort: '-modified'
};

conversation.getExamples(params, function(err, response) {
    if (err) {
        console.error(err);
    } else {
        console.log(response);
    }

});
        

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  version = '2017-05-26'
)

response = conversation.list_examples(
  workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent = 'hello',
  page_limit = 2,
  sort = '-modified'
)

print(json.dumps(response, indent=2))
        

Example response


{
  "examples": [
    {
      "text": "Howdy!",
      "created": "2017-08-18T20:12:43.230Z",
      "updated": "2017-08-18T20:12:43.230Z"
    },
    {
      "text": "Good morning",
      "created": "2017-08-18T18:05:48.153Z",
      "updated": "2017-08-18T18:05:48.153Z"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?page_limit=2&sort=-modified&version=2017-05-26",
    "next_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?cursor=eyJtb2RpZmllZCI6eyJ2YWx1ZSI6IjIwMTctMDgtMThUMTg6MDU6NDguMTUzWiIsIm9yZGVyIjoiZGVzYyJ9LCJ0ZXh0Ijp7InZhbHVlIjoiR29vZCBtb3JuaW5nIiwib3JkZXIiOiJhc2MiLCJ0aWVfYnJlYWtlciI6dHJ1ZX19&page_limit=2&sort=-modified&version=2017-05-26"
  }
}
        

Rate limiting

Rate limits for API requests are enforced on a per-service-instance basis. If the number of requests for a particular method and endpoint reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.

The response to each HTTP request includes headers you can use to determine whether you are close to the rate limit:

  • X-RateLimit-Reset: the time the current timer expires (in UNIX epoch time)
  • X-RateLimit-Remaining: the number of requests remaining in the current time window
  • X-RateLimit-Limit: the total number of requests allowed within the time window

An HTTP status code of 429 indicates that the rate limit has been exceeded.

The number of allowed requests, and the length of the time window, vary by method and endpoint. The reference information for each endpoint specifies the rate limit that applies.

Data collection

By default, all Watson services log requests and their results. Logging is done only to improve the services for future users. The logged data is not shared or made public. If you prefer that your data not be used for service improvements, use one of the following options:

  • To prevent IBM from accessing user input and Watson responses, set the X-Watson-Learning-Opt-Out header parameter to true when sending a message. You must set the header on each message request that you do not want IBM to access for general service improvements. You can set the header using the headers property of the service object you use to send message requests that you do not want to be accessed. improvements. You can set the header using the setDefaultHeaders method of the service object you use to send message requests that you do not want to be accessed. You can set the header using the x_watson_learning_opt_out attribute of the service object you use to send message requests that you do not want to be accessed.
  • To prevent IBM from accessing workspace training data such as intents and entities, set the X-Watson-Learning-Opt-Out header parameter to true when creating or updating a workspace. This option marks the workspace as opted out, and no training data for that workspace will be used. (This option does not apply to messages, which must be opted out individually.) You can set the header using the headers property of the service object you use to create or update the workspace. You can set the header using the setDefaultHeaders method of the service object you use to create or update the workspace. You can set the header using the x_watson_learning_opt_out attribute of the service object you use to create or update the workspace.
  • You can also mark a workspace as opted out by specifying a value of true for the learning_opt_out property in the JSON data used to create or update a workspace. This option applies only to training data, not to messages. (Note that the HTTP header always overrides the JSON property, if both are specified.)

Example request


curl -H "Content-Type: application/json" -H "X-Watson-Learning-Opt-Out: true" -X POST -u "{username}":"{password}" -d "{\"input\": {\"text\": \"Good morning\"}}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/message?version=2017-05-26"
        

Example request


var watson = require( 'watson-developer-cloud' );
    
var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2016-05-26',
  headers: {
    "X-Watson-Learning-Opt-Out": true
  }
});
        

Example request


Conversation service = new Conversation();
Map<String, String> headers = new HashMap<String, String>();
headers.put(HttpHeaders.X_WATSON_LEARNING_OPT_OUT, 1);
service.setDefaultHeaders(headers);
        

Example request


import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
  username = '{username}',
  password = '{password}',
  x_watson_learning_opt_out = True
)