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-02-03'
});
      

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

from watson_developer_cloud import ConversationV1

conversation = ConversationV1(
  username='{username}',
  password='{password}',
  version='2017-02-03'
)
      

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-02-03.

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-02-03.
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, modified, and workspace_id.
cursor query string A token identifying the last value from the previous page of results.

Example request


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

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 PaginationResponse 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 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.
PaginationResponse
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-02-03"
      },
      "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-02-03"
      },
      "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-02-03"
      },
      "description": "Example workspace to try out the service",
      "workspace_id": "293b58fc-3c5b-4ac5-a8f4-8d52c393d875"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces?version=2017-02-03"
  }
}
        

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-02-03.
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 that is required by the workspace.
counterexamples CreateExample[ ] An array of CreateExample objects defining input examples that have been marked as irrelevant input.
dialog_nodes CreateDialogNode[ ] An array of CreateDialogNode objects defining the nodes in the workspace dialog.
entities CreateEntity[ ] An array of CreateEntity objects defining the entities for the workspace.
intents CreateIntent[ ] An array of CreateIntent objects defining the intents for the workspace.
CreateExample
Name Description
text string The text of a user input example.
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.
previous_sibling string The ID of the previous sibling dialog node.
output DialogNodeOutput The output from the dialog node.
context object The context for the dialog node.
metadata object The metadata for the dialog node.
go_to DialogNodeGoTo The location to go to when the dialog node is triggered.
CreateEntity
Name Description
entity string The name of the entity.
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.
open_list boolean Reserved for future use.
values CreateValue[ ] An array of entity values.
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.
DialogNodeOutput
Name Description
text string The output text of the dialog node.
DialogNodeGoTo
Name Description
dialog_node string The ID of the dialog node to go to.
selector string Where in the target node focus is to be passed to.
return boolean Reserved for future use.
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-02-03"

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-02-03.

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-02-03"

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-02-03.
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-02-03"

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 return data 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 IntentExportResponse objects describing the intents for the workspace.
entities EntityExportResponse[ ] An array of EntityExportResponse objects describing the entities for the workspace.
counterexamples ExampleResponse[ ] An array of ExampleResponse objects describing the user input examples that have been marked as irrelevant input.
dialog_nodes DialogNodeResponse[ ] An array of DialogNodeResponse 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 ExampleResponse objects describing the user input examples for the intent.
EntityExportResponse
Name Description
entity string The name of the entity.
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.
open_list boolean Reserved for future use.
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 ValueExportResponse objects describing the entity values.
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.
DialogNodeResponse
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.
previous_sibling string The ID of the previous sibling dialog node.
output DialogNodeOutput The output from the dialog node.
context object The context for the dialog node.
metadata object The metadata for the dialog node.
go_to DialogNodeGoTo The location to go to when the dialog node is triggered.
created string The timestamp for creation of the dialog node.
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.
DialogNodeOutput
Name Description
text string The output text of the dialog node.
DialogNodeGoTo
Name Description
dialog_node string The ID of the dialog node to go to.
selector string Where in the target node focus is to be passed to.
return boolean Reserved for future use.

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-02-03.
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 CreateExample objects defining input examples that have been marked as irrelevant input.
dialog_nodes CreateDialogNode[ ] An array of CreateDialogNode objects defining the nodes in the workspace dialog.
entities CreateEntity[ ] An array of CreateEntity objects defining the entities for the workspace.
intents CreateIntent[ ] An array of CreateIntent objects defining the intents for the workspace.
CreateExample
Name Description
text string The text of a user input example.
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.
previous_sibling string The ID of the previous sibling dialog node.
output DialogNodeOutput The output from the dialog node.
context object The context for the dialog node.
metadata object The metadata for the dialog node.
go_to DialogNodeGoTo The location to go to when the dialog node is triggered.
CreateEntity
Name Description
entity string The name of the entity.
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.
open_list boolean Reserved for future use.
values CreateValue[ ] An array of entity values.
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.
DialogNodeOutput
Name Description
text string The output text of the dialog node.
DialogNodeGoTo
Name Description
dialog_node string The ID of the dialog node to go to.
selector string Where in the target node focus is to be passed to.
return boolean Reserved for future use.
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-02-03"

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-02-03.
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 A SystemResponse object that includes information about the dialog.
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.
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.
SystemResponse
Name Description
dialog_stack DialogStack[ ]

