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

Important: If you have IBM® Cloud Dedicated, this might not be your endpoint. Check your endpoint URL on the Service credentials page for your instance of the Conversation service.

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>4.0.0</version>
</dependency>

Gradle

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

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 --upgrade "watson-developer-cloud>=1.0,<2.0"

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.

To access the service credentials for a workspace from the Conversation tool, select Deploy from the menu, and then go to the Credentials tab.

You can also view the service credentials for a service instance from the Existing Services page of the Watson console. 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 IBM Cloud 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, 2018-02-16).


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

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

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

Conversation service = new Conversation("{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 2018-02-16.

Workspaces

List workspaces

List the workspaces associated with a Conversation service instance.

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

GET /v1/workspaces
listWorkspaces(params, callback())
ServiceCall<WorkspaceCollection> listWorkspaces(ListWorkspacesOptions listWorkspacesOptions)
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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java ListWorkspacesOptions object with the listWorkspacesOptions argument.

Name Description
pageLimit integer The number of records to return in each page of results. The default page limit is 100.
includeCount 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

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

ListWorkspacesOptions options = new ListWorkspacesOptions.Builder().build();

WorkspaceCollection workspaces = service.listWorkspaces(options).execute();

System.out.println(workspaces);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

response = conversation.list_workspaces()

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

Response

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.
WorkspaceCollection (Java WorkspaceCollection object)
Name Description
workspaces A List of Workspace objects describing the workspaces associated with the service instance.
pagination A Pagination object defining the pagination data for the returned objects.
Workspace (Java Workspace object)
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.
created Date The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
updated Date The timestamp for the last update to the workspace.
workspace_id string The workspace ID.
workspaceId string The workspace ID.
description string The description of the workspace.
metadata object Any metadata related to the workspace.
metadata Map 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.
learningOptOut 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

Example response


{
  "workspaces": [
    {
      "name": "Car_Dashboard",
      "language": "en",
      "metadata": {
        "runtime_version": "2018-02-16"
      },
      "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",
      "language": "en",
      "metadata": {
        "runtime_version": "2018-02-16"
      },
      "workspace_id": "e42c8e5c-eb34-4b65-99f0-59f9329b66ec",
      "learning_opt_out": false
    },
    {
      "name": "workspace-example",
      "language": "en",
      "metadata": {
        "runtime_version": "2018-02-16"
      },
      "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=2018-02-16"
  }
}
      
    

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. For more information, see Rate limiting.

POST /v1/workspaces
createWorkspace(params, callback())
ServiceCall<Workspace> createWorkspace(CreateWorkspaceOptions createWorkspaceOptions)
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 2018-02-16.
workspace body json CreateWorkspace A CreateWorkspace object defining the content of the new workspace.
CreateWorkspace
Name Description
name string The name of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 64 characters.
description string The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
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 CreateDialogNode[ ] 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. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 64 characters.
description string The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
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 CreateDialogNode[ ] 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.

Pass the parameters as a Java CreateWorkspaceOptions object with the createWorkspaceOptions argument.

Name Description
counterexamples CreateCounterexample[ ] An array of objects defining input examples that have been marked as irrelevant input.
description string The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
dialogNodes CreateDialogNode[ ] An array of objects defining the nodes in the workspace dialog.
entities CreateEntity[ ] An array of objects defining the entities for the workspace.
intents CreateIntent[ ] An array of objects defining the intents for the workspace.
language string The language of the workspace.
learningOptOut 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.
metadata Map Any metadata related to the workspace.
name string The name of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 64 characters.
Name Description
name string The name of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 64 characters.
description string The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 64 characters.
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 CreateDialogNode[ ] 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.
CreateIntent (Java CreateIntent object)
Name Description
intent string The name of the intent. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 128 characters
description string The description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
examples CreateExample[ ] An array of user input examples for the intent.
examples CreateExample[ ] A List of user input examples for the intent.
CreateExample (Java CreateExample object)
Name Description
text string The text of a user input example. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters
CreateEntity (Java CreateEntity object)
Name Description
entity string The name of the entity (for example, beverage). This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, and hyphen characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 64 characters
description string The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
metadata object Any metadata related to the entity.
metadata Map Any metadata related to the entity.
values CreateValue[ ] An array of entity values.
values CreateValue[ ] A List of entity values.
fuzzy_match boolean Whether to use fuzzy matching for the entity.
fuzzyMatch boolean Whether to use fuzzy matching for the entity.
CreateValue (Java CreateValue object)
Name Description
value string The text of the entity value. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
metadata object Any metadata related to the entity value.
metadata Map Any metadata related to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can provide either synonyms or patterns (as specified by the value of type), but not both. A synonym must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
synonyms string[ ] A List containing synonyms for the entity value. You can provide either synonyms or patterns (as specified by the value of type), but not both. A synonym must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
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. A pattern is a regular expression no longer than 128 characters. For more information about the allowed syntax, see Creating entities.
patterns string[ ] A List containing patterns for the entity value. You can specify either synonyms or patterns (as specified by the value of type), but not both. A pattern is a regular expression no longer than 128 characters. For more information about the allowed syntax, see Creating entities.
type string[ ] Specifies the type of value (synonyms or patterns).
value_type string[ ] Specifies the type of value (synonyms or patterns).
valueType string[ ] Specifies the type of value (synonyms or patterns).
CreateDialogNode (Java CreateDialogNode object)
Name Description
dialog_node string The dialog node ID. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 1024 characters
dialogNode string The dialog node ID. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 1024 characters
description string The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
conditions string The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters.
parent string The ID of the parent dialog node (if any).
previous_sibling string The ID of the previous sibling dialog node (if any).
previousSibling 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.
output Map 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.
context Map The context for the dialog node.
metadata object The metadata for the dialog node.
metadata Map The metadata for the dialog node.
next_step DialogNodeNextStep An object describing the next step to be executed in dialog processing.
nextStep DialogNodeNextStep An object describing the next step to be executed in dialog processing.
actions DialogNodeAction[ ] An array of objects describing any actions to be invoked by the dialog node.
title string The alias used to identify the dialog node. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 64 characters
type string How the dialog node is processed. The valid values are standard, event_handler, frame, slot, and response_condition.
nodeType 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.
eventName string How an event_handler node is processed.
variable string The location in the dialog context where output is stored.
DialogNodeNextStep (Java DialogNodeNextStep object)
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.
dialogNode 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 (Java DialogNodeAction object)
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.
parameters Map 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.
resultVariable string The location in the dialog context where the result of the action is stored.
credentials string The name of the context variable that the client application will use to pass in credentials for the action.
CreateCounterexample (Java CreateCounterexample object)
Name Description
text string The text of a user input example to be marked as irrelevant input. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }
 });

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

String workspaceName = "API test";
String workspaceDescription = "Example workspace created via API";

CreateWorkspaceOptions options = new CreateWorkspaceOptions.Builder()
  .name(workspaceName)
  .description(workspaceDescription)
  .build();

Workspace response = service.createWorkspace(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

Workspace (Java Workspace object)
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.
created Date The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
updated Date The timestamp for the last update to the workspace.
workspace_id string The workspace ID.
workspaceId string The workspace ID.
description string The description of the workspace.
metadata object Any metadata related to the workspace.
metadata Map Any metadata related to the workspace.
learningOptOut 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

Example response


{
  "name": "API test",
  "created": "2017-01-31T18:02:19.070Z",
  "updated": "2017-01-31T18:02:19.070Z",
  "language": "en",
  "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. For more information, see Rate limiting.

DELETE /v1/workspaces/{workspace_id}
deleteWorkspace(params, callback())
ServiceCall<Void> deleteWorkspace(DeleteWorkspaceOptions deleteWorkspaceOptions)
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 2018-02-16.
Name Description
workspace_id string Unique identifier of the workspace.

Pass the parameters as a Java DeleteWorkspaceOptions object with the deleteWorkspaceOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9081e306-ccc4-41ca-a27b-4791e35c7621";

DeleteWorkspaceOptions options = new DeleteWorkspaceOptions.Builder(workspaceId).build();

service.deleteWorkspace(options).execute();
  

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

response = conversation.delete_workspace(
    workspace_id = '8f9269e0-ff44-4673-99cc-8a28e508c0ba'
)

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

Response

No response body.

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

Get workspace

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

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.

GET /v1/workspaces/{workspace_id}
getWorkspace(params, callback())
ServiceCall<WorkspaceExport> getWorkspace(GetWorkspaceOptions getWorkspaceOptions)
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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java GetWorkspaceOptions object with the getWorkspaceOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }
   });

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

