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

npm

npm install watson-developer-cloud

Maven

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

Gradle

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

pip

pip install --upgrade watson-developer-cloud

API explorer

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

Authentication

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

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

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

Replace {username} and {password} with your credentials


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

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

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

ConversationService service = new ConversationService("2017-05-26");
service.setUsernameAndPassword("{username}", "{password}");
      

from watson_developer_cloud import ConversationV1

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

Versioning

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

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

The current version is 2017-05-26.

Workspaces

List workspaces

List the workspaces associated with a Conversation service instance.

GET /v1/workspaces

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about all workspaces associated with the service instance.

Name Description
workspaces An array of WorkspaceResponse objects describing the workspaces associated with the service instance.
pagination A Pagination object defining the pagination data for the returned objects.
WorkspaceResponse
Name Description
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
metadata object Any metadata related to the workspace.
created string The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
workspace_id string The workspace ID.
Pagination
Name Description
refresh_url string The URL that will return the same page of results.
next_url string The URL that will return the next page of results, if any.
total integer Reserved for future use.
matched integer Reserved for future use.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Create workspace

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

This operation is limited to 30 requests per 30 minutes.

POST /v1/workspaces

  

  

  

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace body json WorkspaceRequest A Workspace object defining the content of the new workspace.
WorkspaceRequest
Name Description
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
metadata object Any metadata related to the workspace.
counterexamples CreateExample[ ] An array of objects defining input examples that have been marked as irrelevant input.
dialog_nodes object[ ] 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.
CreateExample
Name Description
text string The text of a user input example.
CreateEntity
Name Description
entity string The name of the entity (for example, beverage).
description string The description of the entity.
metadata object Any metadata related to the entity.
values CreateValue[ ] An array of entity values.
fuzzy_match boolean Whether to use fuzzy matching for the entity.
CreateIntent
Name Description
intent string The name of the intent.
description string The description of the intent.
examples CreateExample[ ] An array of user input examples for the intent.
CreateValue
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value.

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the workspace that was created.

Name Description
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
metadata object Any metadata that is required by the workspace.
created string The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
workspace_id string The workspace ID.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Delete workspace

Delete a workspace from the service instance.

This operation is limited to 30 requests per 30 minutes.

DELETE /v1/workspaces/{workspace_id}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns an empty object.

Response codes

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

Rate limit

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

Example response


{}
        

Get workspace

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

GET /v1/workspaces/{workspace_id}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

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

Name Description
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
metadata object Any metadata that is required by the workspace.
created string The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
workspace_id string The workspace ID.
status string The current status of the workspace (Non Existent, Training, Failed, Available, or Unavailable).
intents IntentExportResponse[ ] An array of objects describing the intents for the workspace.
entities EntityExportResponse[ ] An array of objects describing the entities for the workspace.
counterexamples ExampleResponse[ ] An array of objects describing the user input examples that have been marked as irrelevant input.
dialog_nodes object[ ] An array of objects describing the dialog nodes for the workspace.
IntentExportResponse
Name Description
intent string The name of the intent.
description string The description of the intent.
created string The timestamp for creation of the intent.
updated string The timestamp for the last update to the intent.
examples ExampleResponse[ ] An array of objects describing the user input examples for the intent.
EntityExportResponse
Name Description
entity string The name of the entity (for example, beverage).
description string The description of the entity.
type string Reserved for future use.
source string The source of the entity. For system entities, system.entities is returned.
created string The timestamp for creation of the entity.
updated string The timestamp for the last update to the entity.
values ValueExportResponse[ ] An array of objects describing the entity values.
fuzzy_match boolean Whether fuzzy matching is used for the entity.
ExampleResponse
Name Description
created string The timestamp for creation of the user input example.
updated string The timestamp for the last update to the user input example.
text string The text of the user input example.
ValueExportResponse
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value.

Response codes

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

Rate limit

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

Example response


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

Update workspace

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

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