An array of DialogStack objects identifying the dialog nodes that are in focus in the conversation.

dialog_turn_counter integer The number of cycles of user input and response in this conversation.
dialog_request_counter integer The number of inputs in this conversation. This counter might be higher than the dialog_turn_counter counter when multiple inputs are needed before a response can be returned.
LogMessageResponse
Name Description
level string The severity of the message (info, error, or warn).
msg string The text of the log message.
DialogStack
Name Description
dialog_node string The ID of a dialog node.

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-02-03"

Example request


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

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

// 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-02-03");
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-02-03'
)

# 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.
RuntimeContext
Name Description
conversation_id string The unique identifier of the conversation.
system RuntimeSystemContext A RuntimeSystemContext object that includes information about the dialog.
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.
RuntimeSystemContext
Name Description
dialog_stack RuntimeDialogStack[ ]

An array of RuntimeDialogStack objects identifying the dialog nodes that are in focus in the conversation.

If no nodes are in the array, the conversation restarts at the root with the next request. If multiple dialog nodes are in the array, several dialogs are in progress, and the last node in the array is active. When the active dialog ends, it is removed from the stack and the previous one becomes active.

dialog_turn_counter integer The number of cycles of user input and response in this conversation.
dialog_request_counter integer The number of inputs in this conversation. This counter might be higher than the dialog_turn_counter counter when multiple inputs are needed before a response can be returned.
RuntimeLogMessage
Name Description
level string The severity of the message (info, error, or warn).
msg string The text of the message.
RuntimeDialogStack
Name Description
dialog_node string The ID of a dialog node.
invoked_subdialog string Reserved for future use.

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"
    }
  ],
  "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

Get 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-02-03.
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 modified.
cursor query string A token identifying the last value from the previous page of results.
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, modified, and intent_id.
cursor query string A token identifying the last value 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-02-03"

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 PaginationResponse 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.
PaginationResponse
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-02-03"
  }
}
        

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-02-03.
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-02-03"

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-02-03.
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-02-03"

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-02-03.
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-02-03"

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-02-03.
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-02-03"

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

Intents

Get 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-02-03.
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, modified, and intent_id.
cursor query string A token identifying the last value 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-02-03?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 PaginationResponse 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 ExampleResponse objects describing the user input examples for the intent.
PaginationResponse
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-02-03&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-02-03.
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-02-03"

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 30 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-02-03.

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-02-03"

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 30 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-02-03.
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-02-03"

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 return data 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 ExampleResponse 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-02-03.
new_intent body json CreateIntent 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-02-03"

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
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-16T22:08:13.352Z",
  "updated":"2017-02-16T22:41:45.400Z",
  "description":"Updated intent"
}
        

Examples

Get 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-02-03.
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, modified, and example_id.
cursor query string A token identifying the last value 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-02-03&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 PaginationResponse 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.
PaginationResponse
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-02-03&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-02-03.
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-02-03"

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-02-03.

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-02-03"

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-02-03.

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-02-03"

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-02-03.
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-02-03"

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

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 Error description.

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 return data 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-02-03&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-02-03",
        "next_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/test/examples?cursor=eyJtb2RpZmllZCI6eyJ2YWx1ZSI6IjIwMTctMDMtMDNUMjE6MTg6MjMuOTI0WiIsIm9yZGVyIjoiZGVzYyJ9LCJ0ZXh0Ijp7InZhbHVlIjoibmluZXRlZW4iLCJvcmRlciI6ImFzYyIsInRpZV9icmVha2VyIjp0cnVlfX0=&page_limit=10&sort=-modified&version=2017-02-03"
    }
}
        

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, Bluemix collects data from all requests and uses the data to improve the services. If you do not want to share your data, set a header parameter X-Watson-Learning-Opt-Out with the value true for all requests. If you do not specify this header in all payload data, data is collected and used to improve the service. For more information, see Controlling request logging for Watson services.