String workspaceId = "1abfe057-c159-460e-af03-3d794c65d20a";

GetWorkspaceOptions options = new GetWorkspaceOptions.Builder(workspaceId).build();

WorkspaceExport response = service.getWorkspace(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

WorkspaceExport (Java WorkspaceExport object)
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.
metadata Map Any metadata that is required by the workspace.
created string The timestamp for creation of the workspace.
created Date The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
updated Date The timestamp for the last update to the workspace.
workspace_id string The workspace ID.
workspaceId string The workspace ID.
status string The current status of the workspace (Non Existent, Training, Failed, Available, or Unavailable).
intents IntentExport[ ] An array of IntentExport objects describing the intents for the workspace.
intents IntentExport[ ] A List of IntentExport objects describing the intents for the workspace.
entities EntityExport[ ] An array of EntityExport objects describing the entities for the workspace.
entities EntityExport[ ] A List of EntityExport objects describing the entities for the workspace.
counterexamples Counterexample[ ] An array of Counterexample objects describing the user input examples that have been marked as irrelevant input.
counterexamples Counterexample[ ] A List of Counterexample objects describing the user input examples that have been marked as irrelevant input.
dialog_nodes DialogNode[ ] An array of DialogNode objects describing the dialog nodes for the workspace.
dialogNodes DialogNode[ ] A List of DialogNode 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.
learningOptOut 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
400 Bad Request Invalid request
404 Not Found The request specified a resource that was not found

Example response


{
  "name": "API test",
  "language": "en",
  "status": "Available",
  "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.

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

POST /v1/workspaces/{workspace_id}
updateWorkspace(params, callback())
ServiceCall<Workspace> updateWorkspace(UpdateWorkspaceOptions updateWorkspaceOptions)
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 2018-02-16.
workspace_id path string Unique identifier of the workspace.
append query string

Whether the new data is to be appended to the existing data in the workspace. If append=false, elements included in the new data completely replace the corresponding existing elements, including all subelements. For example, if the new data includes entities and append=false, all existing entities in the workspace are discarded and replaced with the new entities.

If append=true, existing elements are preserved, and the new elements are added. If any elements in the new data collide with existing elements, the update request fails.

The default value is false.

workspace body json UpdateWorkspace The JSON data defining the new and updated workspace content.
UpdateWorkspace
Name Description
name string The name of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 64 characters.
description string The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
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 CreateDialogNode[ ] 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. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 64 characters.
description string The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
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 CreateDialogNode[ ] 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.

Pass the parameters as a Java UpdateWorkspaceOptions object with the updateWorkspaceOptions argument.

Name Description
workspaceId string Unique identifier of the workspace.
counterexamples CreateCounterexample[ ] An array of objects defining input examples that have been marked as irrelevant input.
description string The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
dialogNodes CreateDialogNode[ ] An array of objects defining the nodes in the workspace dialog.
entities CreateEntity[ ] An array of objects defining the entities for the workspace.
intents CreateIntent[ ] An array of objects defining the intents for the workspace.
language string The language of the workspace.
learningOptOut 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.
metadata Map Any metadata related to the workspace.
name string The name of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 64 characters.
Name Description
workspace_id string Unique identifier of the workspace.
name string The name of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 64 characters.
description string The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
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 CreateDialogNode[ ] 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.

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }
   });

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

String workspaceId = "1abfe057-c159-460e-af03-3d794c65d20a";
String workspaceName = "Update Test";
String workspaceDescription = "Example workspace updated via API.";

UpdateWorkspaceOptions options = new UpdateWorkspaceOptions.Builder(workspaceId)
  .name(workspaceName)
  .description(workspaceDescription)
  .build();