POST /v1/workspaces/{workspace_id}

  

  

  

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace body json UpdateWorkspace The JSON data defining the new and updated workspace content.
UpdateWorkspace
Name Description
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
metadata object Any metadata that is required by the workspace.
counterexamples CreateExample[ ] An array of objects defining input examples that have been marked as irrelevant input.
dialog_nodes object[ ] 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.
CreateExample
Name Description
text string The text of a user input example.
CreateEntity
Name Description
entity string The name of the entity (for example, beverage).
description string The description of the entity.
metadata object Any metadata related to the entity.
values CreateValue[ ] An array of entity values.
fuzzy_match boolean Whether to use fuzzy matching for the entity.
CreateIntent
Name Description
intent string The name of the intent.
description string The description of the intent.
examples CreateExample[ ] An array of user input examples for the intent.
CreateValue
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value.

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the workspace that was updated.

Name Description
name string The name of the workspace.
description string The description of the workspace.
language string The language of the workspace.
metadata object Any metadata that is required by the workspace.
created string The timestamp for creation of the workspace.
updated string The timestamp for the last update to the workspace.
workspace_id string The workspace ID.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Messages

Send message

Get a response to a user's input.

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

Request

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

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

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

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

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

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


curl -X POST -u "{username}":"{password}" —-header "Content-Type:application/json" --data "{\"input\": {\"text\": \"Turn on the lights\"}, \"context\": {\"conversation_id\": \"1b7b67c0-90ed-45dc-8508-9488bc483d5b\", \"system\": {\"dialog_stack\":[{\"dialog_node\":\"root\"}], \"dialog_turn_counter\": 1, \"dialog_request_counter\": 1}}}" "https://gateway.watsonplatform.net/conversation/api/v1/workspaces/25dfa8a0-0263-471b-8980-317e68c30488/message?version=2017-05-26"

Example request


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

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

// Replace with the context obtained from the initial request
var context = {};

conversation.message({
  workspace_id: '25dfa8a0-0263-471b-8980-317e68c30488',
  input: {'text': 'Turn on the lights'},
  context: context
},  function(err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});

ConversationService service = new ConversationService("2017-05-26");
service.setUsernameAndPassword("{username}", "{password}");


MessageRequest newMessage = new MessageRequest.Builder()
  .inputText("Turn on the lights")
  // Replace with the context obtained from the initial request
  //.context(...)
  .build();

String workspaceId = "25dfa8a0-0263-471b-8980-317e68c30488";

MessageResponse response = service
  .message(workspaceId, newMessage)
  .execute();

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

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

# Replace with the context obtained from the initial request
context = {}

workspace_id = '25dfa8a0-0263-471b-8980-317e68c30488'

response = conversation.message(
  workspace_id=workspace_id,
  message_input={'text': 'Turn on the lights'},
  context=context
)

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

Response

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

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

Response codes

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

Rate limit

There is no rate limit for this operation.

Example response


{
  "input": {
    "text": "Turn on the lights"
  },
  "context": {
    "conversation_id": "f1ab5f76-f41b-47b4-a8dc-e1c32b925b79",
    "system": {
      "dialog_stack": [
        {
          "dialog_node": "root"
        }
      ],
      "dialog_turn_counter": 2,
      "dialog_request_counter": 2
    },
    "defaultCounter": 0
  },
  "entities": [
    {
      "entity": "appliance",
      "location": [12, 18],
      "value": "light",
      "confidence": 1
    }
  ],
  "intents": [
    {
      "intent": "turn_on",
      "confidence": 0.99
    }
  ],
  "output": {
   "log_messages": [],
    "text": [
      "Ok. Turning on the light."
    ],
    "nodes_visited": [
      "node_1_1467221909631",
      "node_2_1467232480480"
    ]
  }
}
        

Counterexamples

List counterexamples

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

GET /v1/workspaces/{workspace_id}/counterexamples

Request

Name Description
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
workspace_id string The workspace ID.
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.

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about all counterexamples for the workspace.

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Create counterexample

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