Workspace response = service.updateWorkspace(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

response = conversation.update_workspace(
    workspace_id = '0ae6ab15-dd03-4be7-8002-fd8cfa0cd8c1',
    name='Update Test',
    description='Test workspace updated via API'
)

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

Response

Workspace (Java Workspace object)
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.
created Date The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
updated Date The timestamp for the last update to the workspace.
workspace_id string The workspace ID.
workspaceId string The workspace ID.
description string The description of the workspace.
metadata object Any metadata related to the workspace.
metadata Map Any metadata related to the workspace.
learningOptOut 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

Example response


{
  "name": "API test",
  "created": "2017-02-01T15:28:10.145Z",
  "updated": "2017-02-01T21:49:32.690Z",
  "language": "en",
  "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.

There is no rate limit for this operation.

POST /v1/workspaces/{workspace_id}/message
message(params, callback())
ServiceCall<MessageResponse> message(MessageOptions messageOptions)
message(workspace_id, 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 2018-02-16.
nodes_visited_details query boolean Whether to include additional diagnostic information about the dialog nodes that were visited during processing of the input message. The default value is false.
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 information over multiple requests.
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[ ] A List 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.
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 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 (Java InputData object)
Name Description
text string The text of the user input. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters.
Context (Java Context object)
Name Description
conversation_id string The unique identifier of the conversation.
conversationId string The unique identifier of the conversation.
system SystemResponse For internal use only.
RuntimeEntity (Java RuntimeEntity object)
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.
location integer[ ] A List 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.
metadata Map Any metadata for the entity.
groups CaptureGroup[ ] The recognized capture groups for the entity, as defined by the entity pattern.
RuntimeIntent (Java RuntimeIntent object)
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 (Java OutputData object)
Name Description
log_messages LogMessage[ ] An array of 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.
nodes_visited_details DialogNodeVisitedDetails[ ] An array of objects containing detailed diagnostic information about the nodes that were triggered during processing of the input message. Included only if nodes_visited_details is set to true in the message request.
LogMessage (Java LogMessage object)
Name Description
level string The severity of the message (info, error, or warn).
msg string The text of the log message.
CaptureGroup
Name Description
group string A recognized capture group for the entity.
location integer[ ] Zero-based character offsets that indicate where the entity value begins and ends in the input text.
DialogNodeVisitedDetails
Name Description
dialog_node string A dialog node that was triggered during processing of the input message.
title string The title of the dialog node.

Example request


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=2018-02-16"

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

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

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='2018-02-16'
)

response = conversation.message(
    workspace_id='9978a49e-ea89-4493-b33d-82298d3db20d',
    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.
intents RuntimeIntent[ ] A List of intents recognized in the user input, sorted in descending order of confidence. Returns an empty list 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.
entities RuntimeEntity[ ] A List of entities identified in the user input. Returns an empty list 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.
alternateIntents 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 (Java MessageInput object)
Name Description
text string The text of the user input.

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

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.

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

GET /v1/workspaces/{workspace_id}/counterexamples
listCounterexamples(params, callback())
ServiceCall<CounterexampleCollection> listCounterexamples(ListCounterexamplesOptions listCounterexamplesOptions)
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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java ListCounterexamplesOptions object with the listCounterexamplesOptions argument.

Name Description
workspaceId string The workspace ID.
pageLimit integer The number of records to return in each page of results. The default page limit is 100.
includeCount 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.listCounterexamples(params, function(err, response) {
  if (err) {
    console.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";

ListCounterexamplesOptions options = new ListCounterexamplesOptions.Builder(workspaceId).build();

CounterexampleCollection response = service.listCounterexamples(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

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.
CounterexampleCollection (Java CounterexampleCollection object)
Name Description
counterexamples A List of Counterexample objects describing the examples marked as irrelevant input.
pagination A Pagination object defining the pagination data for the returned objects.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


{
  "counterexamples": [
    {
      "text": "What are you wearing?"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples?version=2018-02-16"
  }
}
      

Create counterexample

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

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

POST /v1/workspaces/{workspace_id}/counterexamples
createCounterExample(params, callback())
ServiceCall<Counterexample> createCounterexample(CreateCounterexampleOptions CreateCounterexampleOptions)
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 2018-02-16.
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.
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters

Pass the parameters as a Java CreateCounterexampleOptions object with the createCounterexampleOptions argument.

Name Description
workspaceId string Unique identifier of the workspace.
text string The text of a user input example to be marked as irrelevant input. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";
String text = "Make me a sandwich";

CreateCounterexampleOptions options = new CreateCounterexampleOptions.Builder(workspaceId, text).build();

Counterexample response = service.createCounterexample(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

Counterexample (Java Counterexample object)
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

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.

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

DELETE /v1/workspaces/{workspace_id}/counterexamples/{text}
deleteCounterExample(params, callback())
ServiceCall<Void> deleteCounterexample(DeleteCounterexampleOptions deleteCounterexampleOptions)
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 2018-02-16.
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.

Pass the parameters as a Java DeleteCounterexampleOptions object with the deleteCounterexampleOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";
String text = "Make me a sandwich";

DeleteCounterexampleOptions options = new DeleteCounterexampleOptions.Builder(workspaceId, text).build();

service.deleteCounterexample(options).execute();
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

No response body.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Get counterexample

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

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

GET /v1/workspaces/{workspace_id}/counterexamples/{text}
getCounterExample(params, callback())
ServiceCall<Counterexample> getCounterexample(GetCounterexampleOptions getCounterexampleOptions)
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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
Name Description
workspace_id string Unique identifier of the workspace.
text string The text of the user input example.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java GetCounterexampleOptions object with the getCounterexampleOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";
String text = "Make me a sandwich";

GetCounterexampleOptions options = new GetCounterexampleOptions.Builder(workspaceId, text).build();

Counterexample response = service.getCounterexample(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

Counterexample (Java Counterexample object)
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

Example response


{
  "text": "What are you wearing?"
}
      

Update counterexample

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

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

POST /v1/workspaces/{workspace_id}/counterexamples/{text}
updateCounterExample(params, callback())
ServiceCall<Counterexample> updateCounterexample(UpdateCounterexampleOptions updateCounterexampleOptions)
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 2018-02-16.
workspace_id path string Unique identifier of the workspace.
text path string The current text of the counterexample, with spaces and special characters in URL encoding.
counterexample body json UpdateCounterexample An UpdateCounterexample object defining the new text for the counterexample.
UpdateCounterexample
Name Description
text string The updated text for the counterexample. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters

Pass the parameters as a Java UpdateCounterexampleOptions object with the updateCounterexampleOptions argument.

Name Description
workspaceId string Unique identifier of the workspace.
text string The current text of the counterexample.
newText string The updated text for the counterexample. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.updateCounterExample(params, function(err, response) {
  if (err) {
    console.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";
String text = "Make me a sandwich";
String newText = "Make me a cheeseburger!";

UpdateCounterexampleOptions options = new UpdateCounterexampleOptions.Builder(workspaceId, text)
  .newText(newText)
  .build();

Counterexample response = service.updateCounterexample(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

Counterexample (Java Counterexample object)
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

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.

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.

GET /v1/workspaces/{workspace_id}/entities
listEntities(params, callback())
ServiceCall<EntityCollection> listEntities(ListEntitiesOptions listEntitiesOptions)
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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java ListEntitiesOptions object with the listEntitiesOptions argument.

Name Description
workspaceId 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.
pageLimit integer The number of records to return in each page of results. The default page limit is 100.
includeCount 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.listEntities(params, function(err, response) {
  if (err) {
    console.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";

ListEntitiesOptions options = new ListEntitiesOptions.Builder(workspaceId).build();

EntityCollection response = service.listEntities(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

EntityCollection (Java EntityCollection object)
Name Description
entities An array of EntityExport objects describing the entities defined for the workspace.
entities A List of EntityExport objects describing the entities defined for the workspace.
pagination A Pagination object defining the pagination data for the returned objects.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


{
  "entities": [
    {
      "entity": "animal"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/entities?version=2018-02-16"
  }
}
      

Create entity

Create a new entity.

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

POST /v1/workspaces/{workspace_id}/entities
createEntity(params, callback())
ServiceCall<Entity> createEntity(CreateEntityOptions createEntityOptions)
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 2018-02-16.
workspace_id string The workspace ID.
entity body json CreateEntity A CreateEntity object defining the content of the new entity.
Name Description
workspace_id string The workspace ID.
entity string The name of the entity (for example, beverage). This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, and hyphen characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 64 characters
description string The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
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.

Pass the parameters as a Java CreateEntityOptions object with the createEntityOptions argument.

Name Description
workspaceId string The workspace ID.
entity string The name of the entity (for example, beverage). This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, and hyphen characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 64 characters
description string The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
metadata Map Any metadata related to the entity.
values CreateValue[ ] A List of objects defining entity values.
fuzzyMatch 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). This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, and hyphen characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 64 characters
description string The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
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.

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

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

List<CreateValue> entityValues = new ArrayList<CreateValue>();
entityValues.add(new CreateValue.Builder("water").build());
entityValues.add(new CreateValue.Builder("orange juice").build());
entityValues.add(new CreateValue.Builder("soda").build());

CreateEntityOptions options = new CreateEntityOptions.Builder(workspaceId, entityName)
  .values(entityValues)
  .build();

Entity response = service.createEntity(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Example response


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

Delete entity

Delete an entity from a workspace.

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

DELETE /v1/workspaces/{workspace_id}/entities/{entity}
deleteEntity(params, callback())
ServiceCall<Void> deleteEntity(DeleteEntityOptions deleteEntityOptions)
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 2018-02-16.
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).

Pass the parameters as a Java DeleteEntityOptions object with the deleteEntityOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

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

DeleteEntityOptions options = new DeleteEntityOptions.Builder(workspaceId, entityName).build();

service.deleteEntity(options).execute();
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

No response body.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Get entity

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

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.

GET /v1/workspaces/{workspace_id}/entities/{entity}
getEntity(params, callback())
ServiceCall<EntityExport> getEntity(GetEntityOptions getEntityOptions)
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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java GetEntityOptions object with the getEntityOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

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

GetEntityOptions options = new GetEntityOptions.Builder(workspaceId, entityName).build();

EntityExport response = service.getEntity(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

EntityExport (Java EntityExport object)
Name Description
entity string The name of the entity (for example, beverage).
created string The timestamp for creation of the entity.
created Date The timestamp for creation of the entity.
updated string The timestamp for the last update to the entity.
updated Date The timestamp for the last update to the entity.
description string The description of the entity.
metadata object Any metadata related to the entity.
metadata Map 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.
values ValueExport[ ] A List of objects describing the entity values.

Response codes

Status Description
400 Bad Request Invalid request

Example response


{
  "entity": "beverage"
}
      

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.

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

POST /v1/workspaces/{workspace_id}/entities/{entity}
updateEntity(params, callback())
ServiceCall<Entity> updateEntity(UpdateEntityOptions updateEntityOptions)
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 2018-02-16.
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). This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, and hyphen characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 64 characters
description string The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
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.
entity string The name of the entity to update.
new_entity string The updated name of the entity (for example, beverage). This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, and hyphen characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 64 characters
new_description string The updated description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
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.

Pass the parameters as a Java UpdateEntityOptions object with the updateEntityOptions argument.

Name Description
workspaceId string The workspace ID.
entity string The name of the entity to update.
newEntity string The updated name of the entity (for example, beverage). This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, and hyphen characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 64 characters
newDescription string The updated description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
newMetadata Map Updated metadata related to the entity.
newFuzzyMatch boolean Whether to use fuzzy matching for the entity.
newValues CreateValue[ ] An array of entity values.
Name Description
workspace_id 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). This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, and hyphen characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 64 characters
new_description string The updated description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
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.

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.updateEntity(params, function(err, response) {
  if (err) {
    console.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";
String entityName = "beverage";
String description = "Liquid refreshment";

UpdateEntityOptions options = new UpdateEntityOptions.Builder(workspaceId, entityName)
  .newDescription(description)
  .build();

Entity response = service.updateEntity(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


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

Values

List entity values

List the values for an entity.

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

GET /v1/workspaces/{workspace_id}/entities/{entity}/values
listValues(params, callback())
ServiceCall<ValueCollection> listValues(ListValuesOptions listValuesOptions)
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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java ListValuesOptions object with the listValuesOptions argument.

Name Description
workspaceId 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.
pageLimit integer The number of records to return in each page of results. The default page limit is 100.
includeCount 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.listValues(params, function(err, response) {
  if (err) {
    console.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";
String entityName = "beverage";

ListValuesOptions options = new ListValuesOptions.Builder(workspaceId, entityName).build();

ValueCollection response = service.listValues(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

ValueCollection (Java ValueCollection object)
Name Description
values ValueExport[ ] An array of objects describing the entity values.
values ValueExport[ ] A List of objects describing the entity values.
pagination A Pagination object defining the pagination data for the returned objects.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


{
  "values": [
    {
      "type": "synonyms",
      "value": "orange juice"
    },
    {
      "type": "synonyms",
      "value": "soda"
    },
    {
      "type": "synonyms",
      "value": "water"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values?version=2018-02-16"
  }
}
      

Add entity value

Add a new value to an entity.

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

POST /v1/workspaces/{workspace_id}/entities/{entity}/values
createValue(params, callback())
ServiceCall<Value> createValue(CreateValueOptions createValueOptions)
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 2018-02-16.
value body json CreateValue A CreateValue object defining the new 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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value. A synonym must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters

Pass the parameters as a Java CreateValueOptions object with the createValueOptions argument.

Name Description
workspaceId string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
metadata Map Any metadata related to the entity value.
synonyms string[ ] A List containing any synonyms for the entity value. A synonym must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value. A synonym must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";
String entityName = "beverage";
String value = "beer";

CreateValueOptions options = new CreateValueOptions.Builder(workspaceId, entityName, value).build();

Value response = service.createValue(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

Value (Java Value object)
Name Description
value string The text of the entity value.
value_text string The text of the entity value.
valueText string The text of the entity value.
metadata object Any metadata related to the entity value.
metadata Map Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
created Date The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.
updated Date The timestamp for the last update to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value.
synonyms string[ ] A List containing any synonyms for the entity value.
patterns string[ ] An array containing any patterns for the entity value.
patterns string[ ] A List containing any patterns for the entity value.
type string The type of value (synonyms or patterns). The default value is synonyms.
value_type string The type of value (synonyms or patterns). The default value is synonyms.
valueType string The type of value (synonyms or patterns). The default value is synonyms.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Example response


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

Delete entity value

Delete a value from an entity.

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

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
deleteValue(params, callback())
ServiceCall<Void> deleteValue(DeleteValueOptions deleteValueOptions)
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 2018-02-16.
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.

Pass the parameters as a Java DeleteValueOptions object with the deleteValueOptions argument.

Name Description
workspaceId 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/beer?version=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.deleteValue(params, function(err, response) {
  if (err) {
    console.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";
String entityName = "beverage";
String value = "beer";

DeleteValueOptions options = new DeleteValueOptions.Builder(workspaceId, entityName, value).build();

service.deleteValue(options).execute();
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

No response body.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Get entity value

Get information about an entity value.

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

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
getValue(params, callback())
ServiceCall<ValueExport> getValue(GetValueOptions getValueOptions)
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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java GetValueOptions object with the getValueOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";
String entityName = "beverage";
String value = "orange juice";

GetValueOptions options = new GetValueOptions.Builder(workspaceId, entityName, value).build();

ValueExport response = service.getValue(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

ValueExport (Java ValueExport object)
Name Description
value string The text of the entity value.
value_text string The text of the entity value.
valueText string The text of the entity value.
metadata object Any metadata related to the entity value.
metadata Map Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
created Date The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.
updated Date The timestamp for the last update to the entity value.
synonyms string[ ] An array containing synonyms for the entity value. You can provide either synonyms or patterns (as specified by the value of type), but not both.
synonyms string[ ] A List containing synonyms for the entity value. You can provide 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 provide either synonyms or patterns (as specified by the value of type), but not both.
patterns string[ ] A List containing patterns for the entity value. You can provide either synonyms or patterns (as specified by the value of type), but not both.
type string[ ] Specifies the type of value (synonyms or patterns).
value_type string[ ] Specifies the type of value (synonyms or patterns).
valueType string[ ] Specifies the type of value (synonyms or patterns).

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


{
  "type": "synonyms",
  "value": "orange juice"
}
        

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.

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

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
updateValue(params, callback())
ServiceCall<Value> updateValue(UpdateValueOptions updateValueOptions)
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 2018-02-16.
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
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. A synonym must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
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 current text of the entity value.
new_value string The updated text of the entity value. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
new_metadata object Any metadata related to the entity value.
new_synonyms string[ ] An array containing any synonyms for the entity value. A synonym must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters

Pass the parameters as a Java UpdateValueOptions object with the updateValueOptions argument.

Name Description
workspaceId 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.
newValue string The updated text of the entity value. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
newMetadata Map Any metadata related to the entity value.
newSynonyms string[ ] A List containing any synonyms for the entity value. A synonym must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
new_metadata object Any metadata related to the entity value.
new_synonyms string[ ] An array containing any synonyms for the entity value. A synonym must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.updateValue(params, function(err, response) {
  if (err) {
    console.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";
String entityName = "beverage";
String value = "soda";

List<String> newSynonyms = Arrays.asList("pop", "soft drink");

UpdateValueOptions options = new UpdateValueOptions.Builder(workspaceId, entityName, value)
  .newSynonyms(newSynonyms)
  .build();

Value response = service.updateValue(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

Value (Java Value object)
Name Description
value string The text of the entity value.
value_text string The text of the entity value.
valueText string The text of the entity value.
metadata object Any metadata related to the entity value.
metadata Map Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
created Date The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.
updated Date The timestamp for the last update to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value.
synonyms string[ ] A List containing any synonyms for the entity value.
patterns string[ ] An array containing any patterns for the entity value.
patterns string[ ] A List containing any patterns for the entity value.
type string The type of value (synonyms or patterns). The default value is synonyms.
value_type string The type of value (synonyms or patterns). The default value is synonyms.
valueType string The type of value (synonyms or patterns). The default value is synonyms.
Value (Java Value object)
Name Description
valueText string The text of the entity value.
metadata Map Any metadata related to the entity value.
created Date The timestamp for the creation of the entity value.
updated Date The timestamp for the last update to the entity value.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


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

Synonyms

List synonyms

List the synonyms for an entity value.

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

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms
listSynonyms(params, callback())
ServiceCall<SynonymCollection> listSynonyms(ListSynonymsOptions listSynonymsOptions)
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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java ListSynonymsOptions object with the listSynonymsOptions argument.

Name Description
workspaceId string Unique identifier of the workspace.
entity string The name of the entity (for example, beverage).
value string The text of the entity value.
pageLimit integer The number of records to return in each page of results. The default page limit is 100.
includeCount 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
    username: '{username}',
    password: '{password}',
    version_date: '2018-02-16'
});

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

conversation.listSynonyms(params, function(err, response) {
    if (err) {
        console.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";
String entityName = "beverage";
String value = "soda";

ListSynonymsOptions options = new ListSynonymsOptions.Builder(workspaceId, entityName, value).build();

SynonymCollection response = service.listSynonyms(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

SynonymCollection (Java SynonymCollection object)
Name Description
synonyms Synonym[ ] An array of synonyms.
pagination A Pagination object defining the pagination data for the returned objects.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


{
  "synonyms": [
    {
      "synonym": "pop"
    },
    {
      "synonym": "soft drink"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/entities/beverage/values/soda/synonyms?version=2018-02-16"
  }
}
      

Add synonym

Add a new synonym to an entity value.

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

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms
createSynonym(params, callback())
ServiceCall<Synonym> createSynonym(CreateSynonymOptions createSynonymOptions)
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 2018-02-16.
synonym body json CreateSynonym A CreateSynonym object defining the new synonym.
CreateSynonym
Name Description
synonym string The text of the synonym. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters

Pass the parameters as a Java CreateSynonymOptions object with the createSynonymOptions argument.

Name Description
workspaceId 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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";
String entityName = "beverage";
String value = "orange juice";
String synonym = "OJ";

CreateSynonymOptions options = new CreateSynonymOptions.Builder(workspaceId, entityName, value, synonym).build();

Synonym response = service.createSynonym(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

Synonym (Java Synonym object)
Name Description
synonym string The text of the synonym.
created string The timestamp for the creation of the synonym.
created Date The timestamp for the creation of the synonym.
updated string The timestamp for the last update to the synonym.
updated Date The timestamp for the last update to the synonym.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

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.

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

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
deleteSynonym(params, callback())
ServiceCall<Void> deleteSynonym(DeleteSynonymOptions deleteSynonymOptions)
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 2018-02-16.
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.

Pass the parameters as a Java DeleteSynonymOptions object with the deleteSynonymOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";
String entityName = "beverage";
String value = "orange juice";
String synonym = "OJ";

DeleteSynonymOptions options = new DeleteSynonymOptions.Builder(workspaceId, entityName, value, synonym).build();

service.deleteSynonym(options).execute();
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

No response body.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Get synonym

Get information about a synonym of an entity value.

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

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
getSynonym(params, callback())
ServiceCall<Synonym> getSynonym(GetSynonymOptions getSynonymOptions)
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 2018-02-16.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java GetSynonymOptions object with the getSynonymOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";
String entityName = "beverage";
String value = "orange juice";
String synonym = "OJ";

GetSynonymOptions options = new GetSynonymOptions.Builder(workspaceId, entityName, value, synonym).build();

Synonym response = service.getSynonym(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

Synonym (Java Synonym object)
Name Description
synonym string The text of the synonym.
created string The timestamp for the creation of the synonym.
created Date The timestamp for the creation of the synonym.
updated string The timestamp for the last update to the synonym.
updated Date The timestamp for the last update to the synonym.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


{
  "synonym": "OJ"
}
      

Update synonym

Update an existing entity value synonym with new text.

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

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
updateSynonym(params, callback())
ServiceCall<Synonym> updateSynonym(UpdateSynonymOptions updateSynonymOptions)
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 2018-02-16.
new_synonym body json UpdateSynonym An UpdateSynonym object defining the new synonym text.
UpdateSynonym
Name Description
synonym string The updated text of the synonym. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters

Pass the parameters as a Java UpdateSynonymOptions object with the updateSynonymOptions argument.

Name Description
workspaceId 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.
newSynonym string The updated text of the synonym. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 64 characters

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.updateSynonym(params, function(err, response) {
  if (err) {
    console.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";
String entityName = "beverage";
String value = "orange juice";
String synonym = "OJ";
String newSynonym = "O.J.";

UpdateSynonymOptions options = new UpdateSynonymOptions.Builder(workspaceId, entityName, value, synonym)
  .newSynonym(newSynonym)
  .build();

Synonym response = service.updateSynonym(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

Synonym (Java Synonym object)
Name Description
synonym string The text of the synonym.
created string The timestamp for the creation of the synonym.
created Date The timestamp for the creation of the synonym.
updated string The timestamp for the last update to the synonym.
updated Date The timestamp for the last update to the synonym.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

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.

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.

GET /v1/workspaces/{workspace_id}/intents
listIntents(params, callback())
ServiceCall<IntentCollection> listIntents(ListIntentsOptions listIntentsOptions)
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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java ListIntentsOptions object with the listIntentsOptions argument.

Name Description
workspaceId 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.
pageLimit integer The number of records to return in each page of results. The default page limit is 100.
includeCount 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.listIntents(params, function(err, response) {
  if (err) {
    console.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";

ListIntentsOptions options = new ListIntentsOptions.Builder(workspaceId).build();

IntentCollection response = service.listIntents(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

IntentCollection (Java IntentCollection object)
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.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


{
  "intents": [
    {
      "intent": "goodbye"
    },
    {
      "intent": "hello"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents?version=2017-08-21"
  }
}
        

Create intent

Create a new intent.

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

POST /v1/workspaces/{workspace_id}/intents
createIntent(params, callback())
ServiceCall<Intent> createIntents(CreateIntentOptions createIntentOptions)
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 2018-02-16.
workspace_id string The workspace ID.
intent body json CreateIntent An object defining the content of the new intent.
Name Description
workspace_id string The workspace ID.
intent string The name of the intent. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 128 characters
description string The description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
examples CreateExample[ ] An array of user input examples for the intent.

Pass the parameters as a Java CreateIntentOptions object with the createIntentOptions argument.

Name Description
workspaceId string The workspace ID.
intent string The name of the intent. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 128 characters
description string The description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
examples CreateExample[ ] A List of user input examples for the intent.
Name Description
workspace_id string The workspace ID.
intent string The name of the intent. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 128 characters
description string The description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
examples CreateExample[ ] An array of user input examples for the intent.

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

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

List<CreateExample> examples = new ArrayList<CreateExample>();
examples.add(new CreateExample.Builder("Good morning").build());
examples.add(new CreateExample.Builder("Hi there").build());

CreateIntentOptions options = new CreateIntentOptions.Builder(workspaceId, intent)
  .examples(examples)
  .build();

Intent response = service.createIntent(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

Intent
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.
Intent (Java Intent object)
Name Description
intentName string The name of the intent.
created Date The timestamp for creation of the intent.
updated Date 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

Example response


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

Delete intent

Delete an intent from a workspace.

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

DELETE /v1/workspaces/{workspace_id}/intents/{intent}
deleteIntent(params, callback())
ServiceCall<Void> deleteIntent(DeleteIntentOptions deleteIntentOptions)
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 2018-02-16.
Name Description
workspace_id string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).

Pass the parameters as a Java DeleteIntentOptions object with the deleteIntentOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

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

DeleteIntentOptions options = new DeleteIntentOptions.Builder(workspaceId, intent).build();

service.deleteIntent(options).execute();
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

No response body.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Get intent

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

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.

GET /v1/workspaces/{workspace_id}/intents/{intent}
getIntent(params, callback())
ServiceCall<IntentExport> getIntent(GetIntentOptions getIntentOptions)
get_intent(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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java GetIntentOptions object with the getIntentOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

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

GetIntentOptions options = new GetIntentOptions.Builder(workspaceId, intent).build();

IntentExport response = service.getIntent(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

IntentExport (Java IntentExport object)
Name Description
intent string The name of the intent.
intentName string The name of the intent.
created string The timestamp for creation of the intent.
created Date The timestamp for creation of the intent.
updated string The timestamp for the last update to the intent.
updated Date 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.
examples Example[ ] A List of objects describing the user input examples for the intent.

Response codes

Status Description
400 Bad Request Invalid request

Example response


{
  "intent": "hello"
}
      

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.

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

POST /v1/workspaces/{workspace_id}/intents/{intent}
updateIntent(params, callback())
ServiceCall<Intent> updateIntent(UpdateIntentOptions updateIntentOptions)
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 2018-02-16.
new_intent body json UpdateIntent An object defining the updated content of the intent.
UpdateIntent
Name Description
intent string The name of the intent. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 128 characters
description string The description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
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. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 128 characters
new_description string The updated description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
new_examples CreateExample[ ] An array of user input examples for the intent.

Pass the parameters as a Java UpdateIntentOptions object with the updateIntentOptions argument.

Name Description
workspaceId string The workspace ID.
intent string The name of the intent to update.
newIntent string The updated name of the intent. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 128 characters
newDescription string The updated description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
newExamples CreateExample[ ] A List 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. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters
  • It cannot begin with the reserved prefix sys-
  • It must be no longer than 128 characters
new_description string The updated description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
new_examples CreateExample[ ] An array of user input examples for the intent.

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.updateIntent(params, function(err, response) {
  if (err) {
    console.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";
String intent = "hello";
String description = "Updated intent";

List<CreateExample> examples = new ArrayList<CreateExample>();
examples.add(new CreateExample.Builder("Good afternoon").build());

UpdateIntentOptions options = new UpdateIntentOptions.Builder(workspaceId, intent)
  .newExamples(examples)
  .newDescription(description)
  .build();

Intent response = service.updateIntent(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

Intent
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.
Intent (Java Intent object)
Name Description
intentName string The name of the intent.
created Date The timestamp for creation of the intent.
updated Date 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

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.

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

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples
getExamples(params, callback())
ServiceCall<ExampleCollection> listExamples(ListExamplesOptions listExamplesOptions)
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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java ListExamplesOptions object with the listExamplesOptions argument.

Name Description
workspaceId string Unique identifier of the workspace.
intent string The intent name (for example, pizza_order).
pageLimit integer The number of records to return in each page of results. The default page limit is 100.
includeCount 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=2018-02-16&export=true"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.listExamples(params, function(err, response) {
  if (err) {
    console.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";
String intent = "hello";

ListExamplesOptions options = new ListExamplesOptions.Builder(workspaceId, intent).build();

ExampleCollection response = service.listExamples(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

ExampleCollection (Java ExampleCollection object)
Name Description
examples An array of Example objects describing the examples defined for the intent.
examples A List of Example objects describing the examples defined for the intent.
pagination A Pagination object defining the pagination data for the returned objects.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


{
  "examples":[
    {
      "text": "Good afternoon"
    },
    {
      "text": "hi there"
    }
  ],
  "pagination":{
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?version=2018-02-16&export=true"
  }
}
      

Create example

Add a new user input example to an intent.

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

POST /v1/workspaces/{workspace_id}/intents/{intent}/examples
createExample(params, callback())
ServiceCall<Example> createExample(CreateExampleOptions createExampleOptions)
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 2018-02-16.
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.
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters

Pass the parameters as a Java CreateExampleOptions object with the createExampleOptions argument.

Name Description
workspaceId 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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";
String intent = "hello";
String example = "Howdy!";

CreateExampleOptions options = new CreateExampleOptions.Builder(workspaceId, intent, example).build();

Example response = service.createExample(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

Example (Java Example object)
Name Description
text string The text of the user input example.
exampleText string The text of the user input example.
created string The timestamp for creation of the user input example.
created Date The timestamp for creation of the user input example.
updated string The timestamp for the last update to the user input example.
updated Date The timestamp for the last update to the user input example.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

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.

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

DELETE /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
deleteExample(params, callback())
ServiceCall<Void> deleteExample(DeleteExampleOptions deleteExampleOptions)
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 2018-02-16.
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.

Pass the parameters as a Java DeleteExampleOptions object with the deleteExampleOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";
String intent = "hello";
String example = "Good afternoon";

DeleteExampleOptions options = new DeleteExampleOptions.Builder(workspaceId, intent, example).build();

service.deleteExample(options).execute();
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

No response body.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Get example

Get information about a user input example.

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

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
getExample(params, callback())
ServiceCall<Example> getExample(GetExampleOptions getExampleOptions)
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 2018-02-16.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java GetExampleOptions object with the getExampleOptions argument.

Name Description
workspaceId 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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));
  }

});

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

String workspaceId = "9978a49e-ea89-4493-b33d-82298d3db20d";
String intent = "hello";
String example = "Good afternoon";

GetExampleOptions options = new GetExampleOptions.Builder(workspaceId, intent, example).build();

Example response = service.getExample(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

Example (Java Example object)
Name Description
text string The text of the user input example.
exampleText string The text of the user input example.
created string The timestamp for creation of the user input example.
created Date The timestamp for creation of the user input example.
updated string The timestamp for the last update to the user input example.
updated Date The timestamp for the last update to the user input example.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


{
  "text": "Good afternoon"
}
      

Update example

Update the text of a user input example.

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

POST /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
updateExample(params, callback())
ServiceCall<Example> updateExample(UpdateExampleOptions updateExampleOptions)
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 2018-02-16.
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters

Pass the parameters as a Java UpdateExampleOptions object with the updateExampleOptions argument.

Name Description
workspaceId 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.
newText string The updated text for the user input example. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters
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. This string must conform to the following restrictions:
  • It cannot contain carriage return, newline, or tab characters
  • It cannot consist of only whitespace characters
  • It must be no longer than 1024 characters

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.updateExample(params, function(err, response) {
  if (err) {
    console.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";
String intent = "hello";
String example = "Hi there";
String newText = "Hello there!";

UpdateExampleOptions options = new UpdateExampleOptions.Builder(workspaceId, intent, example)
  .newText(newText)
  .build();

Example response = service.updateExample(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

Example (Java Example object)
Name Description
text string The text of the user input example.
exampleText string The text of the user input example.
created string The timestamp for creation of the user input example.
created Date The timestamp for creation of the user input example.
updated string The timestamp for the last update to the user input example.
updated Date The timestamp for the last update to the user input example.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

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.

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

GET /v1/workspaces/{workspace_id}/dialog_nodes
listDialogNodes(params, callback())
ServiceCall<DialogNodeCollection> listDialogNodes(ListDialogNodesOptions listDialogNodesOptions)
list_dialog_nodes(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 2018-02-16.
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.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
Name Description
workspace_id string Unique identifier of the workspace.
page_limit number The number of records to return in each page of results. The default page limit is 100.
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 dialog_node and updated.
cursor string A token identifying the last object from the previous page of results.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java ListDialogNodesOptions object with the listDialogNodesOptions argument.

Name Description
workspaceId string The workspace ID.
pageLimit integer The number of records to return in each page of results. The default page limit is 100.
includeCount 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 dialog_node 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/dialog_nodes?version=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.listDialogNodes(params, function(err, response) {
  if (err) {
    console.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";

ListDialogNodesOptions options = new ListDialogNodesOptions.Builder(workspaceId).build();

DialogNodeCollection response = service.listDialogNodes(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

DialogNodeCollection (Java DialogNodeCollection object)
Name Description
dialog_nodes An array of DialogNode objects describing the dialog nodes defined for the workspace.
dialogNodes A List of DialogNode objects describing the dialog nodes defined for the workspace.
pagination A Pagination object defining the pagination data for the returned objects.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


{
  "dialog_nodes": [
    {
      "output": {
        "text": {
          "values": [
            "Hi! How can I help you?"
          ]
        }
      },
      "conditions": "#hello",
      "dialog_node": "greeting"
    }
  ]
}
      

Create dialog node

Create a new dialog node.

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

POST /v1/workspaces/{workspace_id}/dialog_nodes
createDialogNode(params, callback())
ServiceCall<DialogNode> createDialogNode(CreateDialogNodeOptions createDialogNodeOptions)
create_dialog_node(workspace_id, dialog_node, description=None, conditions=None, parent=None, previous_sibling=None, output=None, context=None, metadata=None, next_step=None, actions=None, title=None, node_type=None, event_name=None, variable=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 2018-02-16.
workspace_id string The workspace ID.
dialog_node body json CreateDialogNode A CreateDialogNode object defining the content of the new dialog node.
Name Description
workspace_id string The workspace ID.
dialog_node string The dialog node ID. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 1024 characters
description string The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
conditions string The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters.
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 array of objects describing any actions to be invoked by the dialog node.
title string The alias used to identify the dialog node. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 64 characters
node_type string How the dialog node is processed. The valid values are standard, event_handler, frame, slot, and response_condition. You can specify this value using the constants defined by the NodeType enumeration.
event_name string How an event_handler node is processed. You can specify this value using the constants defined by the EventName enumeration.
variable string The location in the dialog context where output is stored.

Pass the parameters as a Java CreateDialogNodeOptions object with the createDialogNodeOptions argument.

CreateDialogNode (Java CreateDialogNode object)
Name Description
workspaceId string The workspace ID.
dialogNode string The dialog node ID. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 1024 characters
description string The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
conditions string The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters.
parent string The ID of the parent dialog node (if any).
previousSibling string The ID of the previous sibling dialog node (if any).
output Map The output from the dialog node. See here for more information about how to specify dialog node output.
context Map The context for the dialog node.
metadata map The metadata for the dialog node.
nextStep DialogNodeNextStep An object describing the next step to be executed in dialog processing.
actions DialogNodeAction[ ] An array of objects describing any actions to be invoked by the dialog node.
title string The alias used to identify the dialog node. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 64 characters
nodeType string How the dialog node is processed. The valid values are standard, event_handler, frame, slot, and response_condition.
eventName string How an event_handler node is processed.
variable string The location in the dialog context where output 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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

var params = {
    workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
    dialog_node: 'greeting',
    conditions:'#hello',
    output: {
      text: 'Hi! How can I help you?'
    },
    title: 'Greeting'
};

conversation.createDialogNode(params, function(err, response) {
  if (err) {
    console.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";
String dialogNode = "greeting";
String conditions = "#hello";
String title = "Greeting";

Map<String, String> output = new HashMap<String, String>();
output.put("text","Hi! How can I help you?");

CreateDialogNodeOptions options = new CreateDialogNodeOptions.Builder(workspaceId, dialogNode)
  .conditions(conditions)
  .output(output)
  .title(title)
  .build();

DialogNode response = service.createDialogNode(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

response = conversation.create_dialog_node(
    workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
    dialog_node = 'greeting',
    conditions = '#hello',
    output = {
        'text': 'Hi! How can I help you?'
    },
    title = 'Greeting'
)

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

Response

DialogNode (Java DialogNode object)
Name Description
dialog_node string The dialog node ID.
dialogNode 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.
previousSibling string The ID of the previous sibling dialog node.
output object The output from the dialog node.
output Map The output from the dialog node.
context object The context (if defined) for the dialog node.
context Map The context (if defined) for the dialog node.
metadata object The metadata (if any) for the dialog node.
metadata Map The metadata (if any) for the dialog node.
next_step DialogNodeNextStep The next step to execute following this dialog node.
nextStep DialogNodeNextStep The next step to execute following this dialog node.
created string The timestamp for creation of the dialog node.
created Date The timestamp for creation of the dialog node.
updated string The timestamp for the most recent update to the dialog node.
updated Date The timestamp for the most recent update to the dialog node.
actions DialogNodeAction[ ] An array of objects defining any actions to be invoked by the dialog node.
actions DialogNodeAction[ ] A List of objects defining 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.
eventName 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

Example response


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

Delete dialog node

Delete a dialog node from a workspace.

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

DELETE /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}
deleteDialogNode(params, callback())
ServiceCall<Void> deleteDialogNode(DeleteDialogNodeOptions deleteDialogNodeOptions)
delete_dialog_node(workspace_id, dialog_node)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
dialog_node path string The dialog node ID.
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 2018-02-16.
Name Description
workspace_id string Unique identifier of the workspace.
dialog_node string The dialog node ID.

Pass the parameters as a Java DeleteDialogNodeOptions object with the deleteDialogNodeOptions argument.

Name Description
workspaceId string Unique identifier of the workspace.
dialogNode string The dialog node ID.

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.deleteDialogNode(params, function(err, response) {
  if (err) {
    console.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";
String dialogNode = "greeting";

DeleteDialogNodeOptions options = new DeleteDialogNodeOptions.Builder(workspaceId, dialogNode).build();

service.deleteDialogNode(options).execute();
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

response = conversation.delete_dialog_node(
    workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
    dialog_node = 'greeting'
)

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

Response

No response body.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Get dialog node

Get information about a dialog node.

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

GET /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}
getDialogNode(params, callback())
ServiceCall<DialogNode> getDialogNode(GetDialogNodeOptions getDialogNodeOptions)
get_dialog_node(workspace_id, dialog_node)

Request

Name Description
workspace_id path string Unique identifier of the workspace.
dialog_node path string The dialog node ID.
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 2018-02-16.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.
Name Description
workspace_id string Unique identifier of the workspace.
dialog_node string The dialog node ID.
include_audit query boolean Whether to include the audit properties (created and updated timestamps) in the response.

Pass the parameters as a Java GetDialogNodeOptions object with the getDialogNodeOptions argument.

Name Description
workspaceId string Unique identifier of the workspace.
dialogNode string The dialog node ID.

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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.getDialogNode(params, function(err, response) {
  if (err) {
    console.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";
String dialogNode = "greeting";

GetDialogNodeOptions options = new GetDialogNodeOptions.Builder(workspaceId, dialogNode).build();

DialogNode response = service.getDialogNode(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

response = conversation.get_dialog_node(
    workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
    dialog_node = 'greeting'
)

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

Response

DialogNode (Java DialogNode object)
Name Description
dialog_node string The dialog node ID.
dialogNode 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.
previousSibling string The ID of the previous sibling dialog node.
output object The output from the dialog node.
output Map The output from the dialog node.
context object The context (if defined) for the dialog node.
context Map The context (if defined) for the dialog node.
metadata object The metadata (if any) for the dialog node.
metadata Map The metadata (if any) for the dialog node.
next_step DialogNodeNextStep The next step to execute following this dialog node.
nextStep DialogNodeNextStep The next step to execute following this dialog node.
created string The timestamp for creation of the dialog node.
created Date The timestamp for creation of the dialog node.
updated string The timestamp for the most recent update to the dialog node.
updated Date The timestamp for the most recent update to the dialog node.
actions DialogNodeAction[ ] An array of objects defining any actions to be invoked by the dialog node.
actions DialogNodeAction[ ] A List of objects defining 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.
eventName 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

Example response


{
  "title": "Greeting",
  "output": {
    "text": "Hi! How can I help you?"
  },
  "conditions": "#hello",
  "dialog_node": "greeting"
}
      

Update dialog node

Update an existing dialog node with new or modified data.

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

POST /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}
updateDialogNode(params, callback())
ServiceCall<DialogNode> updateDialogNode(UpdateDialogNodeOptions updateDialogNodeOptions)
update_dialog_node(workspace_id, dialog_node, new_dialog_node, new_description=None, new_conditions=None, new_parent=None, new_previous_sibling=None, new_output=None, new_context=None, new_metadata=None, new_next_step=None, new_title=None, new_type=None, new_event_name=None, new_variable=None, new_actions=None)

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 2018-02-16.
new_dialog_node body json UpdateDialogNode An UpdateDialogNode object defining the updated content of the dialog node.
UpdateDialogNode
Name Description
dialog_node string The updated dialog node ID. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 1024 characters
description string The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
conditions string The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters.
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. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 64 characters
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 array of objects describing any actions to be invoked by the dialog node.
Name Description
workspace_id string The workspace ID.
dialog_node string The ID of the dialog node to update.
new_dialog_node string The new dialog node ID. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 1024 characters
new_description string The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
new_conditions string The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters.
new_parent string The ID of the parent dialog node (if any).
new_previous_sibling string The ID of the previous sibling dialog node (if any).
new_output object The output from the dialog node. See here for more information about how to specify dialog node output.
new_context object The context for the dialog node.
new_metadata object The metadata for the dialog node.
new_next_step DialogNodeNextStep An object describing the next step to be executed in dialog processing.
new_actions DialogNodeAction[ ] An array of objects describing any actions to be invoked by the dialog node.
new_title string The alias used to identify the dialog node. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 64 characters
new_type string How the dialog node is processed. The valid values are standard, event_handler, frame, slot, and response_condition. You can specify this value using the constants defined by the NodeType enumeration.
new_event_name string How an event_handler node is processed. You can specify this value using the constants defined by the EventName enumeration.
new_variable string The location in the dialog context where output is stored.

Pass the parameters as a Java UpdateDialogNodeOptions object with the updateDialogNodeOptions argument.

Name Description
workspaceId string Unique identifier of the workspace.
dialogNode string The ID of the dialog node to update.
newActions DialogNodeAction[ ] A List of objects describing any actions to be invoked by the dialog node.
newConditions string The condition that will trigger the dialog node.
newContext Map The context for the dialog node.
newDescription string The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
newDialogNode string The updated dialog node ID. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 1024 characters
newEventName string How an event_handler node is processed.
newMetadata Map The metadata for the dialog node.
newNextStep DialogNodeNextStep An object describing the next step to be executed in dialog processing.
newOutput Map The output from the dialog node. See here for more information about how to specify dialog node output.
newParent string The ID of the parent dialog node (if any).
newPreviousSibling string The ID of the previous sibling dialog node (if any).
newTitle string The alias used to identify the dialog node. This string must conform to the following restrictions:
  • It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters
  • It must be no longer than 64 characters
newVariable string The location in the dialog context where output is stored.
nodeType string How the dialog node is processed. The valid values are standard, event_handler, frame, slot, and response_condition.

Example request


curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"output\":{\"text\":\"Hello! What can I do for you?\"}}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/dialog_nodes/greeting?version=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  dialog_node: 'greeting',
  new_dialog_node: 'greeting',
  new_output: {
    text: 'Hello! What can I do for you?'
  }
};

conversation.updateDialogNode(params, function(err, response) {
  if (err) {
    console.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";
String dialogNode = "greeting";
String newDialogNode = "greeting";

Map<String, String> newOutput = new HashMap<String, String>();
newOutput.put("text","Hello! What can I do for you?");

UpdateDialogNodeOptions options = new UpdateDialogNodeOptions.Builder(workspaceId, dialogNode, newDialogNode)
  .newOutput(newOutput)
  .build();

DialogNode response = service.updateDialogNode(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

response = conversation.update_dialog_node(
    workspace_id = '9978a49e-ea89-4493-b33d-82298d3db20d',
    dialog_node = 'greeting',
    new_dialog_node = 'greeting',
    new_output = {
        'text': 'Hello! What can I do for you?'
    }
)

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

Response

DialogNode (Java DialogNode object)
Name Description
dialog_node string The dialog node ID.
dialogNode 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.
previousSibling string The ID of the previous sibling dialog node.
output object The output from the dialog node.
output Map The output from the dialog node.
context object The context (if defined) for the dialog node.
context Map The context (if defined) for the dialog node.
metadata object The metadata (if any) for the dialog node.
metadata Map The metadata (if any) for the dialog node.
next_step DialogNodeNextStep The next step to execute following this dialog node.
nextStep DialogNodeNextStep The next step to execute following this dialog node.
created string The timestamp for creation of the dialog node.
created Date The timestamp for creation of the dialog node.
updated string The timestamp for the most recent update to the dialog node.
updated Date The timestamp for the most recent update to the dialog node.
actions DialogNodeAction[ ] An array of objects defining any actions to be invoked by the dialog node.
actions DialogNodeAction[ ] A List of objects defining 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.
eventName 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

Example response


{
  "title": "Greeting",
  "output": {
    "text": "Hello! What can I do for you?"
  },
  "created": "2017-06-28T17:09:31.523Z",
  "updated": "2017-06-28T19:57:05.300Z",
  "conditions": "#hello",
  "dialog_node": "greeting"
}
      

Logs

List log events in a workspace

List the events from the log of a specific workspace.

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.

GET /v1/workspaces/{workspace_id}/logs
listLogs(params, callback())
ServiceCall<LogCollection> listLogs(ListLogsOptions listLogsOptions)
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 2018-02-16.
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.

Pass the parameters as a Java ListLogsOptions object with the listLogsOptions argument.

Name Description
workspaceId 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.
pageLimit 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.
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=2018-02-16"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

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

conversation.listLogs(params, function(err, response) {
  if (err) {
    console.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";

ListLogsOptions options = new ListLogsOptions.Builder(workspaceId).build();

LogCollection response = service.listLogs(options).execute();

System.out.println(response);
      

import json
import watson_developer_cloud

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

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

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

Response

LogCollection (Java LogCollection object)
Name Description
logs An array of LogExport objects describing log events.
logs A List of LogExport objects describing log events.
pagination A LogPagination object defining the pagination data for the returned objects.
LogExport (Java LogExport object)
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.
logId string A unique identifier for the logged event.
request_timestamp string The timestamp for receipt of the message.
requestTimestamp string The timestamp for receipt of the message.
response_timestamp string The timestamp for the system response to the message.
responseTimestamp 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 (Java LogPagination object)
Name Description
next_url string The URL that will return the next page of results, if any.
nextUrl string The URL that will return the next page of results, if any.
cursor string A token identifying the last object from the previous page of results.
matched integer Reserved for future use.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

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": {}
}
      

List log events in all workspaces

List the events from the logs of all workspaces in the service instance.

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.

GET /v1/logs
listAllLogs(params, callback())
ServiceCall<LogCollection> listAllLogs(ListAllLogsOptions listAllLogsOptions)

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 2018-02-16.
filter query string A cacheable parameter that limits the results to those matching the specified filter. When listing log events for all workspaces, you must specify a filter query that includes a value for language, as well as a value for workspace_id or request.context.metadata.deployment. 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
filter string A cacheable parameter that limits the results to those matching the specified filter. When listing log events for all workspaces, you must specify a filter query that includes a value for language, as well as a value for workspace_id or request.context.metadata.deployment. 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.

Pass the parameters as a Java ListAllLogsOptions object with the listAllLogsOptions argument.

Name Description
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. When listing log events for all workspaces, you must specify a filter query that includes a value for language, as well as a value for workspace_id or request.context.metadata.deployment. For more information, see Filter query reference.
pageLimit 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/logs?version=2018-02-16&filter=(language::en,request.context.metadata.deployment::deployment_1)"

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

var conversation = new watson.ConversationV1({
  username: '{username}',
  password: '{password}',
  version_date: '2018-02-16'
});

var params = {
  filter: 'language::en,request.context.metadata.deployment::testDeployment'
};

conversation.listAllLogs(params, function(err, response) {
  if (err) {
    console.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 filter = "language::en,request.context.metadata.deployment::testDeployment";

ListAllLogsOptions options = new ListAllLogsOptions.Builder(filter).build();

LogCollection response = service.listAllLogs(options).execute();

System.out.println(response);
      
Coming soon.
      

Response

LogCollection (Java LogCollection object)
Name Description
logs An array of LogExport objects describing log events.
pagination A LogPagination object defining the pagination data for the returned objects.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Example response


{
  "logs": [
    {
      "request": {
        "input": {
          "text": "Good morning"
        },
        "context": {
          "metadata": {
            "deployment": "deployment_1"
          }
        }
      },
      "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": {
          "metadata": {
            "deployment": "deployment_1"
          },
          "conversation_id": "81a43b48-7dca-4a7d-a0d7-6fed03fcee69",
          "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-13T19:52:32.611Z",
      "response_timestamp": "2017-09-13T19:52:32.628Z",
      "log_id": "aa886a8a-bac5-4b91-8323-2fd61a69c9d3"
    }
  ],
  "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.
code integer HTTP status code for the error response.
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"
  "code" : 404
}
        

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.

Pagination (Java Pagination object)
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 request


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

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

var conversation = new watson.ConversationV1({
    username: '{username}',
    password: '{password}',
    version_date: '2018-02-16'
});

var 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='2018-02-16'
)

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=2018-02-16",
    "next_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?cursor=eyJtb2RpZmllZCI6eyJ2YWx1ZSI6IjIwMTctMDgtMThUMTg6MDU6NDguMTUzWiIsIm9yZGVyIjoiZGVzYyJ9LCJ0ZXh0Ijp7InZhbHVlIjoiR29vZCBtb3JuaW5nIiwib3JkZXIiOiJhc2MiLCJ0aWVfYnJlYWtlciI6dHJ1ZX19&page_limit=2&sort=-modified&version=2018-02-16"
  }
}
        

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 method 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 set_default_headers method 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=2018-02-16"
        

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
  }
});
        

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

conversation = watson_developer_cloud.ConversationV1(
    username='{username}',
    password='{password}',
    version='2018-02-16'
)

conversation.set_default_headers({'X-Watson-Learning-Opt-Out': "true"})