POST /v1/workspaces/{workspace_id}/counterexamples

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the user input example that was added as a counterexample.

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

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Delete counterexample

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

DELETE /v1/workspaces/{workspace_id}/counterexamples/{text}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


{}
        

Get counterexample

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

GET /v1/workspaces/{workspace_id}/counterexamples/{text}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

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

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Update counterexample

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

POST /v1/workspaces/{workspace_id}/counterexamples/{text}

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the counterexample that was updated.

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Entities

List entities

List the entities for a workspace.

GET /v1/workspaces/{workspace_id}/entities

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about all entities defined for the workspace.

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Create entity

Create a new entity.

POST /v1/workspaces/{workspace_id}/entities

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the entity that was created.

Name Description
entity string The name of the entity (for example, beverage).
description string The description of the entity.
created string The timestamp for creation of the entity.
updated string The timestamp for the last update to the entity.
metadata object Any metadata related to the entity.

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Delete entity

Delete an entity from a workspace.

DELETE /v1/workspaces/{workspace_id}/entities/{entity}

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


{}
        

Get entity

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

GET /v1/workspaces/{workspace_id}/entities/{entity}

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

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

Name Description
entity string The name of the entity (for example, beverage).
description string The description of the entity.
created string The timestamp for creation of the entity.
updated string The timestamp for the last update to the entity.
metadata object Any metadata related to the entity.
values ValueExportResponse[ ] An array of objects describing the entity values.
fuzzy_match boolean Whether fuzzy matching is used for the entity.
ValueExportResponse
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value.

Response codes

Status Description
400 Bad Request Invalid request

Rate limit

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

Example response


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

Update entity

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

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

POST /v1/workspaces/{workspace_id}/entities/{entity}

Request

Name Description
workspace_id path string The workspace ID.
entity path string The name of the entity to update.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
new_entity body json UpdateEntity An UpdateEntity object defining the updated content of the entity.
UpdateEntity
Name Description
entity string The name of the entity (for example, beverage).
description string The description of the entity.
metadata object Any metadata related to the entity.
values CreateValue[ ] An array of entity values.
fuzzy_match boolean Whether to use fuzzy matching for the entity.
CreateValue
Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value.

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the entity that was updated.

Name Description
entity string The name of the entity (for example, beverage).
description string The description of the entity.
created string The timestamp for creation of the entity.
updated string The timestamp for the last update to the entity.
metadata object Any metadata related to the entity.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Values

List entity values

List the values for an entity.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about all values defined for the specified entity.

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Add entity value

Add a new value to an entity.

POST /v1/workspaces/{workspace_id}/entities/{entity}/values

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the entity value that was added.

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

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Delete entity value

Delete a value from an entity.

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


{}
        

Get entity value

Get information about an entity value.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

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

Name Description
value string The text of the entity value.
metadata object Any metadata related to the entity value.
created string The timestamp for the creation of the entity value.
updated string The timestamp for the last update to the entity value.
synonyms string[ ] An array containing any synonyms for the entity value.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Update entity value

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

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

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the entity value that was updated.

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Synonyms

List synonyms

List the synonyms for an entity value.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

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

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Add synonym

Add a new synonym to an entity value.

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms

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 body json CreateSynonym A CreateSynonym object defining the new synonym.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
CreateSynonym
Name Description
synonym string The text of the synonym.

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the synonym that was added.

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

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Delete synonym

Delete a synonym from an entity value.

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


{}
        

Get synonym

Get information about a synonym of an entity value.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

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

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Update synonym

Update an existing entity value synonym with new text.

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}

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.
new_synonym body json UpdateSynonym An UpdateSynonym object defining the new synonym text.
version query string The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2017-05-26.
UpdateSynonym
Name Description
synonym string The updated text of the synonym.

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the synonym that was updated.

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Intents

List intents

List the intents for a workspace.

GET /v1/workspaces/{workspace_id}/intents

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about all intents defined for the workspace.

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


{
  "intents":
  [
    {
      "intent":"hello",
      "created":"2017-02-02T21:04:26.049Z",
      "updated":"2017-02-02T21:04:26.049Z",
      "examples":
      [
        {
          "text":"good morning",
          "created":"2017-02-02T21:04:26.049Z",
          "updated":"2017-02-02T21:04:26.049Z"
        },
        {
          "text":"hello",
          "created":"2017-02-02T21:04:26.049Z",
          "updated":"2017-02-02T21:04:26.049Z"
        }
      ],
      "description":null
    }
  ],
  "pagination":
  {
    "refresh_url":"/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents?version=2017-05-26&export=true"
  }
}
        

Create intent

Create a new intent.

POST /v1/workspaces/{workspace_id}/intents

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the intent that was created.

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

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Delete intent

Delete an intent from a workspace.

DELETE /v1/workspaces/{workspace_id}/intents/{intent}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


{}
        

Get intent

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

GET /v1/workspaces/{workspace_id}/intents/{intent}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

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

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

Response codes

Status Description
400 Bad Request Invalid request

Rate limit

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

Example response


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

Update intent

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

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

POST /v1/workspaces/{workspace_id}/intents/{intent}

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the intent that was updated.

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Examples

List examples

List the user input examples for an intent.

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

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

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Create example

Add a new user input example to an intent.

POST /v1/workspaces/{workspace_id}/intents/{intent}/examples

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the user input example that was added.

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

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Delete example

Delete a user input example from an intent.

DELETE /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


{}
        

Get example

Get information about a user input example.

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

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

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Update example

Update the text of a user input example.

POST /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the user input example that was updated.

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Dialog nodes

List dialog nodes

List the dialog nodes for a workspace.

GET /v1/workspaces/{workspace_id}/dialog_nodes

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about all dialog nodes for the workspace.

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Create dialog node

Create a new dialog node.

POST /v1/workspaces/{workspace_id}/dialog_nodes

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the dialog node that was created.

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

Response codes

Status Description
201 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Delete dialog node

Delete a dialog node from a workspace.

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

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns an empty object.

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


{}
        

Get dialog node

Get information about a dialog node.

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

  

  

  

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the dialog node.

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

Response codes

Status Description
400 Bad Request Invalid request

Rate limit

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

Example response


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

Update dialog node

Update an existing dialog node with new or modified data.

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

Request

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

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

Returns information about the dialog node that was updated.

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


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

Logs

List log events

List the events from the log of a workspace.

GET /v1/workspaces/{workspace_id}/logs

Request

Name Description
workspace_id string The workspace 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 2017-05-26.
filter query string A cacheable parameter that limits the results to those matching the specified filter. For more information, see Filter query reference.
sort query string The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). The only supported value is request_timestamp.
page_limit query integer The number of records to return in each page of results. The default page limit is 100.
cursor query string A token identifying the last object from the previous page of results.

Example request


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

Example request

Coming soon.
      
Coming soon.
      
Coming soon.
      

Response

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

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

Response codes

Status Description
200 OK Successful request
400 Bad Request Invalid request

Rate limit

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

Example response


{
  "logs": [
    {
      "request": {
        "input": {
          "text": "Good morning"
        },
        "alternate_intents": "true",
        "context": {
          "conversation_id": "1b7b67c0-90ed-45dc-8508-9488bc483d5b",
          "system": {
            "dialog_stack": [
              {
                "dialog_node_s": "root"
              }
            ],
            "dialog_turn_counter": 1,
            "dialog_request_counter": 1
          }
        }
      },
      "response": {
        "intents": [
          {
            "intent": "hello",
            "confidence": 0.800764799118042
          }
        ],
        "entities": [],
        "input": {
          "text": "Good morning"
        },
        "output": {
          "log_messages": [],
          "text": [
            "Hi."
          ],
          "nodes_visited": [
            "node_1_1486069472111"
          ]
        },
        "context": {
          "conversation_id": "1b7b67c0-90ed-45dc-8508-9488bc483d5b",
          "system": {
            "dialog_stack": [
              {
                "dialog_node": "node_1_1486069472111"
              }
            ],
            "dialog_turn_counter": 2,
            "dialog_request_counter": 2,
            "_node_output_map": {
              "node_1_1486069472111": [
                0,
                1,
                0,
                3,
                2
              ]
            }
          }
        },
        "alternate_intents": true
      },
      "log_id": "7c19d055-2ddb-4873-9f97-a2dbdccaccb7",
      "request_timestamp": "2017-04-11T15:27:27.124Z"
    }
  ],
  "pagination": {
    "next_url": "/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/logs?cursor=dOfVSuh6fBrVJ0gXGiMuA1v3XxPaLYPmLWx+ovvixyaoqNDssEBE2EkHdcGVhztiE/MZ3HAsaBKQNw9ZZgUauLGqGXHb90NKI8sYxGGyNmm3zXnomHBRRAVeXLO3Cpw7afXT2oXxf+ZxaWJPnjDt82dWiB6hBVpwt0h8OWEaCwyUJFST2ij8hnMeV1eIl/t8O4BcoInOzXiVeY0T449v2WY7IT9tcr8JKQkP8Axg5YeelKfnx4va6I309zT+9apuADLPUONyQXZthlwRorDXNvyWtQKPcJepOXTuEWXd8Fsls2DDwROQQxSr13UVlISOwZ3VOUMYv5J4YjGklWTAA3lKLUCtO4la+ddZ82gggGy+bt5gKtMlnmSY2mFPFbSxUwrkXPFCtp64V1INEfL7b53NiYprWv9qvHVK8vkrlYhgqWupselgaqHgqSxjHfBM0BriY8rQWqNT4gQuMGB9b7P8YzQaFT2iWHm7zyH20+GgjXGmByLgTuTmQ0cBPevUXy/y5QBm8Qk026XZPgTxRYywWnmKtodFjacS/kovMfpfc4flxzlyrVse5zaE3fZQTha5XMlYVOexiGYNc7I9o+22uXZLG5PbrmZ1+TPs8yDFXcyKL/brVg4ORQU86smbSf7p8NGOHIDmwoNTTAhUmdLSLOgLw0zpE1uOx+BQXGk=&page_limit=2&sort=-request_timestamp&version=2017-05-26"
  }
}
        

Error handling

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

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

Common exceptions thrown

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

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

Error format

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

Example error


{
  "error": "Resource not found"
}
        

Pagination

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

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

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

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

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

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

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

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

Example request


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

Example response


{
...
    "pagination": {
        "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/test/examples?page_limit=10&sort=-modified&version=2017-05-26",
        "next_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/test/examples?cursor=eyJtb2RpZmllZCI6eyJ2YWx1ZSI6IjIwMTctMDMtMDNUMjE6MTg6MjMuOTI0WiIsIm9yZGVyIjoiZGVzYyJ9LCJ0ZXh0Ijp7InZhbHVlIjoibmluZXRlZW4iLCJvcmRlciI6ImFzYyIsInRpZV9icmVha2VyIjp0cnVlfX0=&page_limit=10&sort=-modified&version=2017-05-26"
    }
}
        

Rate limiting

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

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

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

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

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

Data collection

By default, all Watson services log requests and their results. Logging is done only to improve the services for future users. The logged data is not shared or made public. To prevent IBM from accessing your data for general service improvements, set the X-Watson-Learning-Opt-Out header parameter to true for all requests. (Any value other than false or 0 disables request logging for that call.) You must set the header on each request that you do not want IBM to access. set the X-Watson-Learning-Opt-Out header parameter to true when you create the service instance. (Any value other than false or 0 disables request logging for that call.) You must set the header when you create the service for any any call that you do not want IBM to access. set the x-watson-learning-opt-out header parameter to true when you create the service instance. (Any value other than false or 0 disables request logging for that call.) You must set the header when you create the service for any any call that you do not want IBM to access.