IBM Cloud API Docs

Introduction

Last updated: 2023-12-08

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

The Assistant v1 API provides authoring methods your application can use to create or update a workspace.

This documentation describes Java SDK major version 9. For more information about how to update your code from the previous version, see the migration guide.

This documentation describes Node SDK major version 6. For more information about how to update your code from the previous version, see the migration guide.

This documentation describes Python SDK major version 5. For more information about how to update your code from the previous version, see the migration guide.

This documentation describes Ruby SDK major version 2. For more information about how to update your code from the previous version, see the migration guide.

This documentation describes .NET Standard SDK major version 5. For more information about how to update your code from the previous version, see the migration guide.

This documentation describes Go SDK major version 2. For more information about how to update your code from the previous version, see the migration guide.

This documentation describes Swift SDK major version 4. For more information about how to update your code from the previous version, see the migration guide.

This documentation describes Unity SDK major version 5. For more information about how to update your code from the previous version, see the migration guide.

For runtime methods that are used by a client application to send user input to an assistant, use the v2 API.

For runtime methods that are used by a client application to send user input to an assistant, use the v2 API.

For runtime methods that are used by a client application to send user input to an assistant, use the v2 API.

For runtime methods that are used by a client application to send user input to an assistant, use the v2 API reference.

For runtime methods that are used by a client application to send user input to an assistant, use the v2 API.

For runtime methods that are used by a client application to send user input to an assistant, use the v2 API.

For runtime methods that are used by a client application to send user input to an assistant, use the v2 API.

For runtime methods that are used by a client application to send user input to an assistant, use the v2 API.

For runtime methods that are used by a client application to send user input to an assistant, use the v2 API.

The IBM Watson Unity SDK has the following requirements.

  • The SDK requires Unity version 2018.2 or later to support Transport Layer Security (TLS) 1.2.
    • Set the project settings for both the Scripting Runtime Version and the Api Compatibility Level to .NET 4.x Equivalent.
    • For more information, see TLS 1.0 support.
  • The SDK doesn't support the WebGL projects. Change your build settings to any platform except WebGL.

For more information about how to install and configure the SDK and SDK Core, see https://github.com/watson-developer-cloud/unity-sdk.

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

Maven

<dependency>
  <groupId>com.ibm.watson</groupId>
  <artifactId>ibm-watson</artifactId>
  <version>11.0.1</version>
</dependency>

Gradle

compile 'com.ibm.watson:ibm-watson:11.0.1'

GitHub

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

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

Installation

npm install ibm-watson@^8.0.0

GitHub

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

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

Installation

pip install --upgrade "ibm-watson>=7.0.1"

GitHub

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

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

Installation

gem install ibm_watson

GitHub

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

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

go get -u github.com/watson-developer-cloud/go-sdk/v2@v3.0.0

GitHub

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

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

Cocoapods

pod 'IBMWatsonAssistantV1', '~> 5.0.0'

Carthage

github "watson-developer-cloud/swift-sdk" ~> 5.0.0

Swift Package Manager

.package(url: "https://github.com/watson-developer-cloud/swift-sdk", from: "5.0.0")

GitHub

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

The code examples on this tab use the client library that is provided for .NET Standard.

Package Manager

Install-Package IBM.Watson.Assistant.v1 -Version 7.0.0

.NET CLI

dotnet add package IBM.Watson.Assistant.v1 --version 7.0.0

PackageReference

<PackageReference Include="IBM.Watson.Assistant.v1" Version="7.0.0" />

GitHub

href="https://github.com/watson-developer-cloud/dotnet-standard-sdk

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

GitHub

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

https://github.com/IBM/unity-sdk-core

Endpoint URLs

Identify the base URL for your service instance.

IBM Cloud URLs

The base URLs come from the service instance. To find the URL, view the service credentials by clicking the name of the service in the Resource list. Use the value of the URL. Add the method to form the complete API endpoint for your request.

The following example URL represents a watsonx Assistant instance that is hosted in Washington, DC:

https://api.us-east.assistant.watson.cloud.ibm.com/instances/6bbda3b3-d572-45e1-8c54-22d6ed9e52c2

The following URLs represent the base URLs for watsonx Assistant. When you call the API, use the URL that corresponds to the location of your service instance.

  • Dallas: https://api.us-south.assistant.watson.cloud.ibm.com
  • Washington, DC: https://api.us-east.assistant.watson.cloud.ibm.com
  • Frankfurt: https://api.eu-de.assistant.watson.cloud.ibm.com
  • Sydney: https://api.au-syd.assistant.watson.cloud.ibm.com
  • Tokyo: https://api.jp-tok.assistant.watson.cloud.ibm.com
  • London: https://api.eu-gb.assistant.watson.cloud.ibm.com
  • Seoul: https://api.kr-seo.assistant.watson.cloud.ibm.com

Set the correct service URL by calling the setServiceUrl() method of the service instance.

Set the correct service URL by specifying the serviceUrl parameter when you create the service instance.

Set the correct service URL by calling the set_service_url() method of the service instance.

Set the correct service URL by specifying the service_url property of the service instance.

Set the correct service URL by calling the SetServiceURL() method of the service instance.

Set the correct service URL by setting the serviceURL property of the service instance.

Set the correct service URL by calling the SetServiceUrl() method of the service instance.

Set the correct service URL by calling the SetServiceUrl() method of the service instance.

Dallas API endpoint example for services managed on IBM Cloud

curl -X {request_method} -u "apikey:{apikey}" "https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}"

Your service instance might not use this URL

Default URL

https://api.us-south.assistant.watson.cloud.ibm.com

Example for the Washington, DC location

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("{version}", authenticator);
assistant.setServiceUrl("https://api.us-east.assistant.watson.cloud.ibm.com");

Default URL

https://api.us-south.assistant.watson.cloud.ibm.com

Example for the Washington, DC location

const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '{version}',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: 'https://api.us-east.assistant.watson.cloud.ibm.com',
});

Default URL

https://api.us-south.assistant.watson.cloud.ibm.com

Example for the Washington, DC location

from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='{version}',
    authenticator=authenticator
)

assistant.set_service_url('https://api.us-east.assistant.watson.cloud.ibm.com')

Default URL

https://api.us-south.assistant.watson.cloud.ibm.com

Example for the Washington, DC location

require "ibm_watson/authenticators"
require "ibm_watson/assistant_v1"
include IBMWatson

authenticator = Authenticators::IamAuthenticator.new(
  apikey: "{apikey}"
)
assistant = AssistantV1.new(
  version: "{version}",
  authenticator: authenticator
)
assistant.service_url = "https://api.us-east.assistant.watson.cloud.ibm.com"

Default URL

https://api.us-south.assistant.watson.cloud.ibm.com

Example for the Washington, DC location

assistant, assistantErr := assistantv1.NewAssistantV1(options)

if assistantErr != nil {
  panic(assistantErr)
}

assistant.SetServiceURL("https://api.us-east.assistant.watson.cloud.ibm.com")

Default URL

https://api.us-south.assistant.watson.cloud.ibm.com

Example for the Washington, DC location

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)
assistant.serviceURL = "https://api.us-east.assistant.watson.cloud.ibm.com"

Default URL

https://api.us-south.assistant.watson.cloud.ibm.com

Example for the Washington, DC location

IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("https://api.us-east.assistant.watson.cloud.ibm.com");

Default URL

https://api.us-south.assistant.watson.cloud.ibm.com

Example for the Washington, DC location

var authenticator = new IamAuthenticator(
    apikey: "{apikey}"
);

while (!authenticator.CanAuthenticate())
    yield return null;

var assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("https://api.us-east.assistant.watson.cloud.ibm.com");

Cloud Pak for Data URLs

For services installed on Cloud Pak for Data, the base URLs come from both the cluster and service instance.

You can find the base URL from the Cloud Pak for Data web client in the details page about the instance. Click the name of the service in your list of instances to see the URL.

Use that URL in your requests to Watson Assistant v1. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Set the URL by calling the setServiceUrl() method of the service instance. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Set the correct service URL by specifying the serviceUrl parameter when you create the service instance. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Set the correct service URL by specifying the url parameter when you create the service instance or by calling the set_url() method of the service instance. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Set the correct service URL by specifying the url parameter when you create the service instance or by calling the url= method of the service instance. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Set the correct service URL by specifying the URL parameter when you create the service instance or by calling the SetURL= method of the service instance. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Set the correct service URL by setting the serviceURL property of the service instance. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Set the correct service URL by calling the SetEndpoint() method of the service instance. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Set the correct service URL by setting the Url property of the service instance. For Cloud Pak for Data System, use a hostname that resolves to an IP address in the cluster.

Endpoint example for Cloud Pak for Data

curl -X {request_method} -H "Authorization: Bearer {token}" "https://{cpd_cluster_host}{:port}/assistant/{deployment_id}/instances/{instance_id}/api"

Endpoint example for Cloud Pak for Data

CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator("https://{cpd_cluster_host}{:port}", "{username}", "{password}");
Assistant assistant = new Assistant("{version}", authenticator);
assistant.setServiceUrl("https://{cpd_cluster_host}{:port}/assistant/{deployment_id}/instances/{instance_id}/api");

Endpoint example for Cloud Pak for Data

const AssistantV1 = require('ibm-watson/assistant/v1');
const { CloudPakForDataAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '{version}',
  authenticator: new CloudPakForDataAuthenticator({
    username: '{username}',
    password: '{password}',
    url: 'https://{cpd_cluster_host}{:port}',
  }),
  serviceUrl: 'https://{cpd_cluster_host}{:port}/assistant/{deployment_id}/instances/{instance_id}/api',
});

Endpoint example for Cloud Pak for Data

from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import CloudPakForDataAuthenticator

authenticator = CloudPakForDataAuthenticator(
    '{username}',
    '{password}',
    'https://{cpd_cluster_host}{:port}'
)

assistant = AssistantV1(
    version='{version}',
    authenticator=authenticator
)

assistant.set_service_url('https://{cpd_cluster_host}{:port}/assistant/{deployment_id}/instances/{instance_id}/api')

Endpoint example for Cloud Pak for Data

require "ibm_watson/authenticators"
require "ibm_watson/assistant_v1"
include IBMWatson

authenticator = Authenticators::CLoudPakForDataAuthenticator.new(
  username: "{username}",
  password: "{password}",
  url: "https://{cpd_cluster_host}{:port}"
)
assistant = AssistantV1.new(
  version: "{version}",
  authenticator: authenticator
)
assistant.service_url = "https://{cpd_cluster_host}{:port}/assistant/{deployment_id}/instances/{instance_id}/api"

Endpoint example for Cloud Pak for Data

assistant, assistantErr := assistantv1.NewAssistantV1(options)

if assistantErr != nil {
  panic(assistantErr)
}

assistant.SetServiceURL("https://{cpd_cluster_host}{:port}/assistant/{deployment_id}/instances/{instance_id}/api")

Endpoint example for Cloud Pak for Data

let authenticator = CloudPakForDataAuthenticator(username: "{username}", password: "{password}", url: "https://{cpd_cluster_host}{:port}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)
assistant.serviceURL = "https://{cpd_cluster_host}{:port}/assistant/{deployment_id}/instances/{instance_id}/api"

Endpoint example for Cloud Pak for Data

CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator(
    url: "https://{cpd_cluster_host}{:port}",
    username: "{username}",
    password: "{password}"
    );

AssistantService assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("https://{cpd_cluster_host}{:port}/assistant/{deployment_id}/instances/{instance_id}/api");

Endpoint example for Cloud Pak for Data

var authenticator = new CloudPakForDataAuthenticator(
    url: "https://{cpd_cluster_host}{:port}",
    username: "{username}",
    password: "{password}"
);

while (!authenticator.CanAuthenticate())
    yield return null;

var assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("https://{cpd_cluster_host}{:port}/assistant/{deployment_id}/instances/{instance_id}/api");

Disabling SSL verification

All Watson services use Secure Sockets Layer (SSL) (or Transport Layer Security (TLS)) for secure connections between the client and server. The connection is verified against the local certificate store to ensure authentication, integrity, and confidentiality.

If you use a self-signed certificate, you need to disable SSL verification to make a successful connection.

Enabling SSL verification is highly recommended. Disabling SSL jeopardizes the security of the connection and data. Disable SSL only if necessary, and take steps to enable SSL as soon as possible.

To disable SSL verification for a curl request, use the --insecure (-k) option with the request.

To disable SSL verification, create an HttpConfigOptions object and set the disableSslVerification property to true. Then, pass the object to the service instance by using the configureClient method.

To disable SSL verification, set the disableSslVerification parameter to true when you create the service instance.

To disable SSL verification, specify True on the set_disable_ssl_verification method for the service instance.

To disable SSL verification, set the disable_ssl_verification parameter to true in the configure_http_client() method for the service instance.

To disable SSL verification, call the DisableSSLVerification method on the service instance.

To disable SSL verification, call the disableSSLVerification() method on the service instance. You cannot disable SSL verification on Linux.

To disable SSL verification, set the DisableSslVerification method to true on the service instance.

To disable SSL verification, set the DisableSslVerification method to true on the service instance.

Example to disable SSL verification with a service managed on IBM Cloud. Replace {apikey} and {url} with your service credentials.

curl -k -X {request_method} -u "apikey:{apikey}" "{url}/{method}"

Example to disable SSL verification with a service managed on IBM Cloud

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("{version}", authenticator);
assistant.setServiceUrl("{url}");

HttpConfigOptions configOptions = new HttpConfigOptions.Builder()
  .disableSslVerification(true)
  .build();
assistant.configureClient(configOptions);

Example to disable SSL verification with a service managed on IBM Cloud

const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '{version}',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
  disableSslVerification: true,
});

Example to disable SSL verification with a service managed on IBM Cloud

from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='{version}',
    authenticator=authenticator
)

assistant.set_service_url('{url}')

assistant.set_disable_ssl_verification(True)

Example to disable SSL verification with a service managed on IBM Cloud

require "ibm_watson/authenticators"
require "ibm_watson/assistant_v1"
include IBMWatson

authenticator = Authenticators::IamAuthenticator.new(
  apikey: "{apikey}"
)
assistant = AssistantV1.new(
  version: "{version}",
  authenticator: authenticator
)
assistant.service_url = "{url}"

assistant.configure_http_client(disable_ssl_verification: true)

Example to disable SSL verification with a service managed on IBM Cloud

assistant, assistantErr := assistantv1.NewAssistantV1(options)

if assistantErr != nil {
  panic(assistantErr)
}

assistant.SetServiceURL("{url}")

assistant.DisableSSLVerification()

Example to disable SSL verification with a service managed on IBM Cloud

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)
assistant.serviceURL = "{url}"

assistant.disableSSLVerification()

Example to disable SSL verification with a service managed on IBM Cloud

IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

assistant.DisableSslVerification(true);

Example to disable SSL verification with a service managed on IBM Cloud

var authenticator = new IamAuthenticator(
    apikey: "{apikey}"
);

while (!authenticator.CanAuthenticate())
    yield return null;

var assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

assistant.DisableSslVerification = true;

Example to disable SSL verification with an installed service

curl -k -X {request_method} -H "Authorization: Bearer {token}" "{url}/v1/{method}"

Example to disable SSL verification with an installed service

CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator("https://{cpd_cluster_host}{:port}", "{username}", "{password}");
Assistant assistant = new Assistant("{version}", authenticator);
assistant.setServiceUrl("{url}";

HttpConfigOptions configOptions = new HttpConfigOptions.Builder()
  .disableSslVerification(true)
  .build();
assistant.configureClient(configOptions);

Example to disable SSL verification with an installed service

const AssistantV1 = require('ibm-watson/assistant/v1');
const { CloudPakForDataAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '{version}',
  authenticator: new CloudPakForDataAuthenticator({
    username: '{username}',
    password: '{password}',
    url: 'https://{cpd_cluster_host}{:port}',
  }),
  serviceUrl: '{url}',
  disableSslVerification: true,
});

Example to disable SSL verification with an installed service

from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import CloudPakForDataAuthenticator

authenticator = CloudPakForDataAuthenticator(
    '{username}',
    '{password}'
)

assistant = AssistantV1(
    version='{version}',
    authenticator=authenticator
)

assistant.set_service_url('{url}')

assistant.set_disable_ssl_verification(True)

Example to disable SSL verification with an installed service

require "ibm_watson/authenticators"
require "ibm_watson/assistant_v1"
include IBMWatson

authenticator = Authenticators::CLoudPakForDataAuthenticator.new(
  username: "{username}",
  password: "{password}",
  url: "https://{cpd_cluster_host}{:port}"
)
assistant = AssistantV1.new(
  version: "{version}",
  authenticator: authenticator
)
assistant.service_url = "{url}"

assistant.configure_http_client(disable_ssl_verification: true)

Example to disable SSL verification with an installed service

assistant, assistantErr := assistantv1.NewAssistantV1(options)

if assistantErr != nil {
  panic(assistantErr)
}

assistant.SetServiceURL("{url}")

assistant.DisableSSLVerification()

Example to disable SSL verification with an installed service

let authenticator = WatsonCloudPakForDataAuthenticator(username: "{username}", password: "{password}", url: "https://{cpd_cluster_host}{:port}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)
assistant.serviceURL = "{url}"

assistant.disableSSLVerification()

Example to disable SSL verification with an installed service

CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator(
    url: "https://{cpd_cluster_host}{:port}",
    username: "{username}",
    password: "{password}"
    );

AssistantService assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

assistant.DisableSslVerification(true);

Example to disable SSL verification with an installed service

var authenticator = new CloudPakForDataAuthenticator(
    url: "https://{cpd_cluster_host}{:port}",
    username: "{username}",
    password: "{password}"
);

while (!authenticator.CanAuthenticate())
    yield return null;

var assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

assistant.DisableSslVerification = true;

Authentication

IBM Cloud services use IBM Cloud Identity and Access Management (IAM) to authenticate. With IBM Cloud Pak for Data, you pass a bearer token.

IBM Cloud

For IBM Cloud instances, you authenticate to the API by using IBM Cloud Identity and Access Management (IAM).

You can pass either a bearer token in an authorization header or an API key. Tokens support authenticated requests without embedding service credentials in every call. API keys use basic authentication. For more information, see Authenticating to Watson services.

  • For testing and development, you can pass an API key directly.
  • For production use, unless you use the Watson SDKs, use an IAM token.

If you pass in an API key, use apikey for the username and the value of the API key as the password. For example, if the API key is f5sAznhrKQyvBFFaZbtF60m5tzLbqWhyALQawBg5TjRI in the service credentials, include the credentials in your call like this:

curl -u "apikey:f5sAznhrKQyvBFFaZbtF60m5tzLbqWhyALQawBg5TjRI"

For IBM Cloud instances, the SDK provides initialization methods for each form of authentication.

  • Use the API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it if necessary.
  • Use the access token to manage the lifecycle yourself. You must periodically refresh the token.

For more information, see IAM authentication with the SDK.For more information, see IAM authentication with the SDK.For more information, see IAM authentication with the SDK.For more information, see IAM authentication with the SDK.For more information, see IAM authentication with the SDK.For more information, see IAM authentication with the SDK.For more information, see IAM authentication with the SDK.For more information, see IAM authentication with the SDK.

The service access role that is associated with the API key determines which endpoints and methods you can access. For more information, see Resource-level role impact on available actions.

IBM Cloud. Replace {apikey} and {url} with your service credentials.

curl -X {request_method} -u "apikey:{apikey}" "{url}/v1/{method}"

IBM Cloud. SDK managing the IAM token. Replace {apikey}, {version}, and {url}.

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("{version}", authenticator);
assistant.setServiceUrl("{url}");

IBM Cloud. SDK managing the IAM token. Replace {apikey}, {version}, and {url}.

const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '{version}',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

IBM Cloud. SDK managing the IAM token. Replace {apikey}, {version}, and {url}.

from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='{version}',
    authenticator=authenticator
)

assistant.set_service_url('{url}')

IBM Cloud. SDK managing the IAM token. Replace {apikey}, {version}, and {url}.

require "ibm_watson/authenticators"
require "ibm_watson/assistant_v1"
include IBMWatson

authenticator = Authenticators::IamAuthenticator.new(
  apikey: "{apikey}"
)
assistant = AssistantV1.new(
  version: "{version}",
  authenticator: authenticator
)
assistant.service_url = "{url}"

IBM Cloud. SDK managing the IAM token. Replace {apikey}, {version}, and {url}.

import (
  "github.com/IBM/go-sdk-core/core"
  "github.com/watson-developer-cloud/go-sdk/assistantv1"
)

func main() {
  authenticator := &core.IamAuthenticator{
    ApiKey: "{apikey}",
  }

  options := &assistantv1.AssistantV1Options{
    Version: "{version}",
    Authenticator: authenticator,
  }

  assistant, assistantErr := assistantv1.NewAssistantV1(options)

  if assistantErr != nil {
    panic(assistantErr)
  }

  assistant.SetServiceURL("{url}")
}

IBM Cloud. SDK managing the IAM token. Replace {apikey}, {version}, and {url}.

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)
assistant.serviceURL = "{url}"

IBM Cloud. SDK managing the IAM token. Replace {apikey}, {version}, and {url}.

IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

IBM Cloud. SDK managing the IAM token. Replace {apikey}, {version}, and {url}.

var authenticator = new IamAuthenticator(
    apikey: "{apikey}"
);

while (!authenticator.CanAuthenticate())
    yield return null;

var assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

Cloud Pak for Data

For Cloud Pak for Data, you pass a bearer token in an Authorization header to authenticate to the API. The token is associated with a username.

  • For testing and development, you can use the bearer token that's displayed in the Cloud Pak for Data web client. To find this token, view the details for the service instance by clicking the name of the service in your list of instances. The details also include the service endpoint URL. Don't use this token in production because it does not expire.
  • For production use, create a user in the Cloud Pak for Data web client to use for authentication. Generate a token from that user's credentials with the POST /v1/authorize method.

For more information, see the Get authorization token method of the Cloud Pak for Data API reference.

For Cloud Pak for Data instances, pass either username and password credentials or a bearer token that you generate to authenticate to the API. Username and password credentials use basic authentication. However, the SDK manages the lifecycle of the token. Tokens are temporary security credentials. If you pass a token, you maintain the token lifecycle.

For production use, create a user in the Cloud Pak for Data web client to use for authentication, and decide which authentication mechanism to use.

  • To have the SDK manage the lifecycle of the token, use the username and password for that new user in your calls.
  • To manage the lifecycle of the token yourself, generate a token from that user's credentials. Call the POST /v1/authorize method to generate the token, and then pass the token in an Authorization header in your calls. You can see an example of the method on the Curl tab.

For more information, see the Get authorization token method of the Cloud Pak for Data API reference.

Don't use the bearer token that's displayed in the web client for the instance except during testing and development because that token does not expire.

To find your value for {url}, view the details for the service instance by clicking the name of the service in your list of instances in the Cloud Pak for Data web client.

Cloud Pak for Data. Generating a bearer token.

Replace {cpd_cluster_host} and {port} with the details for the service instance. Replace {username} and {password} with your Cloud Pak for Data credentials.

curl -k -X POST -H "cache-control: no-cache" -H "Content-Type: application/json" -d "{\"username\":\"{username}\",\"password\":\"{password}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize"

The response includes a token property.

Authenticating to the API. Replace {token} with your details.

curl -H "Authorization: Bearer {token}" "{url}/v1/{method}"

Cloud Pak for Data. SDK managing the token.

Replace {username} and {password} with your Cloud Pak for Data credentials. Replace {version} with the service version date. For {url}, see Endpoint URLs.

CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator("https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize", "{username}", "{password}");
Assistant assistant = new Assistant("{version}", authenticator);
assistant.setServiceUrl("{url}");

Cloud Pak for Data. SDK managing the token.

Replace {username} and {password} with your Cloud Pak for Data credentials. Replace {version} with the service version date. For {url}, see Endpoint URLs.

const AssistantV1 = require('ibm-watson/assistant/v1');
const { CloudPakForDataAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '{version}',
  authenticator: new CloudPakForDataAuthenticator({
    username: '{username}',
    password: '{password}',
    url: 'https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize',
  }),
  serviceUrl: '{url}',
});

Cloud Pak for Data. SDK managing the token.

Replace {username} and {password} with your Cloud Pak for Data credentials. Replace {version} with the service version date. For {url}, see Endpoint URLs.

from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import CloudPakForDataAuthenticator

authenticator = CloudPakForDataAuthenticator(
    '{username}',
    '{password}',
    'https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize'
)

assistant = AssistantV1(
    version='{version}',
    authenticator=authenticator
)

assistant.set_service_url('{url}')

Cloud Pak for Data. SDK managing the token.

Replace {username} and {password} with your Cloud Pak for Data credentials. Replace {version} with the service version date. For {url}, see Endpoint URLs.

require "ibm_watson/authenticators"
require "ibm_watson/assistant_v1"
include IBMWatson

authenticator = Authenticators::CloudPakForDataAuthenticator.new(
  username: "{username}",
  password: "{password}",
  url: "https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize"
)
assistant = AssistantV1.new(
  version: "{version}",
  authenticator: authenticator
)
assistant.service_url = "{url}"

Cloud Pak for Data. SDK managing the token.

Replace {username} and {password} with your Cloud Pak for Data credentials. Replace {version} with the service version date. For {url}, see Endpoint URLs.

import (
  "github.com/IBM/go-sdk-core/core"
  "github.com/watson-developer-cloud/go-sdk/assistantv1"
)

func main() {
  authenticator := &core.CloudPakForDataAuthenticator{
    URL: "https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize",
    Username: "{username}",
    Password: "{password}",
  }

  options := &assistantv1.AssistantV1Options{
    Version: "{version}",
    Authenticator: authenticator,
  }

  assistant, assistantErr := assistantv1.NewAssistantV1(options)

  if assistantErr != nil {
    panic(assistantErr)
  }

  assistant.SetServiceURL("{url}")
}

Cloud Pak for Data. SDK managing the token.

Replace {username} and {password} with your Cloud Pak for Data credentials. Replace {version} with the service version date. For {url}, see Endpoint URLs.

let authenticator = WatsonCloudPakForDataAuthenticator(username: "{username}", password: "{password}", url: "https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize")
let assistant = Assistant(version: "{version}", authenticator: authenticator)
assistant.serviceURL = "{url}"

Cloud Pak for Data. SDK managing the token.

Replace {username} and {password} with your Cloud Pak for Data credentials. Replace {version} with the service version date. For {cpd_cluster_host}, {port}, {release}, and {instance_id}, see Endpoint URLs.

CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator(
    url: "https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize",
    username: "{username}",
    password: "{password}"
    );

AssistantService assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

Cloud Pak for Data. SDK managing the token.

Replace {username} and {password} with your Cloud Pak for Data credentials. Replace {version} with the service version date. For {cpd_cluster_host}, {port}, {release}, and {instance_id}, see Endpoint URLs.

var authenticator = new CloudPakForDataAuthenticator(
    url: "https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize",
    username: "{username}",
    password: "{password}"
);

while (!authenticator.CanAuthenticate())
    yield return null;

var assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

Access between services

Your application might use more than one Watson service. You can grant access between services and you can grant access to more than one service for your applications.

For IBM Cloud services, the method to grant access between Watson services varies depending on the type of API key. For more information, see IAM access.

  • To grant access between IBM Cloud services, create an authorization between the services. For more information, see Granting access between services.
  • To grant access to your services by applications without using user credentials, create a service ID, add an API key, and assign access policies. For more information, see Creating and working with service IDs.

When you give a user ID access to multiple services, use an endpoint URL that includes the service instance ID (for example, https://api.us-south.assistant.watson.cloud.ibm.com/instances/6bbda3b3-d572-45e1-8c54-22d6ed9e52c2). You can find the instance ID in two places:

  • By clicking the service instance row in the Resource list. The instance ID is the GUID in the details pane.

  • By clicking the name of the service instance in the list and looking at the credentials URL.

    If you don't see the instance ID in the URL, the credentials predate service IDs. Add new credentials from the Service credentials page and use those credentials.

Because the Cloud Pak for Data bearer token is associated with a username, you can use the token for all CPD Watson services that are associated with the username.

Versioning

API requests require a version parameter that takes a date in the format version=YYYY-MM-DD. When the API is updated with any breaking changes, the service introduces a new version date for 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.

Specify the version to use on API requests with the version parameter when you create the service instance. 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.

This documentation describes the current version of watsonx Assistant, 2021-11-27. In some cases, differences in earlier versions are noted in the descriptions of parameters and response models.

Error handling

watsonx Assistant uses standard HTTP response codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error that cannot be resolved by the user. Response codes are listed with the method.

ErrorResponse

Name Description
code
integer		 The HTTP response code.
error
string		 General description of an error.
errors
ErrorDetail[]		 Collection of specific constraint violations associated with the error.

ErrorDetail

Name Description
message
string		 Description of a specific constraint violation.
path
string		 The location of the constraint violation.

The Java SDK generates an exception for any unsuccessful method invocation. All methods that accept an argument can also throw an IllegalArgumentException.

Exception Description
IllegalArgumentException An invalid argument was passed to the method.

When the Java SDK receives an error response from the watsonx Assistant service, it generates an exception from the com.ibm.watson.developer_cloud.service.exception package. All service exceptions contain the following fields.

Field Description
statusCode The HTTP response code that is returned.
message A message that describes the error.

When the Node SDK receives an error response from the watsonx Assistant service, it creates an Error object with information that describes the error that occurred. This error object is passed as the first parameter to the callback function for the method. The contents of the error object are as shown in the following table.

Error

Field Description
code The HTTP response code that is returned.
message A message that describes the error.

The Python SDK generates an exception for any unsuccessful method invocation. When the Python SDK receives an error response from the watsonx Assistant service, it generates an ApiException with the following fields.

Field Description
code The HTTP response code that is returned.
message A message that describes the error.
info A dictionary of additional information about the error.

When the Ruby SDK receives an error response from the watsonx Assistant service, it generates an ApiException with the following fields.

Field Description
code The HTTP response code that is returned.
message A message that describes the error.
info A dictionary of additional information about the error.

The Go SDK generates an error for any unsuccessful service instantiation and method invocation. You can check for the error immediately. The contents of the error object are as shown in the following table.

Error

Field Description
code The HTTP response code that is returned.
message A message that describes the error.

The Swift SDK returns a WatsonError in the completionHandler any unsuccessful method invocation. This error type is an enum that conforms to LocalizedError and contains an errorDescription property that returns an error message. Some of the WatsonError cases contain associated values that reveal more information about the error.

Field Description
errorDescription A message that describes the error.

When the .NET Standard SDK receives an error response from the watsonx Assistant service, it generates a ServiceResponseException with the following fields.

Field Description
Message A message that describes the error.
CodeDescription The HTTP response code that is returned.

When the Unity SDK receives an error response from the watsonx Assistant service, it generates an IBMError with the following fields.

Field Description
Url The URL that generated the error.
StatusCode The HTTP response code returned.
ErrorMessage A message that describes the error.
Response The contents of the response from the server.
ResponseHeaders A dictionary of headers returned by the request.

Example error handling

try {
  // Invoke a method
} catch (NotFoundException e) {
  // Handle Not Found (404) exception
} catch (RequestTooLargeException e) {
  // Handle Request Too Large (413) exception
} catch (ServiceResponseException e) {
  // Base class for all exceptions caused by error responses from the service
  System.out.println("Service returned status code "
    + e.getStatusCode() + ": " + e.getMessage());
}

Example error handling

assistant.method(params)
  .catch(err => {
    console.log('error:', err);
  });

Example error handling

from ibm_watson import ApiException
try:
    # Invoke a method
except ApiException as ex:
    print "Method failed with status code " + str(ex.code) + ": " + ex.message

Example error handling

require "ibm_watson"
begin
  # Invoke a method
rescue IBMWatson::ApiException => ex
  print "Method failed with status code #{ex.code}: #{ex.error}"
end

Example error handling

import "github.com/watson-developer-cloud/go-sdk/assistantv1"

// Instantiate a service
assistant, assistantErr := assistantv1.NewAssistantV1(options)

// Check for errors
if assistantErr != nil {
  panic(assistantErr)
}

// Call a method
result, _, responseErr := assistant.MethodName(&methodOptions)

// Check for errors
if responseErr != nil {
  panic(responseErr)
}

Example error handling

assistant.method() {
  response, error in

  if let error = error {
    switch error {
    case let .http(statusCode, message, metadata):
      switch statusCode {
      case .some(404):
        // Handle Not Found (404) exception
        print("Not found")
      case .some(413):
        // Handle Request Too Large (413) exception
        print("Payload too large")
      default:
        if let statusCode = statusCode {
          print("Error - code: \(statusCode), \(message ?? "")")
        }
      }
    default:
      print(error.localizedDescription)
    }
    return
  }

  guard let result = response?.result else {
    print(error?.localizedDescription ?? "unknown error")
    return
  }

  print(result)
}

Example error handling

try
{
    // Invoke a method
}
catch(ServiceResponseException e)
{
    Console.WriteLine("Error: " + e.Message);
}
catch (Exception e)
{
    Console.WriteLine("Error: " + e.Message);
}

Example error handling

// Invoke a method
assistant.MethodName(Callback, Parameters);

// Check for errors
private void Callback(DetailedResponse<ExampleResponse> response, IBMError error)
{
    if (error == null)
    {
        Log.Debug("ExampleCallback", "Response received: {0}", response.Response);
    }
    else
    {
        Log.Debug("ExampleCallback", "Error received: {0}, {1}, {3}", error.StatusCode, error.ErrorMessage, error.Response);
    }
}

Data handling

Additional headers

Some Watson services accept special parameters in headers that are passed with the request.

You can pass request header parameters in all requests or in a single request to the service.

To pass a request header, use the --header (-H) option with a curl request.

To pass header parameters with every request, use the setDefaultHeaders method of the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, use the addHeader method as a modifier on the request before you execute it.

To pass header parameters with every request, specify the headers parameter when you create the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, use the headers method as a modifier on the request before you execute it.

To pass header parameters with every request, specify the set_default_headers method of the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, include headers as a dict in the request.

To pass header parameters with every request, specify the add_default_headers method of the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, specify the headers method as a chainable method in the request.

To pass header parameters with every request, specify the SetDefaultHeaders method of the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, specify the Headers as a map in the request.

To pass header parameters with every request, add them to the defaultHeaders property of the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, pass the headers parameter to the request method.

To pass header parameters in a single request, use the WithHeader() method as a modifier on the request before you execute it. See Data collection for an example use of this method.

To pass header parameters in a single request, use the WithHeader() method as a modifier on the request before you execute it.

Example header parameter in a request

curl -X {request_method} -H "Request-Header: {header_value}" "{url}/v1/{method}"

Example header parameter in a request

ReturnType returnValue = assistant.methodName(parameters)
  .addHeader("Custom-Header", "{header_value}")
  .execute();

Example header parameter in a request

const parameters = {
  {parameters}
};

assistant.methodName(
  parameters,
  headers: {
    'Custom-Header': '{header_value}'
  })
   .then(result => {
    console.log(response);
  })
  .catch(err => {
    console.log('error:', err);
  });

Example header parameter in a request

response = assistant.methodName(
    parameters,
    headers = {
        'Custom-Header': '{header_value}'
    })

Example header parameter in a request

response = assistant.headers(
  "Custom-Header" => "{header_value}"
).methodName(parameters)

Example header parameter in a request

result, _, responseErr := assistant.MethodName(
  &methodOptions{
    Headers: map[string]string{
      "Accept": "application/json",
    },
  },
)

Example header parameter in a request

let customHeader: [String: String] = ["Custom-Header": "{header_value}"]
assistant.methodName(parameters, headers: customHeader) {
  response, error in
}

Example header parameter in a request for a service managed on IBM Cloud

IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

assistant.WithHeader("Custom-Header", "header_value");

Example header parameter in a request for an installed service

CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator(
    url: "https://{cpd_cluster_host}{:port}",
    username: "{username}",
    password: "{password}"
    );

AssistantService assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("https://{cpd_cluster_host}{:port}/assistant/{release}/instances/{instance_id}/api");

assistant.WithHeader("Custom-Header", "header_value");

Example header parameter in a request for a service managed on IBM Cloud

var authenticator = new IamAuthenticator(
    apikey: "{apikey}"
);

while (!authenticator.CanAuthenticate())
    yield return null;

var assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

assistant.WithHeader("Custom-Header", "header_value");

Example header parameter in a request for an installed service

var authenticator = new CloudPakForDataAuthenticator(
    url: "https://{cpd_cluster_host}{:port}",
    username: "{username}",
    password: "{password}"
);

while (!authenticator.CanAuthenticate())
    yield return null;

var assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("https://{cpd_cluster_host}{:port}/assistant/{release}/instances/{instance_id}/api");

assistant.WithHeader("Custom-Header", "header_value");

Response details

The watsonx Assistant service might return information to the application in response headers.

To access all response headers that the service returns, include the --include (-i) option with a curl request. To see detailed response data for the request, including request headers, response headers, and extra debugging information, include the --verbose (-v) option with the request.

Example request to access response headers

curl -X {request_method} {authentication_method} --include "{url}/v1/{method}"

To access information in the response headers, use one of the request methods that returns details with the response: executeWithDetails(), enqueueWithDetails(), or rxWithDetails(). These methods return a Response<T> object, where T is the expected response model. Use the getResult() method to access the response object for the method, and use the getHeaders() method to access information in response headers.

Example request to access response headers

Response<ReturnType> response = assistant.methodName(parameters)
  .executeWithDetails();
// Access response from methodName
ReturnType returnValue = response.getResult();
// Access information in response headers
Headers responseHeaders = response.getHeaders();

All response data is available in the Response<T> object that is returned by each method. To access information in the response object, use the following properties.

Property Description
result Returns the response for the service-specific method.
headers Returns the response header information.
status Returns the HTTP status code.

Example request to access response headers

assistant.methodName(parameters)
  .then(response => {
    console.log(response.headers);
  })
  .catch(err => {
    console.log('error:', err);
  });

The return value from all service methods is a DetailedResponse object. To access information in the result object or response headers, use the following methods.

DetailedResponse

Method Description
get_result() Returns the response for the service-specific method.
get_headers() Returns the response header information.
get_status_code() Returns the HTTP status code.

Example request to access response headers

assistant.set_detailed_response(True)
response = assistant.methodName(parameters)
# Access response from methodName
print(json.dumps(response.get_result(), indent=2))
# Access information in response headers
print(response.get_headers())
# Access HTTP response status
print(response.get_status_code())

The return value from all service methods is a DetailedResponse object. To access information in the response object, use the following properties.

DetailedResponse

Property Description
result Returns the response for the service-specific method.
headers Returns the response header information.
status Returns the HTTP status code.

Example request to access response headers

response = assistant.methodName(parameters)
# Access response from methodName
print response.result
# Access information in response headers
print response.headers
# Access HTTP response status
print response.status

The return value from all service methods is a DetailedResponse object. To access information in the response object or response headers, use the following methods.

DetailedResponse

Method Description
GetResult() Returns the response for the service-specific method.
GetHeaders() Returns the response header information.
GetStatusCode() Returns the HTTP status code.

Example request to access response headers

import (
  "github.com/IBM/go-sdk-core/core"
  "github.com/watson-developer-cloud/go-sdk/assistantv1"
)
result, response, responseErr := assistant.MethodName(
  &methodOptions{})
// Access result
core.PrettyPrint(response.GetResult(), "Result ")

// Access response headers
core.PrettyPrint(response.GetHeaders(), "Headers ")

// Access status code
core.PrettyPrint(response.GetStatusCode(), "Status Code ")

All response data is available in the WatsonResponse<T> object that is returned in each method's completionHandler.

Example request to access response headers

assistant.methodName(parameters) {
  response, error in

  guard let result = response?.result else {
    print(error?.localizedDescription ?? "unknown error")
    return
  }
  print(result) // The data returned by the service
  print(response?.statusCode)
  print(response?.headers)
}

The response contains fields for response headers, response JSON, and the status code.

DetailedResponse

Property Description
Result Returns the result for the service-specific method.
Response Returns the raw JSON response for the service-specific method.
Headers Returns the response header information.
StatusCode Returns the HTTP status code.

Example request to access response headers

var results = assistant.MethodName(parameters);

var result = results.Result;            //  The result object
var responseHeaders = results.Headers;  //  The response headers
var responseJson = results.Response;    //  The raw response JSON
var statusCode = results.StatusCode;    //  The response status code

The response contains fields for response headers, response JSON, and the status code.

DetailedResponse

Property Description
Result Returns the result for the service-specific method.
Response Returns the raw JSON response for the service-specific method.
Headers Returns the response header information.
StatusCode Returns the HTTP status code.

Example request to access response headers

private void Example()
{
    assistant.MethodName(Callback, Parameters);
}

private void Callback(DetailedResponse<ResponseType> response, IBMError error)
{
    var result = response.Result;                 //  The result object
    var responseHeaders = response.Headers;       //  The response headers
    var responseJson = reresponsesults.Response;  //  The raw response JSON
    var statusCode = response.StatusCode;         //  The response status code
}

Data labels (IBM Cloud)

You can remove data associated with a specific customer if you label the data with a customer ID when you send a request to the service.

  • Use the X-Watson-Metadata header to associate a customer ID with the data. By adding a customer ID to a request, you indicate that it contains data that belongs to that customer.

    Specify a random or generic string for the customer ID. Do not include personal data, such as an email address. Pass the string customer_id={id} as the argument of the header.

    Labeling data is used only by methods that accept customer data.

  • Use the Delete labeled data method to remove data that is associated with a customer ID.

Use this process of labeling and deleting data only when you want to remove the data that is associated with a single customer, not when you want to remove data for multiple customers. For more information about watsonx Assistant and labeling data, see Information security.

For more information about how to pass headers, see Additional headers.

Data collection (IBM Cloud)

By default, watsonx Assistant service instances managed on IBM Cloud that are not part of Enterprise plans collect data about API requests and their results. This data is collected only to improve the services for future users. The collected data is not shared or made public. Data is not collected for services that are part of Enterprise plans.

To prevent IBM usage of your data for an API request, set one of the following options.

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

Example request with a service managed on IBM Cloud

curl -u "apikey:{apikey}" -H "X-Watson-Learning-Opt-Out: true" "{url}/{method}"

Example request with a service managed on IBM Cloud

Map<String, String> headers = new HashMap<String, String>();
headers.put("X-Watson-Learning-Opt-Out", "true");

assistant.setDefaultHeaders(headers);

Example request with a service managed on IBM Cloud

const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '{version}',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
  headers: {
    'X-Watson-Learning-Opt-Out': 'true'
  }
});

Example request with a service managed on IBM Cloud

assistant.set_default_headers({'x-watson-learning-opt-out': "true"})

Example request with a service managed on IBM Cloud

assistant.add_default_headers(headers: {"x-watson-learning-opt-out" => "true"})

Example request with a service managed on IBM Cloud

import "net/http"

headers := http.Header{}
headers.Add("x-watson-learning-opt-out", "true")
assistant.SetDefaultHeaders(headers)

Example request with a service managed on IBM Cloud

assistant.defaultHeaders["X-Watson-Learning-Opt-Out"] = "true"

Example request with a service managed on IBM Cloud

IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

assistant.WithHeader("X-Watson-Learning-Opt-Out", "true");

Example request with a service managed on IBM Cloud

var authenticator = new IamAuthenticator(
    apikey: "{apikey}"
);

while (!authenticator.CanAuthenticate())
    yield return null;

var assistant = new AssistantService("{version}", authenticator);
assistant.SetServiceUrl("{url}");

assistant.WithHeader("X-Watson-Learning-Opt-Out", "true");

Synchronous and asynchronous requests

The Java SDK supports both synchronous (blocking) and asynchronous (non-blocking) execution of service methods. All service methods implement the ServiceCall interface.

  • To call a method synchronously, use the execute method of the ServiceCall interface. You can call the execute method directly from an instance of the service.
  • To call a method asynchronously, use the enqueue method of the ServiceCall interface to receive a callback when the response arrives. The ServiceCallback interface of the method's argument provides onResponse and onFailure methods that you override to handle the callback.

The Ruby SDK supports both synchronous (blocking) and asynchronous (non-blocking) execution of service methods. All service methods implement the Concurrent::Async module. When you use the synchronous or asynchronous methods, an IVar object is returned. You access the DetailedResponse object by calling ivar_object.value.

For more information about the Ivar object, see the IVar class docs.

  • To call a method synchronously, either call the method directly or use the .await chainable method of the Concurrent::Async module.

    Calling a method directly (without .await) returns a DetailedResponse object.

  • To call a method asynchronously, use the .async chainable method of the Concurrent::Async module.

You can call the .await and .async methods directly from an instance of the service.

Example synchronous request

ReturnType returnValue = assistant.method(parameters).execute();

Example asynchronous request

assistant.method(parameters).enqueue(new ServiceCallback<ReturnType>() {
  @Override public void onResponse(ReturnType response) {
    . . .
  }
  @Override public void onFailure(Exception e) {
    . . .
  }
});

Example synchronous request

response = assistant.method_name(parameters)

or

response = assistant.await.method_name(parameters)

Example asynchronous request

response = assistant.async.method_name(parameters)

Pagination

Some API requests might return many results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. The starting point for each page of results is identified by a token called a cursor.

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

To change the attribute by which results are sorted, use the sort query parametersort parameterSort parameter. If you include multiple sortSort parameters on the same request, 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 method.

For any request that uses pagination, the response includes a pagination object that specifies pagination information. This object includes two URLs that 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 no more results exist.

Each URL specifies the appropriate cursor parameter and retains the same page_limit and sort parameters that were used for the initial request.

For any request that uses pagination, the response includes a paginationPagination object that specifies pagination information. This object includes two cursor tokens, refreshCursorrefresh_cursorRefreshCursor and nextCursornext_cursorNextCursor, that you can specify on subsequent requests.

To request a specific page of results, specify the appropriate value by using the cursorCursor parameter. When you request subsequent pages, do not change the values of the sort and pageLimitsort and page_limitSort and PageLimit parameters (if any).

Pagination

Name Description
refreshCursorrefresh_cursorRefreshCursor
string		 The cursor value for the current page of results.
nextCursornext_cursorNextCursor
string		 The cursor value for the next page of results, if any.
refreshUrlrefreshURLrefresh_urlRefreshUrl
string		 The URL that returns the same page of results.
nextUrlnextURLnext_urlNextUrl
string		 The URL that returns the next page of results, if any.
totalTotal
integer		 Reserved for future use.
matchedMatched
integer		 Reserved for future use.

Using cursor parameter to request a specific page of results:

curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/intents/hello/examples?cursor=eyJ0ZXh0Ijp7Im9yZGVyIjoiYXNjIiwiaW5kZXgiOjAsInZhbHVlIjoiSGV5In0sInBfcyI6NH0=&version=2019-02-28"

Example that retrieves and displays results one page at a time:

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2019-02-28", authenticator);
assistant.setServiceUrl("{url}");
String workspaceId = "{workspace_id}";
String intent = "hello";
String cursor = "";

do {
  ListExamplesOptions options = new ListExamplesOptions.Builder(workspaceId, intent)
    .pageLimit(3)
    .cursor(cursor)
    .build();
  ExampleCollection response = assistant.listExamples(options).execute().getResult();
  List<Example> examples = response.getExamples();
  cursor = response.getPagination().getNextCursor();
  for (Example example : examples) {
    System.out.println(example.text());
  }
}
while(cursor != null);

Example that retrieves and displays results one page at a time:

const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2019-02-28',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});
const cursor = null;

getNextPage(cursor);

function getNextPage(cursor) {
  const params = {
    workspaceId: '{workspace_id}',
    intent: 'hello',
    cursor,
    pageLimit: 3,
  };
  assistant.listExamples(params)
    .then(res => {
      for (const example in res.result.examples) {
        console.log(res.result.examples[example]['text']);
      }
      if(res.result.pagination.next_cursor) {
        getNextPage(res.result.pagination.next_cursor)
      }
    })
    .catch(err => {
      console.log(err)
    });
}

Example that retrieves and displays results one page at a time:

from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2019-02-28',
    authenticator = authenticator
)
assistant.set_service_url('{url}')
cursor = None

while True:
    response=assistant.list_examples(
        workspace_id='{workspace_id}',
        intent='hello',
        cursor=cursor,
        page_limit=3
    ).get_result()

    for example in response.get('examples'):
        print(example.get('text'))

    cursor=response.get('pagination').get('next_cursor')
    if not cursor:
        break

Example that retrieves and displays results one page at a time:

require "ibm_watson/authenticators"
require "ibm_watson/assistant_v1"
include IBMWatson

authenticator = Authenticators::IamAuthenticator.new(
  apikey: "{apikey}"
)
assistant = AssistantV1.new(
  version: "2019-02-28",
  authenticator: authenticator
)
assistant.service_url = "{url}"
cursor = nil

loop do
  response = assistant.list_examples(
    workspace_id: "{workspace_id}",
    intent: "hello",
    page_limit: 3,
    cursor: cursor
  )
  response.result["examples"].each { |example|
    puts example["text"]
  }
  cursor = response.result["pagination"]["next_cursor"]
  if cursor.nil?
    break
  end
end

Example that retrieves and displays results one page at a time:

package main

import (
  "fmt"
  "github.com/IBM/go-sdk-core/core"
  "github.com/watson-developer-cloud/go-sdk/assistantv1"
)

func main() {
  authenticator := &core.IamAuthenticator{
    ApiKey: "{apikey}",
  }
  options := &assistantv1.AssistantV1Options{
    Version: "2019-02-28",
    Authenticator: authenticator,
  }
  assistant, assistantErr := assistantv1.NewAssistantV1(options)
  if assistantErr != nil {
    panic(assistantErr)
  }

  assistant.SetServiceURL("{url}")
  cursor := core.StringPtr("")
  pageLimit := int64(3)

  for {
    result, _, responseErr := assistant.ListExamples(
      &assistantv1.ListExamplesOptions{
        WorkspaceID: core.StringPtr("{workspace_id}"),
        Intent: core.StringPtr("hello"),
        PageLimit: &pageLimit,
        Cursor: cursor,
     },
    )
    if responseErr != nil {
      panic(responseErr)
    }
    for _, example := range result.Examples {
      fmt.Println(*example.Text)
    }
    cursor = result.Pagination.NextCursor
    if cursor == nil {
      break
    }
  }
}

Example that retrieves and displays results one page at a time:

import Foundation
import AssistantV1
let authenticator = WatsonIAMAuthenticator.init(apiKey: "{apikey}")
assistant = Assistant(version: "2019-02-28", authenticator: authenticator)
assistant.serviceURL = "{url}"
func getNextPage(cursor: String?) {
    assistant.listExamples(workspaceID: "{workspace_id}", intent: "hello", pageLimit: 2, cursor: cursor) {
        response, error in
        if let error = error {
            print(error.localizedDescription)
            return
        }
        guard let results = response?.result else {
            print("No results found")
            return
        }
        for example in results.examples {
            print(example)
        }
        if let cursor = examples.pagination.nextCursor {
            getNextPage(cursor?)
        }
    }
}
getNextPage(cursor: nil)

Example that retrieves and displays results one page at a time:

public class ListExamplesWithPagination
{
    public ListExamplesWithPagination()
    {
        IamAuthenticator authenticator = new IamAuthenticator(apikey: "{apikey}");
        AssistantService service = new AssistantService("2019-02-28", authenticator);
        service.SetServiceUrl("{url}");
        string workspaceId = "{workspace_id}";
        string intent = "hello";
        long? pageLimit = 3;
        string cursor = "";
        ListExamples(service, workspaceId, intent, pageLimit, cursor);
    }
    public void ListExamples(AssistantService service, string workspaceId, string intent, long? pageLimit, string cursor)
    {
        var result = service.ListExamples(
            workspaceId: workspaceId,
            intent: intent,
            pageLimit: 3,
            cursor: cursor
        );
        foreach (Example example in result.Result.Examples)
        {
            Console.WriteLine(example.Text);
        }
        var nextCursor = result.Result.Pagination.NextCursor;
        if (!string.IsNullOrEmpty(nextCursor))
        {
            ListExamples(service, workspaceId, intent, pageLimit, nextCursor);
        }
    }
}

Example that retrieves and displays results one page at a time:

public void ListExamples(AssistantService service, string workspaceId, string intent, long? pageLimit, string cursor)
{
    ExampleCollection listExamplesResponse = null;
    service.ListExamples(
        callback: (DetailedResponse<ExampleCollection> response, IBMError error) =>
        {
            Log.Debug("AssistantServiceV1", "ListExamples result: {0}", response.Response);
            listExamplesResponse = response.Result;
            foreach (Example example in listExamplesResponse.Examples)
            {
                Log.Debug("AssistantServiceV1", "Example text: {0}", example.Text);
            }
            var nextCursor = listExamplesResponse.Pagination.NextCursor;
            if (!string.IsNullOrEmpty(nextCursor))
            {
                ListExamples(service, workspaceId, intent, pageLimit, nextCursor);
            }
            else
            {
                paginationDone = true;
            }
        },
        workspaceId: workspaceId,
        intent: intent,
        pageLimit: 3,
        cursor: cursor
    );
}
var authenticator = new IamAuthenticator(
    apikey: "{apikey}"
);
while (!authenticator.CanAuthenticate())
    yield return null;
var assistant = new AssistantService("2019-02-28", authenticator);
assistant.SetServiceUrl("{url}");
bool isPaginationDone = false;
string workspaceId = "{workspace_id}";
string intent = "hello";
long? pageLimit = 3;
string cursor = "";
ListExamples(service, workspaceId, intent, pageLimit, cursor);
while (isPaginationDone == false)
    yield return null;

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 that remain 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.

Related information

Methods

Get response to user input

Send user input to a workspace and receive a response.

Important: This method has been superseded by the new v2 runtime API. The v2 API offers significant advantages, including ease of deployment, automatic state management, versioning, and search capabilities. For more information, see the documentation.

Send user input to a workspace and receive a response.

Important: This method has been superseded by the new v2 runtime API. The v2 API offers significant advantages, including ease of deployment, automatic state management, versioning, and search capabilities. For more information, see the documentation.

Send user input to a workspace and receive a response.

Important: This method has been superseded by the new v2 runtime API. The v2 API offers significant advantages, including ease of deployment, automatic state management, versioning, and search capabilities. For more information, see the documentation.

Send user input to a workspace and receive a response.

Important: This method has been superseded by the new v2 runtime API. The v2 API offers significant advantages, including ease of deployment, automatic state management, versioning, and search capabilities. For more information, see the documentation.

Send user input to a workspace and receive a response.

Important: This method has been superseded by the new v2 runtime API. The v2 API offers significant advantages, including ease of deployment, automatic state management, versioning, and search capabilities. For more information, see the documentation.

POST /v1/workspaces/{workspace_id}/message
ServiceCall<MessageResponse> message(MessageOptions messageOptions)
message(params)
message(
        self,
        workspace_id: str,
        *,
        input: Optional['MessageInput'] = None,
        intents: Optional[List['RuntimeIntent']] = None,
        entities: Optional[List['RuntimeEntity']] = None,
        alternate_intents: Optional[bool] = None,
        context: Optional['Context'] = None,
        output: Optional['OutputData'] = None,
        user_id: Optional[str] = None,
        nodes_visited_details: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Message(string workspaceId, MessageInput input = null, List<RuntimeIntent> intents = null, List<RuntimeEntity> entities = null, bool? alternateIntents = null, Context context = null, OutputData output = null, string userId = null, bool? nodesVisitedDetails = null)

Rate limit

There is no rate limit for this operation.

Request

Use the MessageOptions.Builder to create a MessageOptions object that contains the parameter values for the message method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • nodes_visited_details
    boolean

    Whether to include additional diagnostic information about the dialog nodes that were visited during processing of the message.

    Default: false

Request Body

MessageRequest

The message to be sent. This includes the user's input, along with optional intents, entities, and context from the last response.

MessageOptions

The message options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • input

    An input object that includes the input text.

  • intents

    Intents to use when evaluating the user input. Include intents from the previous response to continue using those intents rather than trying to recognize intents in the new input.

  • entities

    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.

    Examples: 
    {
  "entity": "appliance",
  "location": [
    12,
    18
  ],
  "value": "light",
  "metadata": {}
}
  • alternateIntents
    boolean

    Whether to return more than one intent. A value of true indicates that all matching intents are returned.

    Default: false

  • context

    State information for the conversation. To maintain state, include the context from the previous response.

  • output

    An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log.

  • userId
    string

    A string value that identifies the user who is interacting with the workspace. The client must provide a unique identifier for each individual end user who accesses the application. For user-based plans, this user ID is used to identify unique users for billing purposes. This string cannot contain carriage return, newline, or tab characters. If no value is specified in the input, user_id is automatically set to the value of context.conversation_id.

    Note: This property is the same as the user_id property in the context metadata. If user_id is specified in both locations in a message request, the value specified at the root is used.

    Possible values: 1 ≤ length ≤ 256

  • nodesVisitedDetails
    boolean

    Whether to include additional diagnostic information about the dialog nodes that were visited during processing of the message.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • input

    An input object that includes the input text.

  • intents

    Intents to use when evaluating the user input. Include intents from the previous response to continue using those intents rather than trying to recognize intents in the new input.

  • entities

    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.

    Examples: 
    {
  "entity": "appliance",
  "location": [
    12,
    18
  ],
  "value": "light",
  "metadata": {}
}
  • alternate_intents
    bool

    Whether to return more than one intent. A value of true indicates that all matching intents are returned.

    Default: false

  • context

    State information for the conversation. To maintain state, include the context from the previous response.

  • output

    An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log.

  • user_id
    str

    A string value that identifies the user who is interacting with the workspace. The client must provide a unique identifier for each individual end user who accesses the application. For user-based plans, this user ID is used to identify unique users for billing purposes. This string cannot contain carriage return, newline, or tab characters. If no value is specified in the input, user_id is automatically set to the value of context.conversation_id.

    Note: This property is the same as the user_id property in the context metadata. If user_id is specified in both locations in a message request, the value specified at the root is used.

    Possible values: 1 ≤ length ≤ 256

  • nodes_visited_details
    bool

    Whether to include additional diagnostic information about the dialog nodes that were visited during processing of the message.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • input

    An input object that includes the input text.

  • intents

    Intents to use when evaluating the user input. Include intents from the previous response to continue using those intents rather than trying to recognize intents in the new input.

  • entities

    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.

    Examples: 
    {
  "entity": "appliance",
  "location": [
    12,
    18
  ],
  "value": "light",
  "metadata": {}
}
  • alternateIntents
    bool?

    Whether to return more than one intent. A value of true indicates that all matching intents are returned.

    Default: false

  • context

    State information for the conversation. To maintain state, include the context from the previous response.

  • output

    An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log.

  • userId
    string

    A string value that identifies the user who is interacting with the workspace. The client must provide a unique identifier for each individual end user who accesses the application. For user-based plans, this user ID is used to identify unique users for billing purposes. This string cannot contain carriage return, newline, or tab characters. If no value is specified in the input, user_id is automatically set to the value of context.conversation_id.

    Note: This property is the same as the user_id property in the context metadata. If user_id is specified in both locations in a message request, the value specified at the root is used.

    Possible values: 1 ≤ length ≤ 256

  • nodesVisitedDetails
    bool?

    Whether to include additional diagnostic information about the dialog nodes that were visited during processing of the message.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type:application/json" --data "{\"input\": {\"text\": \"Hello\"}}" "{url}/v1/workspaces/{workspace_id}/message?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.Message(
    workspaceId: "{workspaceId}",
    input: new MessageInput()
    {
        Text = "Hello"
    }
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";

MessageInput input = new MessageInput();
input.setText("Hello");

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

MessageResponse response = assistant.message(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

assistant.message({
  workspaceId: '{workspace_id}',
  input: {'text': 'Hello'}
  })
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response = assistant.message(
    workspace_id='{workspace_id}',
    input={
        'text': 'Hello'
    }
).get_result()

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

Response

Response Body

MessageResponse

The response sent by the workspace, including the output text, detected intents and entities, and context.

MessageResponse

The response sent by the workspace, including the output text, detected intents and entities, and context.

MessageResponse

The response sent by the workspace, including the output text, detected intents and entities, and context.

MessageResponse

The response sent by the workspace, including the output text, detected intents and entities, and context.

MessageResponse

The response sent by the workspace, including the output text, detected intents and entities, and context.

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "intents": [
    {
      "intent": "hello",
      "confidence": 0.9755029201507568
    }
  ],
  "entities": [],
  "input": {
    "text": "Hello"
  },
  "output": {
    "generic": [
      {
        "response_type": "text",
        "text": "Hello! What can I do for you?"
      }
    ],
    "text": [
      "Hello! What can I do for you?"
    ],
    "nodes_visited": [
      "greeting"
    ],
    "log_messages": []
  },
  "context": {
    "conversation_id": "a96ec62f-773c-4e84-8be9-f9dbca9f83d0",
    "system": {
      "dialog_stack": [
        {
          "dialog_node": "root"
        }
      ],
      "dialog_turn_counter": 1,
      "dialog_request_counter": 1,
      "_node_output_map": {
        "greeting": {
          "0": [
            0,
            0
          ]
        }
      },
      "branch_exited": true,
      "branch_exited_reason": "completed"
    },
    "metadata": {
      "user_id": "a96ec62f-773c-4e84-8be9-f9dbca9f83d0"
    }
  },
  "user_id": "a96ec62f-773c-4e84-8be9-f9dbca9f83d0"
}
  • {
  "intents": [
    {
      "intent": "hello",
      "confidence": 0.9755029201507568
    }
  ],
  "entities": [],
  "input": {
    "text": "Hello"
  },
  "output": {
    "generic": [
      {
        "response_type": "text",
        "text": "Hello! What can I do for you?"
      }
    ],
    "text": [
      "Hello! What can I do for you?"
    ],
    "nodes_visited": [
      "greeting"
    ],
    "log_messages": []
  },
  "context": {
    "conversation_id": "a96ec62f-773c-4e84-8be9-f9dbca9f83d0",
    "system": {
      "dialog_stack": [
        {
          "dialog_node": "root"
        }
      ],
      "dialog_turn_counter": 1,
      "dialog_request_counter": 1,
      "_node_output_map": {
        "greeting": {
          "0": [
            0,
            0
          ]
        }
      },
      "branch_exited": true,
      "branch_exited_reason": "completed"
    },
    "metadata": {
      "user_id": "a96ec62f-773c-4e84-8be9-f9dbca9f83d0"
    }
  },
  "user_id": "a96ec62f-773c-4e84-8be9-f9dbca9f83d0"
}

Identify intents and entities in multiple user utterances

Send multiple user inputs to a workspace in a single request and receive information about the intents and entities recognized in each input. This method is useful for testing and comparing the performance of different workspaces.

This method is available only with Enterprise with Data Isolation plans.

Send multiple user inputs to a workspace in a single request and receive information about the intents and entities recognized in each input. This method is useful for testing and comparing the performance of different workspaces.

This method is available only with Enterprise with Data Isolation plans.

Send multiple user inputs to a workspace in a single request and receive information about the intents and entities recognized in each input. This method is useful for testing and comparing the performance of different workspaces.

This method is available only with Enterprise with Data Isolation plans.

Send multiple user inputs to a workspace in a single request and receive information about the intents and entities recognized in each input. This method is useful for testing and comparing the performance of different workspaces.

This method is available only with Enterprise with Data Isolation plans.

Send multiple user inputs to a workspace in a single request and receive information about the intents and entities recognized in each input. This method is useful for testing and comparing the performance of different workspaces.

This method is available only with Enterprise with Data Isolation plans.

POST /v1/workspaces/{workspace_id}/bulk_classify
ServiceCall<BulkClassifyResponse> bulkClassify(BulkClassifyOptions bulkClassifyOptions)
bulkClassify(params)
bulk_classify(
        self,
        workspace_id: str,
        *,
        input: Optional[List['BulkClassifyUtterance']] = None,
        **kwargs,
    ) -> DetailedResponse
BulkClassify(string workspaceId, List<BulkClassifyUtterance> input = null)

Rate limit

This operation is limited to 5 requests per minute.

Request

Use the BulkClassifyOptions.Builder to create a BulkClassifyOptions object that contains the parameter values for the bulkClassify method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

Request Body

BulkClassifyInput

An input object that includes the text to classify.

BulkClassifyOptions

The bulkClassify options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • input

    An array of input utterances to classify.

    Possible values: 1 ≤ number of items ≤ 50

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • input

    An array of input utterances to classify.

    Possible values: 1 ≤ number of items ≤ 50

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • input

    An array of input utterances to classify.

    Possible values: 1 ≤ number of items ≤ 50

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type:application/json" --data "{\"input\": [{\"text\": \"I want to order some coffee\"}]}" "{url}/v1/workspaces/{workspace_id}/bulk_classify?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

List<BulkClassifyUtterance> bulkClassifyUtterances = new List<BulkClassifyUtterance>();
BulkClassifyUtterance bulkClassifyUtterance = new BulkClassifyUtterance();
bulkClassifyUtterance.Text = "I want to order some coffee";
bulkClassifyUtterances.Add(bulkClassifyUtterance);
var result = assistant.BulkClassify(workspaceId:"{workspaceId}", input: bulkClassifyUtterances);

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

BulkClassifyUtterance bulkClassifyUtterance = new BulkClassifyUtterance.Builder()
  .text("I want to order some coffee")
  .build();

BulkClassifyOptions options = new BulkClassifyOptions.Builder()
  .workspaceId("{workspace_id}")
  .addInput(bulkClassifyUtterance)
  .build();

BulkClassifyResponse response = assistant.bulkClassify(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{id}'
  input: [{'text': 'I want to order some coffee'}]
};

assistant.bulkClassify(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.bulk_classify(
    workspace_id='{workspace_id}',
    input=[{'text': 'I want to order some coffee'}]
).get_result()

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

Response

Response Body

BulkClassifyResponse

BulkClassifyResponse

BulkClassifyResponse

BulkClassifyResponse

BulkClassifyResponse

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "output": [
    {
      "input": {
        "text": "I want to order some coffee"
      },
      "entities": [
        {
          "entity": "beverage",
          "value": "coffee",
          "confidence": 1,
          "location": [
            14,
            20
          ],
          "groups": null,
          "role": null
        }
      ],
      "intents": [
        {
          "intent": "order",
          "confidence": 0.1588214785085711
        },
        {
          "intent": "goodbye",
          "confidence": 0.041231044110733354
        }
      ]
    }
  ]
}
  • {
  "output": [
    {
      "input": {
        "text": "I want to order some coffee"
      },
      "entities": [
        {
          "entity": "beverage",
          "value": "coffee",
          "confidence": 1,
          "location": [
            14,
            20
          ],
          "groups": null,
          "role": null
        }
      ],
      "intents": [
        {
          "intent": "order",
          "confidence": 0.1588214785085711
        },
        {
          "intent": "goodbye",
          "confidence": 0.041231044110733354
        }
      ]
    }
  ]
}

List workspaces

List the workspaces associated with a Watson Assistant service instance.

List the workspaces associated with a Watson Assistant service instance.

List the workspaces associated with a Watson Assistant service instance.

List the workspaces associated with a Watson Assistant service instance.

List the workspaces associated with a Watson Assistant service instance.

GET /v1/workspaces
ServiceCall<WorkspaceCollection> listWorkspaces(ListWorkspacesOptions listWorkspacesOptions)
listWorkspaces(params)
list_workspaces(
        self,
        *,
        page_limit: Optional[int] = None,
        include_count: Optional[bool] = None,
        sort: Optional[str] = None,
        cursor: Optional[str] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
ListWorkspaces(long? pageLimit = null, bool? includeCount = null, string sort = null, string cursor = null, bool? includeAudit = null)

Rate limit

This operation is limited to 500 requests per 30 minutes.

Request

Use the ListWorkspacesOptions.Builder to create a ListWorkspacesOptions object that contains the parameter values for the listWorkspaces method.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • page_limit
    integer

    The number of records to return in each page of results.

    Default: 100

  • include_count
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned workspaces will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [name,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

ListWorkspacesOptions

The listWorkspaces options.

parameters

  • pageLimit
    number

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned workspaces will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [name,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • page_limit
    int

    The number of records to return in each page of results.

    Default: 100

  • include_count
    bool

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    str

    The attribute by which returned workspaces will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [name,updated]

  • cursor
    str

    A token identifying the page of results to retrieve.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • pageLimit
    long?

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    bool?

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned workspaces will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [name,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.ListWorkspaces();
Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

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

WorkspaceCollection workspaces = assistant.listWorkspaces(options).execute().getResult();

System.out.println(workspaces);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

assistant.listWorkspaces()
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.list_workspaces().get_result()

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

Response

Response Body

WorkspaceCollection

WorkspaceCollection

WorkspaceCollection

WorkspaceCollection

WorkspaceCollection

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "workspaces": [
    {
      "name": "Car_Dashboard",
      "language": "en",
      "metadata": {
        "runtime_version": "2021-11-27"
      },
      "description": "Cognitive Car workspace which allows multi-turn conversations to perform tasks in the car.",
      "workspace_id": "0a0c06c1-8e31-4655-9067-58fcac5134fc",
      "learning_opt_out": false
    },
    {
      "name": "testing",
      "language": "en",
      "metadata": {
        "runtime_version": "2021-11-27"
      },
      "workspace_id": "e42c8e5c-eb34-4b65-99f0-59f9329b66ec",
      "learning_opt_out": false
    },
    {
      "name": "workspace-example",
      "language": "en",
      "metadata": {
        "runtime_version": "2021-11-27"
      },
      "description": "Example workspace to try out the service",
      "workspace_id": "293b58fc-3c5b-4ac5-a8f4-8d52c393d875",
      "learning_opt_out": false
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces?version=2021-11-27"
  }
}
  • {
  "workspaces": [
    {
      "name": "Car_Dashboard",
      "language": "en",
      "metadata": {
        "runtime_version": "2021-11-27"
      },
      "description": "Cognitive Car workspace which allows multi-turn conversations to perform tasks in the car.",
      "workspace_id": "0a0c06c1-8e31-4655-9067-58fcac5134fc",
      "learning_opt_out": false
    },
    {
      "name": "testing",
      "language": "en",
      "metadata": {
        "runtime_version": "2021-11-27"
      },
      "workspace_id": "e42c8e5c-eb34-4b65-99f0-59f9329b66ec",
      "learning_opt_out": false
    },
    {
      "name": "workspace-example",
      "language": "en",
      "metadata": {
        "runtime_version": "2021-11-27"
      },
      "description": "Example workspace to try out the service",
      "workspace_id": "293b58fc-3c5b-4ac5-a8f4-8d52c393d875",
      "learning_opt_out": false
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces?version=2021-11-27"
  }
}

Create workspace

Create a workspace based on component objects. You must provide workspace components defining the content of the new workspace.

Note: The new workspace data cannot be larger than 1.5 MB. For larger requests, use the Create workspace asynchronously method.

Create a workspace based on component objects. You must provide workspace components defining the content of the new workspace.

Note: The new workspace data cannot be larger than 1.5 MB. For larger requests, use the Create workspace asynchronously method.

Create a workspace based on component objects. You must provide workspace components defining the content of the new workspace.

Note: The new workspace data cannot be larger than 1.5 MB. For larger requests, use the Create workspace asynchronously method.

Create a workspace based on component objects. You must provide workspace components defining the content of the new workspace.

Note: The new workspace data cannot be larger than 1.5 MB. For larger requests, use the Create workspace asynchronously method.

Create a workspace based on component objects. You must provide workspace components defining the content of the new workspace.

Note: The new workspace data cannot be larger than 1.5 MB. For larger requests, use the Create workspace asynchronously method.

POST /v1/workspaces
ServiceCall<Workspace> createWorkspace(CreateWorkspaceOptions createWorkspaceOptions)
createWorkspace(params)
create_workspace(
        self,
        *,
        name: Optional[str] = None,
        description: Optional[str] = None,
        language: Optional[str] = None,
        dialog_nodes: Optional[List['DialogNode']] = None,
        counterexamples: Optional[List['Counterexample']] = None,
        metadata: Optional[dict] = None,
        learning_opt_out: Optional[bool] = None,
        system_settings: Optional['WorkspaceSystemSettings'] = None,
        webhooks: Optional[List['Webhook']] = None,
        intents: Optional[List['CreateIntent']] = None,
        entities: Optional[List['CreateEntity']] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
CreateWorkspace(string name = null, string description = null, string language = null, List<DialogNode> dialogNodes = null, List<Counterexample> counterexamples = null, Dictionary<string, object> metadata = null, bool? learningOptOut = null, WorkspaceSystemSettings systemSettings = null, List<Webhook> webhooks = null, List<CreateIntent> intents = null, List<CreateEntity> entities = null, bool? includeAudit = null)

Rate limit

This operation is limited to 30 requests per 30 minutes.

Request

Use the CreateWorkspaceOptions.Builder to create a CreateWorkspaceOptions object that contains the parameter values for the createWorkspace method.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

CreateWorkspace

CreateWorkspaceOptions

The createWorkspace options.

parameters

  • name
    string

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    string

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    string

    The language of the workspace.

  • dialogNodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    JsonObject

    Any metadata related to the workspace.

  • learningOptOut
    boolean

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • systemSettings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • name
    str

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    str

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    str

    The language of the workspace.

  • dialog_nodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    dict

    Any metadata related to the workspace.

  • learning_opt_out
    bool

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • system_settings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • name
    string

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    string

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    string

    The language of the workspace.

  • dialogNodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    Dictionary<string, object>

    Any metadata related to the workspace.

  • learningOptOut
    bool?

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • systemSettings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"name\":\"API test\",\"intents\":[],\"entities\":[],\"language\":\"en\",\"description\":\"Example workspace created via API.\",\"dialog_nodes\":[]}" "{url}/v1/workspaces?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.CreateWorkspace(
    name: "API test",
    description: "Example workspace created via API"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

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

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

Workspace response = assistant.createWorkspace(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

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

assistant.createWorkspace(workspace)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

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

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

Response

Response Body

Workspace

Workspace

Workspace

Workspace

Workspace

Status Code

  • 201

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "name": "API test",
  "language": "en",
  "description": "Example workspace created via API.",
  "workspace_id": "245edf96-b89f-46ac-b647-c6618b2eb5f0",
  "learning_opt_out": false
}
  • {
  "name": "API test",
  "language": "en",
  "description": "Example workspace created via API.",
  "workspace_id": "245edf96-b89f-46ac-b647-c6618b2eb5f0",
  "learning_opt_out": false
}

Get information about a workspace

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

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

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

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

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

GET /v1/workspaces/{workspace_id}
ServiceCall<Workspace> getWorkspace(GetWorkspaceOptions getWorkspaceOptions)
getWorkspace(params)
get_workspace(
        self,
        workspace_id: str,
        *,
        export: Optional[bool] = None,
        include_audit: Optional[bool] = None,
        sort: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
GetWorkspace(string workspaceId, bool? export = null, bool? includeAudit = null, string sort = null)

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.

Request

Use the GetWorkspaceOptions.Builder to create a GetWorkspaceOptions object that contains the parameter values for the getWorkspace method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • sort
    string

    Indicates how the returned workspace data will be sorted. This parameter is valid only if export=true. Specify sort=stable to sort all workspace objects by unique identifier, in ascending alphabetical order.

    Allowable values: [stable]

GetWorkspaceOptions

The getWorkspace options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • _export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • sort
    string

    Indicates how the returned workspace data will be sorted. This parameter is valid only if export=true. Specify sort=stable to sort all workspace objects by unique identifier, in ascending alphabetical order.

    Allowable values: [stable]

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • export
    bool

    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.

    Default: false

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • sort
    str

    Indicates how the returned workspace data will be sorted. This parameter is valid only if export=true. Specify sort=stable to sort all workspace objects by unique identifier, in ascending alphabetical order.

    Allowable values: [stable]

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • export
    bool?

    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.

    Default: false

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • sort
    string

    Indicates how the returned workspace data will be sorted. This parameter is valid only if export=true. Specify sort=stable to sort all workspace objects by unique identifier, in ascending alphabetical order.

    Allowable values: [stable]

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.GetWorkspace(
    workspaceId: "{workspaceId}"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";

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

Workspace response = assistant.getWorkspace(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}'
};

assistant.getWorkspace(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.get_workspace(
    workspace_id='{workspace_id}'
).get_result()

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

Response

Response Body

Workspace

Workspace

Workspace

Workspace

Workspace

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "name": "Pizza app",
  "language": "en",
  "metadata": {},
  "description": "Pizza app",
  "status": "Available",
  "workspace_id": "pizza_app-e0f3",
  "learning_opt_out": false
}
  • {
  "name": "Pizza app",
  "language": "en",
  "metadata": {},
  "description": "Pizza app",
  "status": "Available",
  "workspace_id": "pizza_app-e0f3",
  "learning_opt_out": false
}

Update workspace

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

Note: The new workspace data cannot be larger than 1.5 MB. For larger requests, use the Update workspace asynchronously method.

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

Note: The new workspace data cannot be larger than 1.5 MB. For larger requests, use the Update workspace asynchronously method.

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

Note: The new workspace data cannot be larger than 1.5 MB. For larger requests, use the Update workspace asynchronously method.

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

Note: The new workspace data cannot be larger than 1.5 MB. For larger requests, use the Update workspace asynchronously method.

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

Note: The new workspace data cannot be larger than 1.5 MB. For larger requests, use the Update workspace asynchronously method.

POST /v1/workspaces/{workspace_id}
ServiceCall<Workspace> updateWorkspace(UpdateWorkspaceOptions updateWorkspaceOptions)
updateWorkspace(params)
update_workspace(
        self,
        workspace_id: str,
        *,
        name: Optional[str] = None,
        description: Optional[str] = None,
        language: Optional[str] = None,
        dialog_nodes: Optional[List['DialogNode']] = None,
        counterexamples: Optional[List['Counterexample']] = None,
        metadata: Optional[dict] = None,
        learning_opt_out: Optional[bool] = None,
        system_settings: Optional['WorkspaceSystemSettings'] = None,
        webhooks: Optional[List['Webhook']] = None,
        intents: Optional[List['CreateIntent']] = None,
        entities: Optional[List['CreateEntity']] = None,
        append: Optional[bool] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
UpdateWorkspace(string workspaceId, string name = null, string description = null, string language = null, List<DialogNode> dialogNodes = null, List<Counterexample> counterexamples = null, Dictionary<string, object> metadata = null, bool? learningOptOut = null, WorkspaceSystemSettings systemSettings = null, List<Webhook> webhooks = null, List<CreateIntent> intents = null, List<CreateEntity> entities = null, bool? append = null, bool? includeAudit = null)

Rate limit

This operation is limited to 30 request per 30 minutes.

Request

Use the UpdateWorkspaceOptions.Builder to create a UpdateWorkspaceOptions object that contains the parameter values for the updateWorkspace method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • append
    boolean

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

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

    Default: false

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

UpdateWorkspace

Valid data defining the new and updated workspace content.

The maximum size for this data is 50MB. If you need to import a larger amount of workspace data, consider importing components such as intents and entities using separate operations.

UpdateWorkspaceOptions

The updateWorkspace options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • name
    string

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    string

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    string

    The language of the workspace.

  • dialogNodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    JsonObject

    Any metadata related to the workspace.

  • learningOptOut
    boolean

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • systemSettings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

  • append
    boolean

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

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

    Default: false

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • name
    str

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    str

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    str

    The language of the workspace.

  • dialog_nodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    dict

    Any metadata related to the workspace.

  • learning_opt_out
    bool

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • system_settings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

  • append
    bool

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

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

    Default: false

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • name
    string

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    string

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    string

    The language of the workspace.

  • dialogNodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    Dictionary<string, object>

    Any metadata related to the workspace.

  • learningOptOut
    bool?

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • systemSettings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

  • append
    bool?

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

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

    Default: false

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"name\":\"Updated workspace\",\"intents\":[],\"entities\":[],\"language\":\"en\",\"description\":\"Example workspace updated via API.\",\"dialog_nodes\":[]}" "{url}/v1/workspaces/{workspace_id}?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.UpdateWorkspace(
    workspaceId: "{workspaceId}",
    name: "Updated workspace",
    description: "Example workspace updated via API"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String workspaceName = "Updated workspace";
String workspaceDescription = "Example workspace updated via API.";

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

Workspace response = assistant.updateWorkspace(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  name: 'Updated workspace',
  description: 'Test workspace modified via API.'
};

assistant.updateWorkspace(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.update_workspace(
    workspace_id='{workspace_id}',
    name='Updated workspace',
    description='Example workspace updated via API'
).get_result()

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

Response

Response Body

Workspace

Workspace

Workspace

Workspace

Workspace

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "name": "Updated workspace",
  "language": "en",
  "description": "Example workspace modified via API",
  "workspace_id": "164cca2d-8af7-4034-a121-89049a665183",
  "learning_opt_out": false
}
  • {
  "name": "Updated workspace",
  "language": "en",
  "description": "Example workspace modified via API",
  "workspace_id": "164cca2d-8af7-4034-a121-89049a665183",
  "learning_opt_out": false
}

Delete workspace

Delete a workspace from the service instance.

Delete a workspace from the service instance.

Delete a workspace from the service instance.

Delete a workspace from the service instance.

Delete a workspace from the service instance.

DELETE /v1/workspaces/{workspace_id}
ServiceCall<Void> deleteWorkspace(DeleteWorkspaceOptions deleteWorkspaceOptions)
deleteWorkspace(params)
delete_workspace(
        self,
        workspace_id: str,
        **kwargs,
    ) -> DetailedResponse
DeleteWorkspace(string workspaceId)

Rate limit

This operation is limited to 30 requests per 30 minutes.

Request

Use the DeleteWorkspaceOptions.Builder to create a DeleteWorkspaceOptions object that contains the parameter values for the deleteWorkspace method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

DeleteWorkspaceOptions

The deleteWorkspace options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • curl -X DELETE -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.DeleteWorkspace(
    workspaceId: "{workspaceId}"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";

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

assistant.deleteWorkspace(options).execute();
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '036fdc1e-71a3-432f-a404-0e4b4de6acad'
};

assistant.deleteWorkspace(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.delete_workspace(
    workspace_id='{workspace_id}'
).get_result()

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

Response

Response type: object

Response Body

EmptyResponse

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

No Sample Response

This method does not specify any sample responses.

Create workspace asynchronously

Create a workspace asynchronously based on component objects. You must provide workspace components defining the content of the new workspace.

A successful call to this method only initiates asynchronous creation of the workspace. The new workspace is not available until processing completes. To check the status of the asynchronous operation, use the Get information about a workspace method.

Create a workspace asynchronously based on component objects. You must provide workspace components defining the content of the new workspace.

A successful call to this method only initiates asynchronous creation of the workspace. The new workspace is not available until processing completes. To check the status of the asynchronous operation, use the Get information about a workspace method.

Create a workspace asynchronously based on component objects. You must provide workspace components defining the content of the new workspace.

A successful call to this method only initiates asynchronous creation of the workspace. The new workspace is not available until processing completes. To check the status of the asynchronous operation, use the Get information about a workspace method.

Create a workspace asynchronously based on component objects. You must provide workspace components defining the content of the new workspace.

A successful call to this method only initiates asynchronous creation of the workspace. The new workspace is not available until processing completes. To check the status of the asynchronous operation, use the Get information about a workspace method.

Create a workspace asynchronously based on component objects. You must provide workspace components defining the content of the new workspace.

A successful call to this method only initiates asynchronous creation of the workspace. The new workspace is not available until processing completes. To check the status of the asynchronous operation, use the Get information about a workspace method.

POST /v1/workspaces_async
ServiceCall<Workspace> createWorkspaceAsync(CreateWorkspaceAsyncOptions createWorkspaceAsyncOptions)
createWorkspaceAsync(params)
create_workspace_async(
        self,
        *,
        name: Optional[str] = None,
        description: Optional[str] = None,
        language: Optional[str] = None,
        dialog_nodes: Optional[List['DialogNode']] = None,
        counterexamples: Optional[List['Counterexample']] = None,
        metadata: Optional[dict] = None,
        learning_opt_out: Optional[bool] = None,
        system_settings: Optional['WorkspaceSystemSettings'] = None,
        webhooks: Optional[List['Webhook']] = None,
        intents: Optional[List['CreateIntent']] = None,
        entities: Optional[List['CreateEntity']] = None,
        **kwargs,
    ) -> DetailedResponse
CreateWorkspaceAsync(string name = null, string description = null, string language = null, List<DialogNode> dialogNodes = null, List<Counterexample> counterexamples = null, Dictionary<string, object> metadata = null, bool? learningOptOut = null, WorkspaceSystemSettings systemSettings = null, List<Webhook> webhooks = null, List<CreateIntent> intents = null, List<CreateEntity> entities = null)

Rate limit

This operation is limited to 30 requests per 30 minutes.

Request

Use the CreateWorkspaceAsyncOptions.Builder to create a CreateWorkspaceAsyncOptions object that contains the parameter values for the createWorkspaceAsync method.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

Request Body

CreateWorkspace

CreateWorkspaceAsyncOptions

The createWorkspaceAsync options.

parameters

  • name
    string

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    string

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    string

    The language of the workspace.

  • dialogNodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    JsonObject

    Any metadata related to the workspace.

  • learningOptOut
    boolean

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • systemSettings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

parameters

  • name
    str

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    str

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    str

    The language of the workspace.

  • dialog_nodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    dict

    Any metadata related to the workspace.

  • learning_opt_out
    bool

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • system_settings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

parameters

  • name
    string

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    string

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    string

    The language of the workspace.

  • dialogNodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    Dictionary<string, object>

    Any metadata related to the workspace.

  • learningOptOut
    bool?

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • systemSettings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

Response

Response Body

Workspace

Workspace

Workspace

Workspace

Workspace

Status Code

  • 202

    Successful request

  • 400

    Invalid request.

Example responses

  • Successful request. The workspace is being created asynchronously.

    {
  "status": "Processing",
  "name": "API test",
  "language": "en",
  "description": "Example workspace created via API.",
  "workspace_id": "245edf96-b89f-46ac-b647-c6618b2eb5f0",
  "learning_opt_out": false
}

  • Successful request. The workspace is being created asynchronously.

    {
  "status": "Processing",
  "name": "API test",
  "language": "en",
  "description": "Example workspace created via API.",
  "workspace_id": "245edf96-b89f-46ac-b647-c6618b2eb5f0",
  "learning_opt_out": false
}

Update workspace asynchronously

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

A successful call to this method only initiates an asynchronous update of the workspace. The updated workspace is not available until processing completes. To check the status of the asynchronous operation, use the Get information about a workspace method.

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

A successful call to this method only initiates an asynchronous update of the workspace. The updated workspace is not available until processing completes. To check the status of the asynchronous operation, use the Get information about a workspace method.

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

A successful call to this method only initiates an asynchronous update of the workspace. The updated workspace is not available until processing completes. To check the status of the asynchronous operation, use the Get information about a workspace method.

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

A successful call to this method only initiates an asynchronous update of the workspace. The updated workspace is not available until processing completes. To check the status of the asynchronous operation, use the Get information about a workspace method.

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

A successful call to this method only initiates an asynchronous update of the workspace. The updated workspace is not available until processing completes. To check the status of the asynchronous operation, use the Get information about a workspace method.

POST /v1/workspaces_async/{workspace_id}
ServiceCall<Workspace> updateWorkspaceAsync(UpdateWorkspaceAsyncOptions updateWorkspaceAsyncOptions)
updateWorkspaceAsync(params)
update_workspace_async(
        self,
        workspace_id: str,
        *,
        name: Optional[str] = None,
        description: Optional[str] = None,
        language: Optional[str] = None,
        dialog_nodes: Optional[List['DialogNode']] = None,
        counterexamples: Optional[List['Counterexample']] = None,
        metadata: Optional[dict] = None,
        learning_opt_out: Optional[bool] = None,
        system_settings: Optional['WorkspaceSystemSettings'] = None,
        webhooks: Optional[List['Webhook']] = None,
        intents: Optional[List['CreateIntent']] = None,
        entities: Optional[List['CreateEntity']] = None,
        append: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
UpdateWorkspaceAsync(string workspaceId, string name = null, string description = null, string language = null, List<DialogNode> dialogNodes = null, List<Counterexample> counterexamples = null, Dictionary<string, object> metadata = null, bool? learningOptOut = null, WorkspaceSystemSettings systemSettings = null, List<Webhook> webhooks = null, List<CreateIntent> intents = null, List<CreateEntity> entities = null, bool? append = null)

Rate limit

This operation is limited to 30 request per 30 minutes.

Request

Use the UpdateWorkspaceAsyncOptions.Builder to create a UpdateWorkspaceAsyncOptions object that contains the parameter values for the updateWorkspaceAsync method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • append
    boolean

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

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

    Default: false

Request Body

UpdateWorkspace

Valid data defining the new and updated workspace content.

The maximum size for this data is 50MB. If you need to import a larger amount of workspace data, consider importing components such as intents and entities using separate operations.

UpdateWorkspaceAsyncOptions

The updateWorkspaceAsync options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • name
    string

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    string

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    string

    The language of the workspace.

  • dialogNodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    JsonObject

    Any metadata related to the workspace.

  • learningOptOut
    boolean

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • systemSettings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

  • append
    boolean

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

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

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • name
    str

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    str

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    str

    The language of the workspace.

  • dialog_nodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    dict

    Any metadata related to the workspace.

  • learning_opt_out
    bool

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • system_settings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

  • append
    bool

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

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

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • name
    string

    The name of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 64

  • description
    string

    The description of the workspace. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • language
    string

    The language of the workspace.

  • dialogNodes

    An array of objects describing the dialog nodes in the workspace.

  • counterexamples

    An array of objects defining input examples that have been marked as irrelevant input.

  • metadata
    Dictionary<string, object>

    Any metadata related to the workspace.

  • learningOptOut
    bool?

    Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

    Default: false

  • systemSettings

    Global settings for the workspace.

  • webhooks

    A webhook that can be used by dialog nodes to make programmatic calls to an external function.

    Note: Currently, only a single webhook named main_webhook is supported.

  • intents

    An array of objects defining the intents for the workspace.

  • entities

    An array of objects describing the entities for the workspace.

  • append
    bool?

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

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

    Default: false

Response

Response Body

Workspace

Workspace

Workspace

Workspace

Workspace

Status Code

  • 202

    Successful request.

  • 400

    Invalid request.

Example responses

  • Successful request. The workspace is being updated asynchronously.

    {
  "status": "Processing",
  "name": "Updated workspace",
  "language": "en",
  "description": "Example workspace modified via API",
  "workspace_id": "164cca2d-8af7-4034-a121-89049a665183",
  "learning_opt_out": false
}

  • Successful request. The workspace is being updated asynchronously.

    {
  "status": "Processing",
  "name": "Updated workspace",
  "language": "en",
  "description": "Example workspace modified via API",
  "workspace_id": "164cca2d-8af7-4034-a121-89049a665183",
  "learning_opt_out": false
}

Export workspace asynchronously

Export the entire workspace asynchronously, including all workspace content.

A successful call to this method only initiates an asynchronous export. The exported JSON data is not available until processing completes. After the initial request is submitted, you can continue to poll by calling the same request again and checking the value of the status property. When processing has completed, the request returns the exported JSON data. Remember that the usual rate limits apply.

Export the entire workspace asynchronously, including all workspace content.

A successful call to this method only initiates an asynchronous export. The exported JSON data is not available until processing completes. After the initial request is submitted, you can continue to poll by calling the same request again and checking the value of the status property. When processing has completed, the request returns the exported JSON data. Remember that the usual rate limits apply.

Export the entire workspace asynchronously, including all workspace content.

A successful call to this method only initiates an asynchronous export. The exported JSON data is not available until processing completes. After the initial request is submitted, you can continue to poll by calling the same request again and checking the value of the status property. When processing has completed, the request returns the exported JSON data. Remember that the usual rate limits apply.

Export the entire workspace asynchronously, including all workspace content.

A successful call to this method only initiates an asynchronous export. The exported JSON data is not available until processing completes. After the initial request is submitted, you can continue to poll by calling the same request again and checking the value of the status property. When processing has completed, the request returns the exported JSON data. Remember that the usual rate limits apply.

Export the entire workspace asynchronously, including all workspace content.

A successful call to this method only initiates an asynchronous export. The exported JSON data is not available until processing completes. After the initial request is submitted, you can continue to poll by calling the same request again and checking the value of the status property. When processing has completed, the request returns the exported JSON data. Remember that the usual rate limits apply.

GET /v1/workspaces_async/{workspace_id}/export
ServiceCall<Workspace> exportWorkspaceAsync(ExportWorkspaceAsyncOptions exportWorkspaceAsyncOptions)
exportWorkspaceAsync(params)
export_workspace_async(
        self,
        workspace_id: str,
        *,
        include_audit: Optional[bool] = None,
        sort: Optional[str] = None,
        verbose: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
ExportWorkspaceAsync(string workspaceId, bool? includeAudit = null, string sort = null, bool? verbose = null)

Rate limit

The limit is 20 requests per 30 minutes.

Request

Use the ExportWorkspaceAsyncOptions.Builder to create a ExportWorkspaceAsyncOptions object that contains the parameter values for the exportWorkspaceAsync method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • sort
    string

    Indicates how the returned workspace data will be sorted. Specify sort=stable to sort all workspace objects by unique identifier, in ascending alphabetical order.

    Allowable values: [stable]

  • verbose
    boolean

    Whether the response should include the counts property, which indicates how many of each component (such as intents and entities) the workspace contains.

    Default: false

ExportWorkspaceAsyncOptions

The exportWorkspaceAsync options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • sort
    string

    Indicates how the returned workspace data will be sorted. Specify sort=stable to sort all workspace objects by unique identifier, in ascending alphabetical order.

    Allowable values: [stable]

  • verbose
    boolean

    Whether the response should include the counts property, which indicates how many of each component (such as intents and entities) the workspace contains.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • sort
    str

    Indicates how the returned workspace data will be sorted. Specify sort=stable to sort all workspace objects by unique identifier, in ascending alphabetical order.

    Allowable values: [stable]

  • verbose
    bool

    Whether the response should include the counts property, which indicates how many of each component (such as intents and entities) the workspace contains.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • sort
    string

    Indicates how the returned workspace data will be sorted. Specify sort=stable to sort all workspace objects by unique identifier, in ascending alphabetical order.

    Allowable values: [stable]

  • verbose
    bool?

    Whether the response should include the counts property, which indicates how many of each component (such as intents and entities) the workspace contains.

    Default: false

Response

Response Body

Workspace

Workspace

Workspace

Workspace

Workspace

Status Code

  • 200

    Successful request. Note that this does not mean that the asynchronous export operation has completed or was successful. Check the value of the status property to determine the status of the operation.

  • 202

    Request to export workspace has been accepted successfully.

  • 400

    Invalid request.

Example responses

  • Successful request. All asynchronous operations have completed, and the exported workspace data is included in the response.

    {
  "status": "Available",
  "workspace_id": "164cca2d-8af7-4034-a121-89049a665183",
  "name": "test workspace",
  "description": "test workspace description",
  "language": "en",
  "learning_opt_out": true,
  "counts": {
    "node": 0,
    "entity": 0,
    "intent": 0
  },
  "created": "2022-05-02T19:22:14.040Z",
  "updated": "2022-05-02T19:23:17.353Z",
  "intents": [],
  "entities": [],
  "dialog_nodes": [],
  "counterexamples": [],
  "system_settings": {
    "initial_context": {
      "init": true
    }
  },
  "metadata": {
    "api_version": {
      "major_version": "v1",
      "minor_version": "2017-05-26"
    }
  }
}

  • Successful request. All asynchronous operations have completed, and the exported workspace data is included in the response.

    {
  "status": "Available",
  "workspace_id": "164cca2d-8af7-4034-a121-89049a665183",
  "name": "test workspace",
  "description": "test workspace description",
  "language": "en",
  "learning_opt_out": true,
  "counts": {
    "node": 0,
    "entity": 0,
    "intent": 0
  },
  "created": "2022-05-02T19:22:14.040Z",
  "updated": "2022-05-02T19:23:17.353Z",
  "intents": [],
  "entities": [],
  "dialog_nodes": [],
  "counterexamples": [],
  "system_settings": {
    "initial_context": {
      "init": true
    }
  },
  "metadata": {
    "api_version": {
      "major_version": "v1",
      "minor_version": "2017-05-26"
    }
  }
}

  • Successful request. However, a previous asynchronous create operation has failed.

    {
  "status": "Failed",
  "workspace_id": "164cca2d-8af7-4034-a121-89049a665183",
  "status_errors": [
    {
      "message": "Invalid tree detected. Dialog node 'node_15_1490282289321' is poorly defined. Check its parent or previous_sibling value."
    }
  ],
  "status_description": "Workspace import failed",
  "name": "Created workspace",
  "language": "en",
  "learning_opt_out": false
}

  • Successful request. However, a previous asynchronous create operation has failed.

    {
  "status": "Failed",
  "workspace_id": "164cca2d-8af7-4034-a121-89049a665183",
  "status_errors": [
    {
      "message": "Invalid tree detected. Dialog node 'node_15_1490282289321' is poorly defined. Check its parent or previous_sibling value."
    }
  ],
  "status_description": "Workspace import failed",
  "name": "Created workspace",
  "language": "en",
  "learning_opt_out": false
}

  • Successful request. However, a previous asynchronous update request has failed.

    {
  "status": "Failed",
  "workspace_id": "164cca2d-8af7-4034-a121-89049a665183",
  "status_errors": [
    {
      "message": "Invalid tree detected. Dialog node 'node_15_1490282289321' is poorly defined. Check its parent or previous_sibling value."
    }
  ],
  "status_description": "Workspace update failed",
  "name": "Updated workspace",
  "language": "en",
  "learning_opt_out": false
}

  • Successful request. However, a previous asynchronous update request has failed.

    {
  "status": "Failed",
  "workspace_id": "164cca2d-8af7-4034-a121-89049a665183",
  "status_errors": [
    {
      "message": "Invalid tree detected. Dialog node 'node_15_1490282289321' is poorly defined. Check its parent or previous_sibling value."
    }
  ],
  "status_description": "Workspace update failed",
  "name": "Updated workspace",
  "language": "en",
  "learning_opt_out": false
}

List intents

List the intents for a workspace.

List the intents for a workspace.

List the intents for a workspace.

List the intents for a workspace.

List the intents for a workspace.

GET /v1/workspaces/{workspace_id}/intents
ServiceCall<IntentCollection> listIntents(ListIntentsOptions listIntentsOptions)
listIntents(params)
list_intents(
        self,
        workspace_id: str,
        *,
        export: Optional[bool] = None,
        page_limit: Optional[int] = None,
        include_count: Optional[bool] = None,
        sort: Optional[str] = None,
        cursor: Optional[str] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
ListIntents(string workspaceId, bool? export = null, long? pageLimit = null, bool? includeCount = null, string sort = null, string cursor = null, bool? includeAudit = null)

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.

Request

Use the ListIntentsOptions.Builder to create a ListIntentsOptions object that contains the parameter values for the listIntents method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • page_limit
    integer

    The number of records to return in each page of results.

    Default: 100

  • include_count
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned intents will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [intent,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

ListIntentsOptions

The listIntents options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • _export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • pageLimit
    number

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned intents will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [intent,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • export
    bool

    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.

    Default: false

  • page_limit
    int

    The number of records to return in each page of results.

    Default: 100

  • include_count
    bool

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    str

    The attribute by which returned intents will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [intent,updated]

  • cursor
    str

    A token identifying the page of results to retrieve.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • export
    bool?

    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.

    Default: false

  • pageLimit
    long?

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    bool?

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned intents will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [intent,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/intents?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.ListIntents(
    workspaceId: "{workspaceId}"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";

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

IntentCollection response = assistant.listIntents(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
};

assistant.listIntents(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.list_intents(
    workspace_id='{workspace_id}'
).get_result()

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

Response

Response Body

IntentCollection

IntentCollection

IntentCollection

IntentCollection

IntentCollection

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "intents": [
    {
      "intent": "goodbye"
    },
    {
      "intent": "hello"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents?version=2021-11-27"
  }
}
  • {
  "intents": [
    {
      "intent": "goodbye"
    },
    {
      "intent": "hello"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents?version=2021-11-27"
  }
}

Create intent

Create a new intent.

If you want to create multiple intents with a single API call, consider using the Update workspace method instead.

Create a new intent.

If you want to create multiple intents with a single API call, consider using the Update workspace method instead.

Create a new intent.

If you want to create multiple intents with a single API call, consider using the Update workspace method instead.

Create a new intent.

If you want to create multiple intents with a single API call, consider using the Update workspace method instead.

Create a new intent.

If you want to create multiple intents with a single API call, consider using the Update workspace method instead.

POST /v1/workspaces/{workspace_id}/intents
ServiceCall<Intent> createIntent(CreateIntentOptions createIntentOptions)
createIntent(params)
create_intent(
        self,
        workspace_id: str,
        intent: str,
        *,
        description: Optional[str] = None,
        examples: Optional[List['Example']] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
CreateIntent(string workspaceId, string intent, string description = null, List<Example> examples = null, bool? includeAudit = null)

Rate limit

This operation is limited to 2000 requests per 30 minutes.

Request

Use the CreateIntentOptions.Builder to create a CreateIntentOptions object that contains the parameter values for the createIntent method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
CreateIntent

The content of the new intent.

CreateIntentOptions

The createIntent options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The name of the intent. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
    • It cannot begin with the reserved prefix sys-.

    Possible values: 1 ≤ length ≤ 128

  • description
    string

    The description of the intent. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • examples

    An array of user input examples for the intent.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • intent
    Required*
    str

    The name of the intent. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
    • It cannot begin with the reserved prefix sys-.

    Possible values: 1 ≤ length ≤ 128

  • description
    str

    The description of the intent. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • examples

    An array of user input examples for the intent.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The name of the intent. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
    • It cannot begin with the reserved prefix sys-.

    Possible values: 1 ≤ length ≤ 128

  • description
    string

    The description of the intent. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • examples

    An array of user input examples for the intent.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"intent\":\"hello\",\"examples\":[{\"text\":\"Good morning\"},{\"text\":\"Hi there\"}]}" "{url}/v1/workspaces/{workspace_id}/intents?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.CreateIntent(
    workspaceId: "{workspaceId}",
    intent: "hello",
    examples: new List<Example>()
    {
        new Example()
        {
            Text = "Good morning"
        },
        new Example()
        {
            Text = "Hi there"
        }
    }
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String intent = "hello";

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

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

Intent response = assistant.createIntent(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  intent: 'hello',
  examples: [
    {
      text: 'Good morning'
    },
    {
      text: 'Hi there'
    }
  ]
};

assistant.createIntent(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.create_intent(
    workspace_id='{workspace_id}',
    intent='hello',
    examples=[
        {'text': 'Good morning'},
        {'text': 'Hi there'}
    ]
).get_result()

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

Response

Response Body

Intent

Intent

Intent

Intent

Intent

Status Code

  • 201

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "intent": "hello"
}
  • {
  "intent": "hello"
}

Get intent

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

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

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

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

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

GET /v1/workspaces/{workspace_id}/intents/{intent}
ServiceCall<Intent> getIntent(GetIntentOptions getIntentOptions)
getIntent(params)
get_intent(
        self,
        workspace_id: str,
        intent: str,
        *,
        export: Optional[bool] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
GetIntent(string workspaceId, string intent, bool? export = null, bool? includeAudit = null)

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.

Request

Use the GetIntentOptions.Builder to create a GetIntentOptions object that contains the parameter values for the getIntent method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

GetIntentOptions

The getIntent options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • _export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • intent
    Required*
    str

    The intent name.

  • export
    bool

    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.

    Default: false

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • export
    bool?

    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.

    Default: false

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/intents/hello?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.GetIntent(
    workspaceId: "{workspaceId}",
    intent: "hello"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String intent = "hello";

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

Intent response = assistant.getIntent(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  intent: 'hello'
};

assistant.getIntent(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.get_intent(
    workspace_id='{workspace_id}',
    intent='hello'
).get_result()

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

Response

Response Body

Intent

Intent

Intent

Intent

Intent

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "intent": "hello"
}
  • {
  "intent": "hello"
}

Update intent

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

If you want to update multiple intents with a single API call, consider using the Update workspace method instead.

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

If you want to update multiple intents with a single API call, consider using the Update workspace method instead.

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

If you want to update multiple intents with a single API call, consider using the Update workspace method instead.

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

If you want to update multiple intents with a single API call, consider using the Update workspace method instead.

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

If you want to update multiple intents with a single API call, consider using the Update workspace method instead.

POST /v1/workspaces/{workspace_id}/intents/{intent}
ServiceCall<Intent> updateIntent(UpdateIntentOptions updateIntentOptions)
updateIntent(params)
update_intent(
        self,
        workspace_id: str,
        intent: str,
        *,
        new_intent: Optional[str] = None,
        new_description: Optional[str] = None,
        new_examples: Optional[List['Example']] = None,
        append: Optional[bool] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
UpdateIntent(string workspaceId, string intent, string newIntent = null, string newDescription = null, List<Example> newExamples = null, bool? append = null, bool? includeAudit = null)

Rate limit

This operation is limited to 2000 requests per 30 minutes.

Request

Use the UpdateIntentOptions.Builder to create a UpdateIntentOptions object that contains the parameter values for the updateIntent method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • append
    boolean

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

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

    Default: false

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
UpdateIntent

The updated content of the intent.

Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) 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 update.

UpdateIntentOptions

The updateIntent options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • newIntent
    string

    The name of the intent. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
    • It cannot begin with the reserved prefix sys-.

    Possible values: 1 ≤ length ≤ 128

  • newDescription
    string

    The description of the intent. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • newExamples

    An array of user input examples for the intent.

  • append
    boolean

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

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

    Default: false

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • intent
    Required*
    str

    The intent name.

  • new_intent
    str

    The name of the intent. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
    • It cannot begin with the reserved prefix sys-.

    Possible values: 1 ≤ length ≤ 128

  • new_description
    str

    The description of the intent. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • new_examples

    An array of user input examples for the intent.

  • append
    bool

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

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

    Default: false

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • newIntent
    string

    The name of the intent. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
    • It cannot begin with the reserved prefix sys-.

    Possible values: 1 ≤ length ≤ 128

  • newDescription
    string

    The description of the intent. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • newExamples

    An array of user input examples for the intent.

  • append
    bool?

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

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

    Default: false

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"intent\":\"hello\",\"examples\":[{\"text\":\"Good afternoon\"}],\"description\":\"Updated intent\"}" "{url}/v1/workspaces/{workspace_id}/intents/hello?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.UpdateIntent(
    workspaceId: "{workspaceId}",
    intent: "hello",
    newExamples: new List<Example>()
    {
        new Example()
        {
            Text = "Good afternoon"
        }
    },
    newDescription: "Updated intent"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String intent = "hello";
String description = "Updated intent";

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

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

Intent response = assistant.updateIntent(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  intent: 'hello',
  newExamples: [
    {
      text: 'Good afternoon'
    }
  ],
  newDescription: 'Updated intent'
};

assistant.updateIntent(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.update_intent(
    workspace_id='{workspace_id}',
    intent='hello',
    new_examples=[
        {'text': 'Good afternoon'}
    ],
    new_description='Updated intent'
).get_result()

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

Response

Response Body

Intent

Intent

Intent

Intent

Intent

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "intent": "hello",
  "description": "Updated intent"
}
  • {
  "intent": "hello",
  "description": "Updated intent"
}

Delete intent

Delete an intent from a workspace.

Delete an intent from a workspace.

Delete an intent from a workspace.

Delete an intent from a workspace.

Delete an intent from a workspace.

DELETE /v1/workspaces/{workspace_id}/intents/{intent}
ServiceCall<Void> deleteIntent(DeleteIntentOptions deleteIntentOptions)
deleteIntent(params)
delete_intent(
        self,
        workspace_id: str,
        intent: str,
        **kwargs,
    ) -> DetailedResponse
DeleteIntent(string workspaceId, string intent)

Rate limit

This operation is limited to 2000 requests per 30 minutes.

Request

Use the DeleteIntentOptions.Builder to create a DeleteIntentOptions object that contains the parameter values for the deleteIntent method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

DeleteIntentOptions

The deleteIntent options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • intent
    Required*
    str

    The intent name.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • curl -X DELETE -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/intents/hello?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.DeleteIntent(
    workspaceId: "{workspaceId}",
    intent: "hello"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String intent = "hello";

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

assistant.deleteIntent(options).execute();
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  intent: 'hello'
};

assistant.deleteIntent(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.delete_intent(
    workspace_id='{workspace_id}',
    intent='hello'
).get_result()

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

Response

Response type: object

Response Body

EmptyResponse

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

No Sample Response

This method does not specify any sample responses.

List user input examples

List the user input examples for an intent, optionally including contextual entity mentions.

List the user input examples for an intent, optionally including contextual entity mentions.

List the user input examples for an intent, optionally including contextual entity mentions.

List the user input examples for an intent, optionally including contextual entity mentions.

List the user input examples for an intent, optionally including contextual entity mentions.

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples
ServiceCall<ExampleCollection> listExamples(ListExamplesOptions listExamplesOptions)
listExamples(params)
list_examples(
        self,
        workspace_id: str,
        intent: str,
        *,
        page_limit: Optional[int] = None,
        include_count: Optional[bool] = None,
        sort: Optional[str] = None,
        cursor: Optional[str] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
ListExamples(string workspaceId, string intent, long? pageLimit = null, bool? includeCount = null, string sort = null, string cursor = null, bool? includeAudit = null)

Rate limit

This operation is limited to 2500 requests per 30 minutes.

Request

Use the ListExamplesOptions.Builder to create a ListExamplesOptions object that contains the parameter values for the listExamples method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • page_limit
    integer

    The number of records to return in each page of results.

    Default: 100

  • include_count
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned examples will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [text,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

ListExamplesOptions

The listExamples options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • pageLimit
    number

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned examples will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [text,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • intent
    Required*
    str

    The intent name.

  • page_limit
    int

    The number of records to return in each page of results.

    Default: 100

  • include_count
    bool

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    str

    The attribute by which returned examples will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [text,updated]

  • cursor
    str

    A token identifying the page of results to retrieve.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • pageLimit
    long?

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    bool?

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned examples will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [text,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/intents/hello/examples?version=2021-06-14&export=true"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.ListExamples(
    workspaceId: "{workspaceId}",
    intent: "hello"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String intent = "hello";

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

ExampleCollection response = assistant.listExamples(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  intent: 'hello'
};

assistant.listExamples(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.list_examples(
    workspace_id='{workspace_id}',
    intent='hello'
).get_result()

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

Response

Response Body

ExampleCollection

ExampleCollection

ExampleCollection

ExampleCollection

ExampleCollection

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "examples": [
    {
      "text": "Good afternoon"
    },
    {
      "text": "hi there"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?version=2021-11-27&export=true"
  }
}
  • {
  "examples": [
    {
      "text": "Good afternoon"
    },
    {
      "text": "hi there"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?version=2021-11-27&export=true"
  }
}

Create user input example

Add a new user input example to an intent.

If you want to add multiple examples with a single API call, consider using the Update intent method instead.

Add a new user input example to an intent.

If you want to add multiple examples with a single API call, consider using the Update intent method instead.

Add a new user input example to an intent.

If you want to add multiple examples with a single API call, consider using the Update intent method instead.

Add a new user input example to an intent.

If you want to add multiple examples with a single API call, consider using the Update intent method instead.

Add a new user input example to an intent.

If you want to add multiple examples with a single API call, consider using the Update intent method instead.

POST /v1/workspaces/{workspace_id}/intents/{intent}/examples
ServiceCall<Example> createExample(CreateExampleOptions createExampleOptions)
createExample(params)
create_example(
        self,
        workspace_id: str,
        intent: str,
        text: str,
        *,
        mentions: Optional[List['Mention']] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
CreateExample(string workspaceId, string intent, string text, List<Mention> mentions = null, bool? includeAudit = null)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the CreateExampleOptions.Builder to create a CreateExampleOptions object that contains the parameter values for the createExample method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
Example

The content of the new user input example.

CreateExampleOptions

The createExample options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • text
    Required*
    string

    The text of a user input example. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • mentions

    An array of contextual entity mentions.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • intent
    Required*
    str

    The intent name.

  • text
    Required*
    str

    The text of a user input example. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • mentions

    An array of contextual entity mentions.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • text
    Required*
    string

    The text of a user input example. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • mentions

    An array of contextual entity mentions.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"text\":\"Howdy!\"}" "{url}/v1/workspaces/{workspace_id}/intents/hello/examples?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.CreateExample(
    workspaceId: "{workspaceId}",
    intent: "hello",
    text: "Howdy!"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String intent = "hello";
String example = "Howdy!";

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

Example response = assistant.createExample(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  intent: 'hello',
  text: 'Howdy!'
};

assistant.createExample(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.create_example(
    workspace_id='{workspace_id}',
    intent='hello',
    text='Howdy!'
).get_result()

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

Response

Response Body

Example

Example

Example

Example

Example

Status Code

  • 201

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "text": "Howdy!"
}
  • {
  "text": "Howdy!"
}

Get user input example

Get information about a user input example.

Get information about a user input example.

Get information about a user input example.

Get information about a user input example.

Get information about a user input example.

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
ServiceCall<Example> getExample(GetExampleOptions getExampleOptions)
getExample(params)
get_example(
        self,
        workspace_id: str,
        intent: str,
        text: str,
        *,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
GetExample(string workspaceId, string intent, string text, bool? includeAudit = null)

Rate limit

This operation is limited to 6000 requests per 5 minutes.

Request

Use the GetExampleOptions.Builder to create a GetExampleOptions object that contains the parameter values for the getExample method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • text
    Required*
    string

    The text of the user input example.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

GetExampleOptions

The getExample options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • text
    Required*
    string

    The text of the user input example.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • intent
    Required*
    str

    The intent name.

  • text
    Required*
    str

    The text of the user input example.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • text
    Required*
    string

    The text of the user input example.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/intents/hello/examples/Good%20afternoon?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.GetExample(
    workspaceId: "{workspaceId}",
    intent: "hello",
    text: "Good afternoon"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String intent = "hello";
String example = "Good afternoon";

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

Example response = assistant.getExample(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  intent: 'hello',
  text: 'Good afternoon'
};

assistant.getExample(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.get_example(
    workspace_id='{workspace_id}',
    intent='hello',
    text='Good afternoon'
).get_result()

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

Response

Response Body

Example

Example

Example

Example

Example

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "text": "Good afternoon"
}
  • {
  "text": "Good afternoon"
}

Update user input example

Update the text of a user input example.

If you want to update multiple examples with a single API call, consider using the Update intent method instead.

Update the text of a user input example.

If you want to update multiple examples with a single API call, consider using the Update intent method instead.

Update the text of a user input example.

If you want to update multiple examples with a single API call, consider using the Update intent method instead.

Update the text of a user input example.

If you want to update multiple examples with a single API call, consider using the Update intent method instead.

Update the text of a user input example.

If you want to update multiple examples with a single API call, consider using the Update intent method instead.

POST /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
ServiceCall<Example> updateExample(UpdateExampleOptions updateExampleOptions)
updateExample(params)
update_example(
        self,
        workspace_id: str,
        intent: str,
        text: str,
        *,
        new_text: Optional[str] = None,
        new_mentions: Optional[List['Mention']] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
UpdateExample(string workspaceId, string intent, string text, string newText = null, List<Mention> newMentions = null, bool? includeAudit = null)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the UpdateExampleOptions.Builder to create a UpdateExampleOptions object that contains the parameter values for the updateExample method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • text
    Required*
    string

    The text of the user input example.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
UpdateExample

The new text of the user input example.

UpdateExampleOptions

The updateExample options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • text
    Required*
    string

    The text of the user input example.

  • newText
    string

    The text of the user input example. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • newMentions

    An array of contextual entity mentions.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • intent
    Required*
    str

    The intent name.

  • text
    Required*
    str

    The text of the user input example.

  • new_text
    str

    The text of the user input example. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • new_mentions

    An array of contextual entity mentions.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • text
    Required*
    string

    The text of the user input example.

  • newText
    string

    The text of the user input example. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • newMentions

    An array of contextual entity mentions.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"text\":\"Hello there!\"}" "{url}/v1/workspaces/{workspace_id}/intents/hello/examples/hi%20there?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.UpdateExample(
    workspaceId: "{workspaceId}",
    intent: "hello",
    text: "Hi there",
    newText: "Hello there!"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String intent = "hello";
String example = "Hi there";
String newText = "Hello there!";

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

Example response = assistant.updateExample(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  intent: 'hello',
  text: 'Hi there',
  newText: 'Hello there!'         
};

assistant.updateExample(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.update_example(
    workspace_id='{workspace_id}',
    intent='hello',
    text='Hi there',
    new_text='Hello there!'
).get_result()

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

Response

Response Body

Example

Example

Example

Example

Example

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "text": "Hello there!"
}
  • {
  "text": "Hello there!"
}

Delete user input example

Delete a user input example from an intent.

Delete a user input example from an intent.

Delete a user input example from an intent.

Delete a user input example from an intent.

Delete a user input example from an intent.

DELETE /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
ServiceCall<Void> deleteExample(DeleteExampleOptions deleteExampleOptions)
deleteExample(params)
delete_example(
        self,
        workspace_id: str,
        intent: str,
        text: str,
        **kwargs,
    ) -> DetailedResponse
DeleteExample(string workspaceId, string intent, string text)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the DeleteExampleOptions.Builder to create a DeleteExampleOptions object that contains the parameter values for the deleteExample method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • text
    Required*
    string

    The text of the user input example.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

DeleteExampleOptions

The deleteExample options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • text
    Required*
    string

    The text of the user input example.

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • intent
    Required*
    str

    The intent name.

  • text
    Required*
    str

    The text of the user input example.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • intent
    Required*
    string

    The intent name.

  • text
    Required*
    string

    The text of the user input example.

  • curl -X DELETE -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/intents/hello/examples/Good%20afternoon?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.DeleteExample(
    workspaceId: "{workspaceId}",
    intent: "hello",
    text: "Good afternoon"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String intent = "hello";
String example = "Good afternoon";

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

assistant.deleteExample(options).execute();
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  intent: 'hello',
  text: 'Good afternoon'
};

assistant.deleteExample(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.delete_example(
    workspace_id='{workspace_id}',
    intent='hello',
    text='Good afternoon'
).get_result()

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

Response

Response type: object

Response Body

EmptyResponse

Status Code

  • 200

    Successful request.

  • 400

    Invalid request

No Sample Response

This method does not specify any sample responses.

List counterexamples

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

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

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

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

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

GET /v1/workspaces/{workspace_id}/counterexamples
ServiceCall<CounterexampleCollection> listCounterexamples(ListCounterexamplesOptions listCounterexamplesOptions)
listCounterexamples(params)
list_counterexamples(
        self,
        workspace_id: str,
        *,
        page_limit: Optional[int] = None,
        include_count: Optional[bool] = None,
        sort: Optional[str] = None,
        cursor: Optional[str] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
ListCounterexamples(string workspaceId, long? pageLimit = null, bool? includeCount = null, string sort = null, string cursor = null, bool? includeAudit = null)

Rate limit

This operation is limited to 2500 requests per 30 minutes.

Request

Use the ListCounterexamplesOptions.Builder to create a ListCounterexamplesOptions object that contains the parameter values for the listCounterexamples method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • page_limit
    integer

    The number of records to return in each page of results.

    Default: 100

  • include_count
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned counterexamples will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [text,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

ListCounterexamplesOptions

The listCounterexamples options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • pageLimit
    number

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned counterexamples will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [text,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • page_limit
    int

    The number of records to return in each page of results.

    Default: 100

  • include_count
    bool

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    str

    The attribute by which returned counterexamples will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [text,updated]

  • cursor
    str

    A token identifying the page of results to retrieve.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • pageLimit
    long?

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    bool?

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned counterexamples will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [text,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/counterexamples?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.ListCounterexamples(
    workspaceId: "{workspaceId}"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";

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

CounterexampleCollection response = assistant.listCounterexamples(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}'
};

assistant.listCounterexamples(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.list_counterexamples(
    workspace_id='{workspace_id}'
).get_result()

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

Response

Response Body

CounterexampleCollection

CounterexampleCollection

CounterexampleCollection

CounterexampleCollection

CounterexampleCollection

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "counterexamples": [
    {
      "text": "What are you wearing?"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples?version=2021-11-27"
  }
}
  • {
  "counterexamples": [
    {
      "text": "What are you wearing?"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples?version=2021-11-27"
  }
}

Create counterexample

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

If you want to add multiple counterexamples with a single API call, consider using the Update workspace method instead.

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

If you want to add multiple counterexamples with a single API call, consider using the Update workspace method instead.

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

If you want to add multiple counterexamples with a single API call, consider using the Update workspace method instead.

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

If you want to add multiple counterexamples with a single API call, consider using the Update workspace method instead.

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

If you want to add multiple counterexamples with a single API call, consider using the Update workspace method instead.

POST /v1/workspaces/{workspace_id}/counterexamples
ServiceCall<Counterexample> createCounterexample(CreateCounterexampleOptions createCounterexampleOptions)
createCounterexample(params)
create_counterexample(
        self,
        workspace_id: str,
        text: str,
        *,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
CreateCounterexample(string workspaceId, string text, bool? includeAudit = null)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the CreateCounterexampleOptions.Builder to create a CreateCounterexampleOptions object that contains the parameter values for the createCounterexample method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
Counterexample

The content of the new counterexample.

CreateCounterexampleOptions

The createCounterexample options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • text
    Required*
    string

    The text of a user input marked as irrelevant input. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • text
    Required*
    str

    The text of a user input marked as irrelevant input. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • text
    Required*
    string

    The text of a user input marked as irrelevant input. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"text\":\"Make me a sandwich\"}" "{url}/v1/workspaces/{workspace_id}/counterexamples?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.CreateCounterexample(
    workspaceId: "{workspaceId}",
    text: "Make me a sandwich"
    );

Console.WriteLine(result.Response);

counterexample = result.Result.Text;
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String text = "Make me a sandwich";

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

Counterexample response = assistant.createCounterexample(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  text: 'Make me a sandwich'
};

assistant.createCounterexample(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.create_counterexample(
    workspace_id='{workspace_id}',
    text='Make me a sandwich'
).get_result()

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

Response

Response Body

Counterexample

Counterexample

Counterexample

Counterexample

Counterexample

Status Code

  • 201

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "text": "Make me a sandwich"
}
  • {
  "text": "Make me a sandwich"
}

Get counterexample

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

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

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

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

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

GET /v1/workspaces/{workspace_id}/counterexamples/{text}
ServiceCall<Counterexample> getCounterexample(GetCounterexampleOptions getCounterexampleOptions)
getCounterexample(params)
get_counterexample(
        self,
        workspace_id: str,
        text: str,
        *,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
GetCounterexample(string workspaceId, string text, bool? includeAudit = null)

Rate limit

This operation is limited to 6000 requests per 5 minutes.

Request

Use the GetCounterexampleOptions.Builder to create a GetCounterexampleOptions object that contains the parameter values for the getCounterexample method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • text
    Required*
    string

    The text of a user input counterexample (for example, What are you wearing?).

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

GetCounterexampleOptions

The getCounterexample options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • text
    Required*
    string

    The text of a user input counterexample (for example, What are you wearing?).

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • text
    Required*
    str

    The text of a user input counterexample (for example, What are you wearing?).

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • text
    Required*
    string

    The text of a user input counterexample (for example, What are you wearing?).

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/counterexamples/What%20are%20you%20wearing%3F?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.GetCounterexample(
    workspaceId: "{workspaceId}",
    text: "What are you wearing?"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String text = "What are you wearing?";

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

Counterexample response = assistant.getCounterexample(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  text: 'What are you wearing?'
};

assistant.getCounterexample(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.get_counterexample(
    workspace_id='{workspace_id}',
    text='What are you wearing?'
).get_result()

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

Response

Response Body

Counterexample

Counterexample

Counterexample

Counterexample

Counterexample

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "text": "What are you wearing?"
}
  • {
  "text": "What are you wearing?"
}

Update counterexample

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

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

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

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

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

POST /v1/workspaces/{workspace_id}/counterexamples/{text}
ServiceCall<Counterexample> updateCounterexample(UpdateCounterexampleOptions updateCounterexampleOptions)
updateCounterexample(params)
update_counterexample(
        self,
        workspace_id: str,
        text: str,
        *,
        new_text: Optional[str] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
UpdateCounterexample(string workspaceId, string text, string newText = null, bool? includeAudit = null)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the UpdateCounterexampleOptions.Builder to create a UpdateCounterexampleOptions object that contains the parameter values for the updateCounterexample method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • text
    Required*
    string

    The text of a user input counterexample (for example, What are you wearing?).

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
UpdateCounterexample

The text of the counterexample.

UpdateCounterexampleOptions

The updateCounterexample options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • text
    Required*
    string

    The text of a user input counterexample (for example, What are you wearing?).

  • newText
    string

    The text of a user input marked as irrelevant input. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • text
    Required*
    str

    The text of a user input counterexample (for example, What are you wearing?).

  • new_text
    str

    The text of a user input marked as irrelevant input. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • text
    Required*
    string

    The text of a user input counterexample (for example, What are you wearing?).

  • newText
    string

    The text of a user input marked as irrelevant input. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 1024

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"text\":\"Make me a cheeseburger\"}" "{url}/v1/workspaces/{workspace_id}/counterexamples/Make%20me%20a%20sandwich?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.UpdateCounterexample(
    workspaceId: "{workspaceId}",
    text: "Make me a sandwich",
    newText: "Make me a cheeseburger"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String text = "Make me a sandwich";
String newText = "Make me a cheeseburger";

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

Counterexample response = assistant.updateCounterexample(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  text: 'Make me a sandwich',
  newText: 'Make me a cheeseburger'
};

assistant.updateCounterexample(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.update_counterexample(
    workspace_id='{workspace_id}',
    text='Make me a sandwich',
    new_text='Make me a cheeseburger'
).get_result()

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

Response

Response Body

Counterexample

Counterexample

Counterexample

Counterexample

Counterexample

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "text": "Make me a cheeseburger"
}
  • {
  "text": "Make me a cheeseburger"
}

Delete counterexample

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

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

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

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

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

DELETE /v1/workspaces/{workspace_id}/counterexamples/{text}
ServiceCall<Void> deleteCounterexample(DeleteCounterexampleOptions deleteCounterexampleOptions)
deleteCounterexample(params)
delete_counterexample(
        self,
        workspace_id: str,
        text: str,
        **kwargs,
    ) -> DetailedResponse
DeleteCounterexample(string workspaceId, string text)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the DeleteCounterexampleOptions.Builder to create a DeleteCounterexampleOptions object that contains the parameter values for the deleteCounterexample method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • text
    Required*
    string

    The text of a user input counterexample (for example, What are you wearing?).

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

DeleteCounterexampleOptions

The deleteCounterexample options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • text
    Required*
    string

    The text of a user input counterexample (for example, What are you wearing?).

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • text
    Required*
    str

    The text of a user input counterexample (for example, What are you wearing?).

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • text
    Required*
    string

    The text of a user input counterexample (for example, What are you wearing?).

  • curl -X DELETE -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/counterexamples/Make%20me%20a%20sandwich?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.DeleteCounterexample(
    workspaceId: "{workspaceId}",
    text: "Make me a sandwich"
);

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String text = "Make me a sandwich";

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

assistant.deleteCounterexample(options).execute();
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  text: 'Make me a sandwich'
};

assistant.deleteCounterexample(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.delete_counterexample(
    workspace_id='{workspace_id}',
    text='Make me a sandwich'
).get_result()

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

Response

Response type: object

Response Body

EmptyResponse

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

No Sample Response

This method does not specify any sample responses.

List entities

List the entities for a workspace.

List the entities for a workspace.

List the entities for a workspace.

List the entities for a workspace.

List the entities for a workspace.

GET /v1/workspaces/{workspace_id}/entities
ServiceCall<EntityCollection> listEntities(ListEntitiesOptions listEntitiesOptions)
listEntities(params)
list_entities(
        self,
        workspace_id: str,
        *,
        export: Optional[bool] = None,
        page_limit: Optional[int] = None,
        include_count: Optional[bool] = None,
        sort: Optional[str] = None,
        cursor: Optional[str] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
ListEntities(string workspaceId, bool? export = null, long? pageLimit = null, bool? includeCount = null, string sort = null, string cursor = null, bool? includeAudit = null)

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.

Request

Use the ListEntitiesOptions.Builder to create a ListEntitiesOptions object that contains the parameter values for the listEntities method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • page_limit
    integer

    The number of records to return in each page of results.

    Default: 100

  • include_count
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned entities will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [entity,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

ListEntitiesOptions

The listEntities options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • _export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • pageLimit
    number

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned entities will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [entity,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • export
    bool

    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.

    Default: false

  • page_limit
    int

    The number of records to return in each page of results.

    Default: 100

  • include_count
    bool

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    str

    The attribute by which returned entities will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [entity,updated]

  • cursor
    str

    A token identifying the page of results to retrieve.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • export
    bool?

    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.

    Default: false

  • pageLimit
    long?

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    bool?

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned entities will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [entity,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/entities?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.ListEntities(
    workspaceId: "{workspaceId}"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";

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

EntityCollection response = assistant.listEntities(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}'
};

assistant.listEntities(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.list_entities(
    workspace_id='{workspace_id}'
).get_result()

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

Response

Response Body

EntityCollection

An array of objects describing the entities for the workspace.

EntityCollection

An array of objects describing the entities for the workspace.

EntityCollection

An array of objects describing the entities for the workspace.

EntityCollection

An array of objects describing the entities for the workspace.

EntityCollection

An array of objects describing the entities for the workspace.

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "entities": [
    {
      "entity": "animal"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/entities?version=2021-11-27"
  }
}
  • {
  "entities": [
    {
      "entity": "animal"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/entities?version=2021-11-27"
  }
}

Create entity

Create a new entity, or enable a system entity.

If you want to create multiple entities with a single API call, consider using the Update workspace method instead.

Create a new entity, or enable a system entity.

If you want to create multiple entities with a single API call, consider using the Update workspace method instead.

Create a new entity, or enable a system entity.

If you want to create multiple entities with a single API call, consider using the Update workspace method instead.

Create a new entity, or enable a system entity.

If you want to create multiple entities with a single API call, consider using the Update workspace method instead.

Create a new entity, or enable a system entity.

If you want to create multiple entities with a single API call, consider using the Update workspace method instead.

POST /v1/workspaces/{workspace_id}/entities
ServiceCall<Entity> createEntity(CreateEntityOptions createEntityOptions)
createEntity(params)
create_entity(
        self,
        workspace_id: str,
        entity: str,
        *,
        description: Optional[str] = None,
        metadata: Optional[dict] = None,
        fuzzy_match: Optional[bool] = None,
        values: Optional[List['CreateValue']] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
CreateEntity(string workspaceId, string entity, string description = null, Dictionary<string, object> metadata = null, bool? fuzzyMatch = null, List<CreateValue> values = null, bool? includeAudit = null)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the CreateEntityOptions.Builder to create a CreateEntityOptions object that contains the parameter values for the createEntity method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
CreateEntity

The content of the new entity.

CreateEntityOptions

The createEntity options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, and hyphen characters.
    • If you specify an entity name beginning with the reserved prefix sys-, it must be the name of a system entity that you want to enable. (Any entity content specified with the request is ignored.).

    Possible values: 1 ≤ length ≤ 64

  • description
    string

    The description of the entity. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • metadata
    JsonObject

    Any metadata related to the entity.

  • fuzzyMatch
    boolean

    Whether to use fuzzy matching for the entity.

  • values

    An array of objects describing the entity values.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, and hyphen characters.
    • If you specify an entity name beginning with the reserved prefix sys-, it must be the name of a system entity that you want to enable. (Any entity content specified with the request is ignored.).

    Possible values: 1 ≤ length ≤ 64

  • description
    str

    The description of the entity. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • metadata
    dict

    Any metadata related to the entity.

  • fuzzy_match
    bool

    Whether to use fuzzy matching for the entity.

  • values

    An array of objects describing the entity values.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, and hyphen characters.
    • If you specify an entity name beginning with the reserved prefix sys-, it must be the name of a system entity that you want to enable. (Any entity content specified with the request is ignored.).

    Possible values: 1 ≤ length ≤ 64

  • description
    string

    The description of the entity. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • metadata
    Dictionary<string, object>

    Any metadata related to the entity.

  • fuzzyMatch
    bool?

    Whether to use fuzzy matching for the entity.

  • values

    An array of objects describing the entity values.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"entity\": \"beverage\",\"values\":[{\"value\":\"water\"},{\"value\":\"orange juice\"},{\"value\":\"soda\"}]}" "{url}/v1/workspaces/{workspace_id}/entities?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.CreateEntity(
    workspaceId: "{workspaceId}",
    entity: "beverage",
    values: new List<CreateValue>()
    {
        new CreateValue()
        {
            Value = "water"
        },
        new CreateValue()
        {
            Value = "orange juice"
        },
        new CreateValue()
        {
            Value = "soda"
        }
    }
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";

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

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

Entity response = assistant.createEntity(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage',
  values: [
    {
      value: 'water'
    },
    {
      value: 'orange juice'
    },
    {
      value: 'soda'
    }
  ]
};

assistant.createEntity(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.create_entity(
    workspace_id='{workspace_id}',
    entity='beverage',
    values=[
        {'value': 'water'},
        {'value': 'orange juice'},
        {'value': 'soda'}
    ]
).get_result()

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

Response

Response Body

Entity

Entity

Entity

Entity

Entity

Status Code

  • 201

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "entity": "beverage"
}
  • {
  "entity": "beverage"
}

Get entity

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

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

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

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

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

GET /v1/workspaces/{workspace_id}/entities/{entity}
ServiceCall<Entity> getEntity(GetEntityOptions getEntityOptions)
getEntity(params)
get_entity(
        self,
        workspace_id: str,
        entity: str,
        *,
        export: Optional[bool] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
GetEntity(string workspaceId, string entity, bool? export = null, bool? includeAudit = null)

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.

Request

Use the GetEntityOptions.Builder to create a GetEntityOptions object that contains the parameter values for the getEntity method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

GetEntityOptions

The getEntity options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • _export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • export
    bool

    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.

    Default: false

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • export
    bool?

    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.

    Default: false

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/entities/beverage?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.GetEntity(
    workspaceId: "{workspaceId}",
    entity: "beverage"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";

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

Entity response = assistant.getEntity(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage'
};

assistant.getEntity(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.get_entity(
    workspace_id='{workspace_id}',
    entity='beverage'
).get_result()

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

Response

Response Body

Entity

Entity

Entity

Entity

Entity

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "entity": "beverage"
}
  • {
  "entity": "beverage"
}

Update entity

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

If you want to update multiple entities with a single API call, consider using the Update workspace method instead.

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

If you want to update multiple entities with a single API call, consider using the Update workspace method instead.

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

If you want to update multiple entities with a single API call, consider using the Update workspace method instead.

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

If you want to update multiple entities with a single API call, consider using the Update workspace method instead.

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

If you want to update multiple entities with a single API call, consider using the Update workspace method instead.

POST /v1/workspaces/{workspace_id}/entities/{entity}
ServiceCall<Entity> updateEntity(UpdateEntityOptions updateEntityOptions)
updateEntity(params)
update_entity(
        self,
        workspace_id: str,
        entity: str,
        *,
        new_entity: Optional[str] = None,
        new_description: Optional[str] = None,
        new_metadata: Optional[dict] = None,
        new_fuzzy_match: Optional[bool] = None,
        new_values: Optional[List['CreateValue']] = None,
        append: Optional[bool] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
UpdateEntity(string workspaceId, string entity, string newEntity = null, string newDescription = null, Dictionary<string, object> newMetadata = null, bool? newFuzzyMatch = null, List<CreateValue> newValues = null, bool? append = null, bool? includeAudit = null)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the UpdateEntityOptions.Builder to create a UpdateEntityOptions object that contains the parameter values for the updateEntity method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • append
    boolean

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

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

    Default: false

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
UpdateEntity

The updated content of the entity. Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) 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 update.

UpdateEntityOptions

The updateEntity options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • newEntity
    string

    The name of the entity. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, and hyphen characters.
    • It cannot begin with the reserved prefix sys-.

    Possible values: 1 ≤ length ≤ 64

  • newDescription
    string

    The description of the entity. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • newMetadata
    JsonObject

    Any metadata related to the entity.

  • newFuzzyMatch
    boolean

    Whether to use fuzzy matching for the entity.

  • newValues

    An array of objects describing the entity values.

  • append
    boolean

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

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

    Default: false

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • new_entity
    str

    The name of the entity. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, and hyphen characters.
    • It cannot begin with the reserved prefix sys-.

    Possible values: 1 ≤ length ≤ 64

  • new_description
    str

    The description of the entity. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • new_metadata
    dict

    Any metadata related to the entity.

  • new_fuzzy_match
    bool

    Whether to use fuzzy matching for the entity.

  • new_values

    An array of objects describing the entity values.

  • append
    bool

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

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

    Default: false

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • newEntity
    string

    The name of the entity. This string must conform to the following restrictions:

    • It can contain only Unicode alphanumeric, underscore, and hyphen characters.
    • It cannot begin with the reserved prefix sys-.

    Possible values: 1 ≤ length ≤ 64

  • newDescription
    string

    The description of the entity. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • newMetadata
    Dictionary<string, object>

    Any metadata related to the entity.

  • newFuzzyMatch
    bool?

    Whether to use fuzzy matching for the entity.

  • newValues

    An array of objects describing the entity values.

  • append
    bool?

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

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

    Default: false

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"description\":\"Liquid refreshment\"}" "{url}/v1/workspaces/{workspace_id}/entities/beverage?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.UpdateEntity(
    workspaceId: "{workspaceId}",
    entity: "beverage",
    newDescription: "Liquid refreshment"
    );

Console.WriteLine(result.Response);

entity = result.Result._Entity;
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";
String description = "Liquid refreshment";

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

Entity response = assistant.updateEntity(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage',
  newEntity: 'beverage',
  newDescription: 'Liquid refreshment'
};

assistant.updateEntity(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.update_entity(
    workspace_id='{workspace_id}',
    entity='beverage',
    new_description='Liquid refreshment'
).get_result()

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

Response

Response Body

Entity

Entity

Entity

Entity

Entity

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "entity": "beverage",
  "description": "Liquid refreshment"
}
  • {
  "entity": "beverage",
  "description": "Liquid refreshment"
}

Delete entity

Delete an entity from a workspace, or disable a system entity.

Delete an entity from a workspace, or disable a system entity.

Delete an entity from a workspace, or disable a system entity.

Delete an entity from a workspace, or disable a system entity.

Delete an entity from a workspace, or disable a system entity.

DELETE /v1/workspaces/{workspace_id}/entities/{entity}
ServiceCall<Void> deleteEntity(DeleteEntityOptions deleteEntityOptions)
deleteEntity(params)
delete_entity(
        self,
        workspace_id: str,
        entity: str,
        **kwargs,
    ) -> DetailedResponse
DeleteEntity(string workspaceId, string entity)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the DeleteEntityOptions.Builder to create a DeleteEntityOptions object that contains the parameter values for the deleteEntity method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

DeleteEntityOptions

The deleteEntity options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • curl -X DELETE -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/entities/beverage?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.DeleteEntity(
    workspaceId: "{workspaceId}",
    entity: "beverage"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";

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

assistant.deleteEntity(options).execute();
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage'
};

assistant.deleteEntity(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.delete_entity(
    workspace_id='{workspace_id}',
    entity='beverage'
).get_result()

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

Response

Response type: object

Response Body

EmptyResponse

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

No Sample Response

This method does not specify any sample responses.

List entity mentions

List mentions for a contextual entity. An entity mention is an occurrence of a contextual entity in the context of an intent user input example.

List mentions for a contextual entity. An entity mention is an occurrence of a contextual entity in the context of an intent user input example.

List mentions for a contextual entity. An entity mention is an occurrence of a contextual entity in the context of an intent user input example.

List mentions for a contextual entity. An entity mention is an occurrence of a contextual entity in the context of an intent user input example.

List mentions for a contextual entity. An entity mention is an occurrence of a contextual entity in the context of an intent user input example.

GET /v1/workspaces/{workspace_id}/entities/{entity}/mentions
ServiceCall<EntityMentionCollection> listMentions(ListMentionsOptions listMentionsOptions)
listMentions(params)
list_mentions(
        self,
        workspace_id: str,
        entity: str,
        *,
        export: Optional[bool] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
ListMentions(string workspaceId, string entity, bool? export = null, bool? includeAudit = null)

Rate limit

This operation is limited to 200 requests per 30 minutes.

Request

Use the ListMentionsOptions.Builder to create a ListMentionsOptions object that contains the parameter values for the listMentions method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

ListMentionsOptions

The listMentions options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • _export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • export
    bool

    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.

    Default: false

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • export
    bool?

    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.

    Default: false

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/entities/beverage/mentions?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.ListMentions(
    workspaceId: "{workspaceId}",
    entity: "beverage"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";

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

EntityMentionCollection response = assistant.listMentions(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage'
};

assistant.listMentions(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.list_mentions(
    workspace_id='{workspace_id}',
    entity='beverage'
).get_result()

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

Response

Response Body

EntityMentionCollection

EntityMentionCollection

EntityMentionCollection

EntityMentionCollection

EntityMentionCollection

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "examples": [
    {
      "text": "Can I get a soda?",
      "intent": "place_order",
      "location": [
        12,
        16
      ]
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/mentions?version=2021-11-27"
  }
}
  • {
  "examples": [
    {
      "text": "Can I get a soda?",
      "intent": "place_order",
      "location": [
        12,
        16
      ]
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/mentions?version=2021-11-27"
  }
}

List entity values

List the values for an entity.

List the values for an entity.

List the values for an entity.

List the values for an entity.

List the values for an entity.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values
ServiceCall<ValueCollection> listValues(ListValuesOptions listValuesOptions)
listValues(params)
list_values(
        self,
        workspace_id: str,
        entity: str,
        *,
        export: Optional[bool] = None,
        page_limit: Optional[int] = None,
        include_count: Optional[bool] = None,
        sort: Optional[str] = None,
        cursor: Optional[str] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
ListValues(string workspaceId, string entity, bool? export = null, long? pageLimit = null, bool? includeCount = null, string sort = null, string cursor = null, bool? includeAudit = null)

Rate limit

This operation is limited to 2500 requests per 30 minutes.

Request

Use the ListValuesOptions.Builder to create a ListValuesOptions object that contains the parameter values for the listValues method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • page_limit
    integer

    The number of records to return in each page of results.

    Default: 100

  • include_count
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned entity values will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [value,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

ListValuesOptions

The listValues options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • _export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • pageLimit
    number

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned entity values will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [value,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • export
    bool

    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.

    Default: false

  • page_limit
    int

    The number of records to return in each page of results.

    Default: 100

  • include_count
    bool

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    str

    The attribute by which returned entity values will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [value,updated]

  • cursor
    str

    A token identifying the page of results to retrieve.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • export
    bool?

    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.

    Default: false

  • pageLimit
    long?

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    bool?

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned entity values will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [value,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/entities/beverage/values?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.ListValues(
    workspaceId: "{workspaceId}",
    entity: "beverage"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";

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

ValueCollection response = assistant.listValues(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage'
};

assistant.listValues(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.list_values(
    workspace_id='{workspace_id}',
    entity='beverage'
).get_result()

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

Response

Response Body

ValueCollection

ValueCollection

ValueCollection

ValueCollection

ValueCollection

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "values": [
    {
      "type": "synonyms",
      "value": "orange juice"
    },
    {
      "type": "synonyms",
      "value": "soda"
    },
    {
      "type": "synonyms",
      "value": "water"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values?version=2021-11-27"
  }
}
  • {
  "values": [
    {
      "type": "synonyms",
      "value": "orange juice"
    },
    {
      "type": "synonyms",
      "value": "soda"
    },
    {
      "type": "synonyms",
      "value": "water"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values?version=2021-11-27"
  }
}

Create entity value

Create a new value for an entity.

If you want to create multiple entity values with a single API call, consider using the Update entity method instead.

Create a new value for an entity.

If you want to create multiple entity values with a single API call, consider using the Update entity method instead.

Create a new value for an entity.

If you want to create multiple entity values with a single API call, consider using the Update entity method instead.

Create a new value for an entity.

If you want to create multiple entity values with a single API call, consider using the Update entity method instead.

Create a new value for an entity.

If you want to create multiple entity values with a single API call, consider using the Update entity method instead.

POST /v1/workspaces/{workspace_id}/entities/{entity}/values
ServiceCall<Value> createValue(CreateValueOptions createValueOptions)
createValue(params)
create_value(
        self,
        workspace_id: str,
        entity: str,
        value: str,
        *,
        metadata: Optional[dict] = None,
        type: Optional[str] = None,
        synonyms: Optional[List[str]] = None,
        patterns: Optional[List[str]] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
CreateValue(string workspaceId, string entity, string value, Dictionary<string, object> metadata = null, string type = null, List<string> synonyms = null, List<string> patterns = null, bool? includeAudit = null)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the CreateValueOptions.Builder to create a CreateValueOptions object that contains the parameter values for the createValue method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
CreateValue

The new entity value.

CreateValueOptions

The createValue options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • metadata
    JsonObject

    Any metadata related to the entity value.

  • type
    string

    Specifies the type of entity value.

    Allowable values: [synonyms,patterns]

    Default: synonyms

  • synonyms
    string[]

    An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • patterns
    string[]

    An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.

    Possible values: number of items ≤ 5, 1 ≤ length ≤ 512

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • value
    Required*
    str

    The text of the entity value. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • metadata
    dict

    Any metadata related to the entity value.

  • type
    str

    Specifies the type of entity value.

    Allowable values: [synonyms,patterns]

    Default: synonyms

  • synonyms
    List[str]

    An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • patterns
    List[str]

    An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.

    Possible values: number of items ≤ 5, 1 ≤ length ≤ 512

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • metadata
    Dictionary<string, object>

    Any metadata related to the entity value.

  • type
    string

    Specifies the type of entity value.

    Allowable values: [synonyms,patterns]

    Default: synonyms

  • synonyms
    List<string>

    An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • patterns
    List<string>

    An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.

    Possible values: number of items ≤ 5, 1 ≤ length ≤ 512

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"value\":\"beer\"}" "{url}/v1/workspaces/{workspace_id}/entities/beverage/values?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.CreateValue(
    workspaceId: "{workspaceId}",
    entity: "beverage",
    value: "beer"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";
String value = "beer";

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

Value response = assistant.createValue(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage',
  value: 'beer'
};

assistant.createValue(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.create_value(
    workspace_id='{workspace_id}',
    entity='beverage',
    value='beer'
).get_result()

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

Response

Response Body

Value

Value

Value

Value

Value

Status Code

  • 201

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "type": "synonyms",
  "value": "beer"
}
  • {
  "type": "synonyms",
  "value": "beer"
}

Get entity value

Get information about an entity value.

Get information about an entity value.

Get information about an entity value.

Get information about an entity value.

Get information about an entity value.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
ServiceCall<Value> getValue(GetValueOptions getValueOptions)
getValue(params)
get_value(
        self,
        workspace_id: str,
        entity: str,
        value: str,
        *,
        export: Optional[bool] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
GetValue(string workspaceId, string entity, string value, bool? export = null, bool? includeAudit = null)

Rate limit

This operation is limited to 6000 requests per 5 minutes.

Request

Use the GetValueOptions.Builder to create a GetValueOptions object that contains the parameter values for the getValue method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

GetValueOptions

The getValue options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • _export
    boolean

    Whether to include all element content in the returned data. If export=false, the returned data includes only information about the element itself. If export=true, all content, including subelements, is included.

    Default: false

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • value
    Required*
    str

    The text of the entity value.

  • export
    bool

    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.

    Default: false

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • export
    bool?

    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.

    Default: false

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/entities/beverage/values/orange%20juice?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.GetValue(
    workspaceId: "{workspaceId}",
    entity: "beverage",
    value: "orange juice"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";
String value = "orange juice";

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

Value response = assistant.getValue(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage',
  value: 'orange juice'
};

assistant.getValue(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.get_value(
    workspace_id='{workspace_id}',
    entity='beverage',
    value='orange juice'
).get_result()

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

Response

Response Body

Value

Value

Value

Value

Value

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "type": "synonyms",
  "value": "orange juice"
}
  • {
  "type": "synonyms",
  "value": "orange juice"
}

Update entity value

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

If you want to update multiple entity values with a single API call, consider using the Update entity method instead.

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

If you want to update multiple entity values with a single API call, consider using the Update entity method instead.

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

If you want to update multiple entity values with a single API call, consider using the Update entity method instead.

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

If you want to update multiple entity values with a single API call, consider using the Update entity method instead.

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

If you want to update multiple entity values with a single API call, consider using the Update entity method instead.

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
ServiceCall<Value> updateValue(UpdateValueOptions updateValueOptions)
updateValue(params)
update_value(
        self,
        workspace_id: str,
        entity: str,
        value: str,
        *,
        new_value: Optional[str] = None,
        new_metadata: Optional[dict] = None,
        new_type: Optional[str] = None,
        new_synonyms: Optional[List[str]] = None,
        new_patterns: Optional[List[str]] = None,
        append: Optional[bool] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
UpdateValue(string workspaceId, string entity, string value, string newValue = null, Dictionary<string, object> newMetadata = null, string newType = null, List<string> newSynonyms = null, List<string> newPatterns = null, bool? append = null, bool? includeAudit = null)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the UpdateValueOptions.Builder to create a UpdateValueOptions object that contains the parameter values for the updateValue method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • append
    boolean

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

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

    Default: false

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
UpdateValue

The updated content of the entity value.

Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) 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 update.

UpdateValueOptions

The updateValue options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • newValue
    string

    The text of the entity value. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • newMetadata
    JsonObject

    Any metadata related to the entity value.

  • newType
    string

    Specifies the type of entity value.

    Allowable values: [synonyms,patterns]

    Default: synonyms

  • newSynonyms
    string[]

    An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • newPatterns
    string[]

    An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.

    Possible values: number of items ≤ 5, 1 ≤ length ≤ 512

  • append
    boolean

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

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

    Default: false

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • value
    Required*
    str

    The text of the entity value.

  • new_value
    str

    The text of the entity value. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • new_metadata
    dict

    Any metadata related to the entity value.

  • new_type
    str

    Specifies the type of entity value.

    Allowable values: [synonyms,patterns]

    Default: synonyms

  • new_synonyms
    List[str]

    An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • new_patterns
    List[str]

    An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.

    Possible values: number of items ≤ 5, 1 ≤ length ≤ 512

  • append
    bool

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

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

    Default: false

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • newValue
    string

    The text of the entity value. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • newMetadata
    Dictionary<string, object>

    Any metadata related to the entity value.

  • newType
    string

    Specifies the type of entity value.

    Allowable values: [synonyms,patterns]

    Default: synonyms

  • newSynonyms
    List<string>

    An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • newPatterns
    List<string>

    An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.

    Possible values: number of items ≤ 5, 1 ≤ length ≤ 512

  • append
    bool?

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

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

    Default: false

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"synonyms\":[\"pop\",\"soft drink\"]}" "{url}/v1/workspaces/{workspace_id}/entities/beverage/values/soda?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.UpdateValue(
    workspaceId: "{workspaceId}",
    entity: "beverage",
    value: "soda",
    newSynonyms: new List<string>()
    {
        "pop",
        "soft drink"
    }
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";
String value = "soda";

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

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

Value response = assistant.updateValue(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage',
  value: 'soda',
  newSynonyms: [
    'pop',
    'soft drink'
  ]
};

assistant.updateValue(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.update_value(
    workspace_id='{workspace_id}',
    entity='beverage',
    value='soda',
    new_synonyms=['pop', 'soft drink']
).get_result()

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

Response

Response Body

Value

Value

Value

Value

Value

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "type": "synonyms",
  "value": "soda"
}
  • {
  "type": "synonyms",
  "value": "soda"
}

Delete entity value

Delete a value from an entity.

Delete a value from an entity.

Delete a value from an entity.

Delete a value from an entity.

Delete a value from an entity.

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
ServiceCall<Void> deleteValue(DeleteValueOptions deleteValueOptions)
deleteValue(params)
delete_value(
        self,
        workspace_id: str,
        entity: str,
        value: str,
        **kwargs,
    ) -> DetailedResponse
DeleteValue(string workspaceId, string entity, string value)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the DeleteValueOptions.Builder to create a DeleteValueOptions object that contains the parameter values for the deleteValue method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

DeleteValueOptions

The deleteValue options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • value
    Required*
    str

    The text of the entity value.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • curl -X DELETE -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/entities/beverage/values/beer?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.DeleteValue(
    workspaceId: "{workspaceId}",
    entity: "beverage",
    value: "beer"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";
String value = "beer";

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

assistant.deleteValue(options).execute();
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage',
  value: 'beer'
};

assistant.deleteValue(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.delete_value(
    workspace_id='{workspace_id}',
    entity='beverage',
    value='beer'
).get_result()

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

Response

Response type: object

Response Body

EmptyResponse

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

No Sample Response

This method does not specify any sample responses.

List entity value synonyms

List the synonyms for an entity value.

List the synonyms for an entity value.

List the synonyms for an entity value.

List the synonyms for an entity value.

List the synonyms for an entity value.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms
ServiceCall<SynonymCollection> listSynonyms(ListSynonymsOptions listSynonymsOptions)
listSynonyms(params)
list_synonyms(
        self,
        workspace_id: str,
        entity: str,
        value: str,
        *,
        page_limit: Optional[int] = None,
        include_count: Optional[bool] = None,
        sort: Optional[str] = None,
        cursor: Optional[str] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
ListSynonyms(string workspaceId, string entity, string value, long? pageLimit = null, bool? includeCount = null, string sort = null, string cursor = null, bool? includeAudit = null)

Rate limit

This operation is limited to 2500 requests per 30 minutes.

Request

Use the ListSynonymsOptions.Builder to create a ListSynonymsOptions object that contains the parameter values for the listSynonyms method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • page_limit
    integer

    The number of records to return in each page of results.

    Default: 100

  • include_count
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned entity value synonyms will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [synonym,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

ListSynonymsOptions

The listSynonyms options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • pageLimit
    number

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned entity value synonyms will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [synonym,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • value
    Required*
    str

    The text of the entity value.

  • page_limit
    int

    The number of records to return in each page of results.

    Default: 100

  • include_count
    bool

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    str

    The attribute by which returned entity value synonyms will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [synonym,updated]

  • cursor
    str

    A token identifying the page of results to retrieve.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • pageLimit
    long?

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    bool?

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned entity value synonyms will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [synonym,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/entities/beverage/values/soda/synonyms?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.ListSynonyms(
    workspaceId: "{workspaceId}",
    entity: "beverage",
    value: "soda"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";
String value = "soda";

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

SynonymCollection response = assistant.listSynonyms(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage',
  value: 'soda'
};

assistant.listSynonyms(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.list_synonyms(
    workspace_id='{workspace_id}',
    entity='beverage',
    value='soda'
).get_result()

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

Response

Response Body

SynonymCollection

SynonymCollection

SynonymCollection

SynonymCollection

SynonymCollection

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "synonyms": [
    {
      "synonym": "pop"
    },
    {
      "synonym": "soft drink"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/entities/beverage/values/soda/synonyms?version=2021-11-27"
  }
}
  • {
  "synonyms": [
    {
      "synonym": "pop"
    },
    {
      "synonym": "soft drink"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/entities/beverage/values/soda/synonyms?version=2021-11-27"
  }
}

Create entity value synonym

Add a new synonym to an entity value.

If you want to create multiple synonyms with a single API call, consider using the Update entity or Update entity value method instead.

Add a new synonym to an entity value.

If you want to create multiple synonyms with a single API call, consider using the Update entity or Update entity value method instead.

Add a new synonym to an entity value.

If you want to create multiple synonyms with a single API call, consider using the Update entity or Update entity value method instead.

Add a new synonym to an entity value.

If you want to create multiple synonyms with a single API call, consider using the Update entity or Update entity value method instead.

Add a new synonym to an entity value.

If you want to create multiple synonyms with a single API call, consider using the Update entity or Update entity value method instead.

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms
ServiceCall<Synonym> createSynonym(CreateSynonymOptions createSynonymOptions)
createSynonym(params)
create_synonym(
        self,
        workspace_id: str,
        entity: str,
        value: str,
        synonym: str,
        *,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
CreateSynonym(string workspaceId, string entity, string value, string synonym, bool? includeAudit = null)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the CreateSynonymOptions.Builder to create a CreateSynonymOptions object that contains the parameter values for the createSynonym method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
Synonym

The new synonym.

CreateSynonymOptions

The createSynonym options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • synonym
    Required*
    string

    The text of the synonym. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • value
    Required*
    str

    The text of the entity value.

  • synonym
    Required*
    str

    The text of the synonym. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • synonym
    Required*
    string

    The text of the synonym. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"synonym\":\"OJ\"}" "{url}/v1/workspaces/{workspace_id}/entities/beverage/values/orange%20juice/synonyms?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.CreateSynonym(
    workspaceId: "{workspaceId}",
    entity: "beverage",
    value: "orange juice",
    synonym: "OJ"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";
String value = "orange juice";
String synonym = "OJ";

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

Synonym response = assistant.createSynonym(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage',
  value: 'orange juice',
  synonym: 'OJ'
};

assistant.createSynonym(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.create_synonym(
    workspace_id='{workspace_id}',
    entity='beverage',
    value='orange juice',
    synonym='OJ'
).get_result()

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

Response

Response Body

Synonym

Synonym

Synonym

Synonym

Synonym

Status Code

  • 201

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "synonym": "OJ"
}
  • {
  "synonym": "OJ"
}

Get entity value synonym

Get information about a synonym of an entity value.

Get information about a synonym of an entity value.

Get information about a synonym of an entity value.

Get information about a synonym of an entity value.

Get information about a synonym of an entity value.

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
ServiceCall<Synonym> getSynonym(GetSynonymOptions getSynonymOptions)
getSynonym(params)
get_synonym(
        self,
        workspace_id: str,
        entity: str,
        value: str,
        synonym: str,
        *,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
GetSynonym(string workspaceId, string entity, string value, string synonym, bool? includeAudit = null)

Rate limit

This operation is limited to 6000 requests per 5 minutes.

Request

Use the GetSynonymOptions.Builder to create a GetSynonymOptions object that contains the parameter values for the getSynonym method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • synonym
    Required*
    string

    The text of the synonym.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

GetSynonymOptions

The getSynonym options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • synonym
    Required*
    string

    The text of the synonym.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • value
    Required*
    str

    The text of the entity value.

  • synonym
    Required*
    str

    The text of the synonym.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • synonym
    Required*
    string

    The text of the synonym.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/entities/beverage/values/orange%20juice/synonyms/OJ?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.GetSynonym(
    workspaceId: "{workspaceId}",
    entity: "beverage",
    value: "orange juice",
    synonym: "OJ"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";
String value = "orange juice";
String synonym = "OJ";

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

Synonym response = assistant.getSynonym(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage',
  value: 'orange juice',
  synonym: 'OJ'
};

assistant.getSynonym(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.get_synonym(
    workspace_id='{workspace_id}',
    entity='beverage',
    value='orange juice',
    synonym='OJ'
).get_result()

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

Response

Response Body

Synonym

Synonym

Synonym

Synonym

Synonym

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "synonym": "OJ"
}
  • {
  "synonym": "OJ"
}

Update entity value synonym

Update an existing entity value synonym with new text.

If you want to update multiple synonyms with a single API call, consider using the Update entity or Update entity value method instead.

Update an existing entity value synonym with new text.

If you want to update multiple synonyms with a single API call, consider using the Update entity or Update entity value method instead.

Update an existing entity value synonym with new text.

If you want to update multiple synonyms with a single API call, consider using the Update entity or Update entity value method instead.

Update an existing entity value synonym with new text.

If you want to update multiple synonyms with a single API call, consider using the Update entity or Update entity value method instead.

Update an existing entity value synonym with new text.

If you want to update multiple synonyms with a single API call, consider using the Update entity or Update entity value method instead.

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
ServiceCall<Synonym> updateSynonym(UpdateSynonymOptions updateSynonymOptions)
updateSynonym(params)
update_synonym(
        self,
        workspace_id: str,
        entity: str,
        value: str,
        synonym: str,
        *,
        new_synonym: Optional[str] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
UpdateSynonym(string workspaceId, string entity, string value, string synonym, string newSynonym = null, bool? includeAudit = null)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the UpdateSynonymOptions.Builder to create a UpdateSynonymOptions object that contains the parameter values for the updateSynonym method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • synonym
    Required*
    string

    The text of the synonym.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
UpdateSynonym

The updated entity value synonym.

UpdateSynonymOptions

The updateSynonym options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • synonym
    Required*
    string

    The text of the synonym.

  • newSynonym
    string

    The text of the synonym. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • value
    Required*
    str

    The text of the entity value.

  • synonym
    Required*
    str

    The text of the synonym.

  • new_synonym
    str

    The text of the synonym. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • synonym
    Required*
    string

    The text of the synonym.

  • newSynonym
    string

    The text of the synonym. This string must conform to the following restrictions:

    • It cannot contain carriage return, newline, or tab characters.
    • It cannot consist of only whitespace characters.

    Possible values: 1 ≤ length ≤ 64

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"synonym\":\"O.J.\"}" "{url}/v1/workspaces/{workspace_id}/entities/beverage/values/orange%20juice/synonyms/OJ?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.UpdateSynonym(
    workspaceId: "{workspaceId}",
    entity: "beverage",
    value: "orange juice",
    synonym: "OJ",
    newSynonym: "O.J."
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";
String value = "orange juice";
String synonym = "OJ";
String newSynonym = "O.J.";

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

Synonym response = assistant.updateSynonym(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage',
  value: 'orange juice',
  synonym: 'OJ',
  newSynonym: 'O.J.'
};

assistant.updateSynonym(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.update_synonym(
    workspace_id='{workspace_id}',
    entity='beverage',
    value='orange juice',
    synonym='OJ',
    new_synonym='O.J.'
).get_result()

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

Response

Response Body

Synonym

Synonym

Synonym

Synonym

Synonym

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "synonym": "O.J."
}
  • {
  "synonym": "O.J."
}

Delete entity value synonym

Delete a synonym from an entity value.

Delete a synonym from an entity value.

Delete a synonym from an entity value.

Delete a synonym from an entity value.

Delete a synonym from an entity value.

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
ServiceCall<Void> deleteSynonym(DeleteSynonymOptions deleteSynonymOptions)
deleteSynonym(params)
delete_synonym(
        self,
        workspace_id: str,
        entity: str,
        value: str,
        synonym: str,
        **kwargs,
    ) -> DetailedResponse
DeleteSynonym(string workspaceId, string entity, string value, string synonym)

Rate limit

This operation is limited to 1000 requests per 30 minutes.

Request

Use the DeleteSynonymOptions.Builder to create a DeleteSynonymOptions object that contains the parameter values for the deleteSynonym method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • synonym
    Required*
    string

    The text of the synonym.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

DeleteSynonymOptions

The deleteSynonym options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • synonym
    Required*
    string

    The text of the synonym.

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • entity
    Required*
    str

    The name of the entity.

  • value
    Required*
    str

    The text of the entity value.

  • synonym
    Required*
    str

    The text of the synonym.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • entity
    Required*
    string

    The name of the entity.

  • value
    Required*
    string

    The text of the entity value.

  • synonym
    Required*
    string

    The text of the synonym.

  • curl -X DELETE -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/entities/beverage/values/orange%20juice/synonyms/OJ?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.DeleteSynonym(
    workspaceId: "{workspaceId}",
    entity: "beverage",
    value: "orange juice",
    synonym: "OJ"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String entityName = "beverage";
String value = "orange juice";
String synonym = "OJ";

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

assistant.deleteSynonym(options).execute();
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  entity: 'beverage',
  value: 'orange juice',
  synonym: 'OJ'
};

assistant.deleteSynonym(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.delete_synonym(
    workspace_id='{workspace_id}',
    entity='beverage',
    value='orange juice',
    synonym='OJ'
).get_result()

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

Response

Response type: object

Response Body

EmptyResponse

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

No Sample Response

This method does not specify any sample responses.

List dialog nodes

List the dialog nodes for a workspace.

List the dialog nodes for a workspace.

List the dialog nodes for a workspace.

List the dialog nodes for a workspace.

List the dialog nodes for a workspace.

GET /v1/workspaces/{workspace_id}/dialog_nodes
ServiceCall<DialogNodeCollection> listDialogNodes(ListDialogNodesOptions listDialogNodesOptions)
listDialogNodes(params)
list_dialog_nodes(
        self,
        workspace_id: str,
        *,
        page_limit: Optional[int] = None,
        include_count: Optional[bool] = None,
        sort: Optional[str] = None,
        cursor: Optional[str] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
ListDialogNodes(string workspaceId, long? pageLimit = null, bool? includeCount = null, string sort = null, string cursor = null, bool? includeAudit = null)

Rate limit

This operation is limited to 2500 requests per 30 minutes.

Request

Use the ListDialogNodesOptions.Builder to create a ListDialogNodesOptions object that contains the parameter values for the listDialogNodes method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • page_limit
    integer

    The number of records to return in each page of results.

    Default: 100

  • include_count
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned dialog nodes will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [dialog_node,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

ListDialogNodesOptions

The listDialogNodes options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • pageLimit
    number

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    boolean

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned dialog nodes will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [dialog_node,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • page_limit
    int

    The number of records to return in each page of results.

    Default: 100

  • include_count
    bool

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    str

    The attribute by which returned dialog nodes will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [dialog_node,updated]

  • cursor
    str

    A token identifying the page of results to retrieve.

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • pageLimit
    long?

    The number of records to return in each page of results.

    Default: 100

  • includeCount
    bool?

    Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is true, the pagination object in the response includes the total property.

    Default: false

  • sort
    string

    The attribute by which returned dialog nodes will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

    Allowable values: [dialog_node,updated]

  • cursor
    string

    A token identifying the page of results to retrieve.

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/dialog_nodes?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.ListDialogNodes(
    workspaceId: "{workspaceId}"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";

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

DialogNodeCollection response = assistant.listDialogNodes(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
};

assistant.listDialogNodes(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.list_dialog_nodes(
    workspace_id='{workspace_id}'
).get_result()

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

Response

Response Body

DialogNodeCollection

An array of dialog nodes.

DialogNodeCollection

An array of dialog nodes.

DialogNodeCollection

An array of dialog nodes.

DialogNodeCollection

An array of dialog nodes.

DialogNodeCollection

An array of dialog nodes.

Status Code

  • 200

    Successful request

  • 400

    Invalid request

Example responses
  • {
  "dialog_nodes": [
    {
      "type": "standard",
      "title": "Greeting",
      "output": {
        "generic": [
          {
            "values": [
              {
                "text": "Hi! How can I help you?"
              }
            ],
            "response_type": "text"
          }
        ]
      },
      "conditions": "#hello",
      "dialog_node": "node_1_1479323581900"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/dialog_nodes?version=2021-11-27"
  }
}
  • {
  "dialog_nodes": [
    {
      "type": "standard",
      "title": "Greeting",
      "output": {
        "generic": [
          {
            "values": [
              {
                "text": "Hi! How can I help you?"
              }
            ],
            "response_type": "text"
          }
        ]
      },
      "conditions": "#hello",
      "dialog_node": "node_1_1479323581900"
    }
  ],
  "pagination": {
    "refresh_url": "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/dialog_nodes?version=2021-11-27"
  }
}

Create dialog node

Create a new dialog node.

If you want to create multiple dialog nodes with a single API call, consider using the Update workspace method instead.

Create a new dialog node.

If you want to create multiple dialog nodes with a single API call, consider using the Update workspace method instead.

Create a new dialog node.

If you want to create multiple dialog nodes with a single API call, consider using the Update workspace method instead.

Create a new dialog node.

If you want to create multiple dialog nodes with a single API call, consider using the Update workspace method instead.

Create a new dialog node.

If you want to create multiple dialog nodes with a single API call, consider using the Update workspace method instead.

POST /v1/workspaces/{workspace_id}/dialog_nodes
ServiceCall<DialogNode> createDialogNode(CreateDialogNodeOptions createDialogNodeOptions)
createDialogNode(params)
create_dialog_node(
        self,
        workspace_id: str,
        dialog_node: str,
        *,
        description: Optional[str] = None,
        conditions: Optional[str] = None,
        parent: Optional[str] = None,
        previous_sibling: Optional[str] = None,
        output: Optional['DialogNodeOutput'] = None,
        context: Optional['DialogNodeContext'] = None,
        metadata: Optional[dict] = None,
        next_step: Optional['DialogNodeNextStep'] = None,
        title: Optional[str] = None,
        type: Optional[str] = None,
        event_name: Optional[str] = None,
        variable: Optional[str] = None,
        actions: Optional[List['DialogNodeAction']] = None,
        digress_in: Optional[str] = None,
        digress_out: Optional[str] = None,
        digress_out_slots: Optional[str] = None,
        user_label: Optional[str] = None,
        disambiguation_opt_out: Optional[bool] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
CreateDialogNode(string workspaceId, string dialogNode, string description = null, string conditions = null, string parent = null, string previousSibling = null, DialogNodeOutput output = null, DialogNodeContext context = null, Dictionary<string, object> metadata = null, DialogNodeNextStep nextStep = null, string title = null, string type = null, string eventName = null, string variable = null, List<DialogNodeAction> actions = null, string digressIn = null, string digressOut = null, string digressOutSlots = null, string userLabel = null, bool? disambiguationOptOut = null, bool? includeAudit = null)

Rate limit

This operation is limited to 500 requests per 30 minutes.

Request

Use the CreateDialogNodeOptions.Builder to create a CreateDialogNodeOptions object that contains the parameter values for the createDialogNode method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
DialogNode

A CreateDialogNode object defining the content of the new dialog node.

CreateDialogNodeOptions

The createDialogNode options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • dialogNode
    Required*
    string

    The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 1024

  • description
    string

    The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • conditions
    string

    The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 2048

  • parent
    string

    The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.

  • previousSibling
    string

    The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.

  • output

    The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

  • context

    The context for the dialog node.

  • metadata
    JsonObject

    The metadata for the dialog node.

  • nextStep

    The next step to execute following this dialog node.

  • title
    string

    A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the suggestion response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the connect_to_agent response type.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 512

  • type
    string

    How the dialog node is processed.

    Allowable values: [standard,event_handler,frame,slot,response_condition,folder]

  • eventName
    string

    How an event_handler node is processed.

    Allowable values: [focus,input,filled,validate,filled_multiple,generic,nomatch,nomatch_responses_depleted,digression_return_prompt]

  • variable
    string

    The location in the dialog context where output is stored.

  • actions

    An array of objects describing any actions to be invoked by the dialog node.

    Possible values: number of items ≤ 5

  • digressIn
    string

    Whether this top-level dialog node can be digressed into.

    Allowable values: [not_available,returns,does_not_return]

  • digressOut
    string

    Whether this dialog node can be returned to after a digression.

    Allowable values: [allow_returning,allow_all,allow_all_never_return]

  • digressOutSlots
    string

    Whether the user can digress to top-level nodes while filling out slots.

    Allowable values: [not_allowed,allow_returning,allow_all]

  • userLabel
    string

    A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).

    Possible values: 1 ≤ length ≤ 512

  • disambiguationOptOut
    boolean

    Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=standard or frame.

    Default: false

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • dialog_node
    Required*
    str

    The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 1024

  • description
    str

    The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • conditions
    str

    The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 2048

  • parent
    str

    The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.

  • previous_sibling
    str

    The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.

  • output

    The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

  • context

    The context for the dialog node.

  • metadata
    dict

    The metadata for the dialog node.

  • next_step

    The next step to execute following this dialog node.

  • title
    str

    A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the suggestion response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the connect_to_agent response type.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 512

  • type
    str

    How the dialog node is processed.

    Allowable values: [standard,event_handler,frame,slot,response_condition,folder]

  • event_name
    str

    How an event_handler node is processed.

    Allowable values: [focus,input,filled,validate,filled_multiple,generic,nomatch,nomatch_responses_depleted,digression_return_prompt]

  • variable
    str

    The location in the dialog context where output is stored.

  • actions

    An array of objects describing any actions to be invoked by the dialog node.

    Possible values: number of items ≤ 5

  • digress_in
    str

    Whether this top-level dialog node can be digressed into.

    Allowable values: [not_available,returns,does_not_return]

  • digress_out
    str

    Whether this dialog node can be returned to after a digression.

    Allowable values: [allow_returning,allow_all,allow_all_never_return]

  • digress_out_slots
    str

    Whether the user can digress to top-level nodes while filling out slots.

    Allowable values: [not_allowed,allow_returning,allow_all]

  • user_label
    str

    A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).

    Possible values: 1 ≤ length ≤ 512

  • disambiguation_opt_out
    bool

    Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=standard or frame.

    Default: false

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • dialogNode
    Required*
    string

    The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 1024

  • description
    string

    The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • conditions
    string

    The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 2048

  • parent
    string

    The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.

  • previousSibling
    string

    The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.

  • output

    The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

  • context

    The context for the dialog node.

  • metadata
    Dictionary<string, object>

    The metadata for the dialog node.

  • nextStep

    The next step to execute following this dialog node.

  • title
    string

    A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the suggestion response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the connect_to_agent response type.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 512

  • type
    string

    How the dialog node is processed.

    Allowable values: [standard,event_handler,frame,slot,response_condition,folder]

  • eventName
    string

    How an event_handler node is processed.

    Allowable values: [focus,input,filled,validate,filled_multiple,generic,nomatch,nomatch_responses_depleted,digression_return_prompt]

  • variable
    string

    The location in the dialog context where output is stored.

  • actions

    An array of objects describing any actions to be invoked by the dialog node.

    Possible values: number of items ≤ 5

  • digressIn
    string

    Whether this top-level dialog node can be digressed into.

    Allowable values: [not_available,returns,does_not_return]

  • digressOut
    string

    Whether this dialog node can be returned to after a digression.

    Allowable values: [allow_returning,allow_all,allow_all_never_return]

  • digressOutSlots
    string

    Whether the user can digress to top-level nodes while filling out slots.

    Allowable values: [not_allowed,allow_returning,allow_all]

  • userLabel
    string

    A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).

    Possible values: 1 ≤ length ≤ 512

  • disambiguationOptOut
    bool?

    Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=standard or frame.

    Default: false

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"dialog_node\": \"greeting\",\"conditions\":\"#hello\",\"output\":{\"generic\":[{\"response_type\":\"text\",\"values\":[{\"text\":\"Hi! How can I help you?\"}]}]},\"title\":\"Greeting\"}" "{url}/v1/workspaces/{workspace_id}/dialog_nodes?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.CreateDialogNode(
    workspaceId: "{workspaceId}",
    dialogNode: "greeting"
    conditions: "#hello"
    title: "Greeting"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String dialogNode = "greeting";
String conditions = "#hello";
String title = "Greeting";

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

DialogNode response = assistant.createDialogNode(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  dialogNode: 'greeting',
  conditions: '#hello',
  title: 'Greeting'
};

assistant.createDialogNode(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.create_dialog_node(
    workspace_id='{workspace_id}',
    dialog_node='greeting',
    conditions='#hello',
    title='Greeting'
).get_result()

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

Response

Response Body

DialogNode

DialogNode

DialogNode

DialogNode

DialogNode

Status Code

  • 201

    Successful request

  • 400

    Invalid request

Example responses
  • {
  "type": "standard",
  "title": "Greeting",
  "conditions": "#hello",
  "dialog_node": "node_1_1479323581900"
}
  • {
  "type": "standard",
  "title": "Greeting",
  "conditions": "#hello",
  "dialog_node": "node_1_1479323581900"
}

Get dialog node

Get information about a dialog node.

Get information about a dialog node.

Get information about a dialog node.

Get information about a dialog node.

Get information about a dialog node.

GET /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}
ServiceCall<DialogNode> getDialogNode(GetDialogNodeOptions getDialogNodeOptions)
getDialogNode(params)
get_dialog_node(
        self,
        workspace_id: str,
        dialog_node: str,
        *,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
GetDialogNode(string workspaceId, string dialogNode, bool? includeAudit = null)

Rate limit

This operation is limited to 6000 requests per 5 minutes.

Request

Use the GetDialogNodeOptions.Builder to create a GetDialogNodeOptions object that contains the parameter values for the getDialogNode method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • dialog_node
    Required*
    string

    The dialog node ID (for example, node_1_1479323581900).

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

GetDialogNodeOptions

The getDialogNode options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • dialogNode
    Required*
    string

    The dialog node ID (for example, node_1_1479323581900).

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • dialog_node
    Required*
    str

    The dialog node ID (for example, node_1_1479323581900).

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • dialogNode
    Required*
    string

    The dialog node ID (for example, node_1_1479323581900).

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/dialog_nodes/greeting?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.GetDialogNode(
    workspaceId: "{workspaceId}",
    dialogNode: "greeting"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String dialogNode = "greeting";

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

DialogNode response = assistant.getDialogNode(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  dialogNode: 'greeting'
};

assistant.getDialogNode(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.get_dialog_node(
    workspace_id='{workspace_id}',
    dialog_node='greeting'
).get_result()

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

Response

Response Body

DialogNode

DialogNode

DialogNode

DialogNode

DialogNode

Status Code

  • 200

    Successful request

  • 400

    Invalid request

Example responses
  • {
  "type": "standard",
  "title": "Greeting",
  "conditions": "#hello",
  "dialog_node": "node_1_1479323581900"
}
  • {
  "type": "standard",
  "title": "Greeting",
  "conditions": "#hello",
  "dialog_node": "node_1_1479323581900"
}

Update dialog node

Update an existing dialog node with new or modified data.

If you want to update multiple dialog nodes with a single API call, consider using the Update workspace method instead.

Update an existing dialog node with new or modified data.

If you want to update multiple dialog nodes with a single API call, consider using the Update workspace method instead.

Update an existing dialog node with new or modified data.

If you want to update multiple dialog nodes with a single API call, consider using the Update workspace method instead.

Update an existing dialog node with new or modified data.

If you want to update multiple dialog nodes with a single API call, consider using the Update workspace method instead.

Update an existing dialog node with new or modified data.

If you want to update multiple dialog nodes with a single API call, consider using the Update workspace method instead.

POST /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}
ServiceCall<DialogNode> updateDialogNode(UpdateDialogNodeOptions updateDialogNodeOptions)
updateDialogNode(params)
update_dialog_node(
        self,
        workspace_id: str,
        dialog_node: str,
        *,
        new_dialog_node: Optional[str] = None,
        new_description: Optional[str] = None,
        new_conditions: Optional[str] = None,
        new_parent: Optional[str] = None,
        new_previous_sibling: Optional[str] = None,
        new_output: Optional['DialogNodeOutput'] = None,
        new_context: Optional['DialogNodeContext'] = None,
        new_metadata: Optional[dict] = None,
        new_next_step: Optional['DialogNodeNextStep'] = None,
        new_title: Optional[str] = None,
        new_type: Optional[str] = None,
        new_event_name: Optional[str] = None,
        new_variable: Optional[str] = None,
        new_actions: Optional[List['DialogNodeAction']] = None,
        new_digress_in: Optional[str] = None,
        new_digress_out: Optional[str] = None,
        new_digress_out_slots: Optional[str] = None,
        new_user_label: Optional[str] = None,
        new_disambiguation_opt_out: Optional[bool] = None,
        include_audit: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
UpdateDialogNode(string workspaceId, string dialogNode, string newDialogNode = null, string newDescription = null, string newConditions = null, string newParent = null, string newPreviousSibling = null, DialogNodeOutput newOutput = null, DialogNodeContext newContext = null, Dictionary<string, object> newMetadata = null, DialogNodeNextStep newNextStep = null, string newTitle = null, string newType = null, string newEventName = null, string newVariable = null, List<DialogNodeAction> newActions = null, string newDigressIn = null, string newDigressOut = null, string newDigressOutSlots = null, string newUserLabel = null, bool? newDisambiguationOptOut = null, bool? includeAudit = null)

Rate limit

his operation is limited to 500 requests per 30 minutes.

Request

Use the UpdateDialogNodeOptions.Builder to create a UpdateDialogNodeOptions object that contains the parameter values for the updateDialogNode method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • dialog_node
    Required*
    string

    The dialog node ID (for example, node_1_1479323581900).

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • include_audit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

Request Body

Required*
UpdateDialogNode

The updated content of the dialog node.

Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) For example, if you update the actions for a dialog node, the previously existing actions are discarded and replaced with the new actions specified in the update.

UpdateDialogNodeOptions

The updateDialogNode options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • dialogNode
    Required*
    string

    The dialog node ID (for example, node_1_1479323581900).

  • newDialogNode
    string

    The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 1024

  • newDescription
    string

    The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • newConditions
    string

    The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 2048

  • newParent
    string

    The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.

  • newPreviousSibling
    string

    The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.

  • newOutput

    The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

  • newContext

    The context for the dialog node.

  • newMetadata
    JsonObject

    The metadata for the dialog node.

  • newNextStep

    The next step to execute following this dialog node.

  • newTitle
    string

    A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the suggestion response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the connect_to_agent response type.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 512

  • newType
    string

    How the dialog node is processed.

    Allowable values: [standard,event_handler,frame,slot,response_condition,folder]

  • newEventName
    string

    How an event_handler node is processed.

    Allowable values: [focus,input,filled,validate,filled_multiple,generic,nomatch,nomatch_responses_depleted,digression_return_prompt]

  • newVariable
    string

    The location in the dialog context where output is stored.

  • newActions

    An array of objects describing any actions to be invoked by the dialog node.

    Possible values: number of items ≤ 5

  • newDigressIn
    string

    Whether this top-level dialog node can be digressed into.

    Allowable values: [not_available,returns,does_not_return]

  • newDigressOut
    string

    Whether this dialog node can be returned to after a digression.

    Allowable values: [allow_returning,allow_all,allow_all_never_return]

  • newDigressOutSlots
    string

    Whether the user can digress to top-level nodes while filling out slots.

    Allowable values: [not_allowed,allow_returning,allow_all]

  • newUserLabel
    string

    A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).

    Possible values: 1 ≤ length ≤ 512

  • newDisambiguationOptOut
    boolean

    Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=standard or frame.

    Default: false

  • includeAudit
    boolean

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • dialog_node
    Required*
    str

    The dialog node ID (for example, node_1_1479323581900).

  • new_dialog_node
    str

    The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 1024

  • new_description
    str

    The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • new_conditions
    str

    The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 2048

  • new_parent
    str

    The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.

  • new_previous_sibling
    str

    The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.

  • new_output

    The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

  • new_context

    The context for the dialog node.

  • new_metadata
    dict

    The metadata for the dialog node.

  • new_next_step

    The next step to execute following this dialog node.

  • new_title
    str

    A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the suggestion response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the connect_to_agent response type.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 512

  • new_type
    str

    How the dialog node is processed.

    Allowable values: [standard,event_handler,frame,slot,response_condition,folder]

  • new_event_name
    str

    How an event_handler node is processed.

    Allowable values: [focus,input,filled,validate,filled_multiple,generic,nomatch,nomatch_responses_depleted,digression_return_prompt]

  • new_variable
    str

    The location in the dialog context where output is stored.

  • new_actions

    An array of objects describing any actions to be invoked by the dialog node.

    Possible values: number of items ≤ 5

  • new_digress_in
    str

    Whether this top-level dialog node can be digressed into.

    Allowable values: [not_available,returns,does_not_return]

  • new_digress_out
    str

    Whether this dialog node can be returned to after a digression.

    Allowable values: [allow_returning,allow_all,allow_all_never_return]

  • new_digress_out_slots
    str

    Whether the user can digress to top-level nodes while filling out slots.

    Allowable values: [not_allowed,allow_returning,allow_all]

  • new_user_label
    str

    A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).

    Possible values: 1 ≤ length ≤ 512

  • new_disambiguation_opt_out
    bool

    Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=standard or frame.

    Default: false

  • include_audit
    bool

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • dialogNode
    Required*
    string

    The dialog node ID (for example, node_1_1479323581900).

  • newDialogNode
    string

    The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 1024

  • newDescription
    string

    The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 128

  • newConditions
    string

    The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.

    Possible values: 1 ≤ length ≤ 2048

  • newParent
    string

    The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.

  • newPreviousSibling
    string

    The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.

  • newOutput

    The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

  • newContext

    The context for the dialog node.

  • newMetadata
    Dictionary<string, object>

    The metadata for the dialog node.

  • newNextStep

    The next step to execute following this dialog node.

  • newTitle
    string

    A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the suggestion response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the connect_to_agent response type.

    This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

    Possible values: 1 ≤ length ≤ 512

  • newType
    string

    How the dialog node is processed.

    Allowable values: [standard,event_handler,frame,slot,response_condition,folder]

  • newEventName
    string

    How an event_handler node is processed.

    Allowable values: [focus,input,filled,validate,filled_multiple,generic,nomatch,nomatch_responses_depleted,digression_return_prompt]

  • newVariable
    string

    The location in the dialog context where output is stored.

  • newActions

    An array of objects describing any actions to be invoked by the dialog node.

    Possible values: number of items ≤ 5

  • newDigressIn
    string

    Whether this top-level dialog node can be digressed into.

    Allowable values: [not_available,returns,does_not_return]

  • newDigressOut
    string

    Whether this dialog node can be returned to after a digression.

    Allowable values: [allow_returning,allow_all,allow_all_never_return]

  • newDigressOutSlots
    string

    Whether the user can digress to top-level nodes while filling out slots.

    Allowable values: [not_allowed,allow_returning,allow_all]

  • newUserLabel
    string

    A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).

    Possible values: 1 ≤ length ≤ 512

  • newDisambiguationOptOut
    bool?

    Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=standard or frame.

    Default: false

  • includeAudit
    bool?

    Whether to include the audit properties (created and updated timestamps) in the response.

    Default: false

  • curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"output\":{\"generic\":[{\"response_type\":\"text\",\"values\":[{\"text\":\"Hello! What can I do for you?\"}]}]}}" "{url}/v1/workspaces/{workspace_id}/dialog_nodes/greeting?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.UpdateDialogNode(
    workspaceId: "{workspaceId}",
    dialogNode: "greeting",
    newOutput: new DialogNodeOutput()
    {
        Generic = new List<DialogNodeOutputGeneric>()
        {
            new DialogNodeOutputGeneric()
            {
                ResponseType = "text",
                Values = new List<DialogNodeOutputTextValuesElement>()
                {
                    new DialogNodeOutputTextValuesElement()
                    {
                        Text = "Hello! What can I do for you?"
                    }
                }
            }
        }
    }
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String dialogNode = "greeting";

List<DialogNodeOutputTextValuesElement> newValues = new ArrayList<>();
DialogNodeOutputTextValuesElement newText = new DialogNodeOutputTextValuesElement();
newText.setText("Hello! What can I do for you?");
newValues.add(newText);

List<DialogNodeOutputGeneric> newGeneric = new ArrayList<>();
DialogNodeOutputGeneric newGenericResponse = new DialogNodeOutputGeneric();
newGenericResponse.setResponseType(DialogNodeOutputGeneric.ResponseType.TEXT);
newGenericResponse.setValues(newValues);
newGeneric.add(newGenericResponse);

DialogNodeOutput newOutput = new DialogNodeOutput();
newOutput.setGeneric(newGeneric);

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

DialogNode response = assistant.updateDialogNode(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  dialogNode: 'greeting',
  newOutput: {
    generic: [
      {
        response_type: 'text',
        values: [
          {
            text: 'Hello! What can I do for you?'
          }
        ]
      }
    ],
  title: 'Greeting'
  }
};

assistant.updateDialogNode(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.update_dialog_node(
    workspace_id='{workspace_id}',
    dialog_node='greeting',
    new_output={
        'generic': [
            {
                'response_type': 'text',
                'values': [
                    {
                        'text': 'Hello! What can I do for you?'
                    }
                ]
            }
        ]
    }
).get_result()

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

Response

Response Body

DialogNode

DialogNode

DialogNode

DialogNode

DialogNode

Status Code

  • 200

    Successful request

  • 400

    Invalid request

Example responses
  • {
  "type": "standard",
  "title": "Greeting",
  "output": {
    "generic": [
      {
        "values": [
          {
            "text": "Hello! What can I do for you?"
          }
        ],
        "response_type": "text"
      }
    ]
  },
  "conditions": "#hello",
  "dialog_node": "node_1_1479323581900"
}
  • {
  "type": "standard",
  "title": "Greeting",
  "output": {
    "generic": [
      {
        "values": [
          {
            "text": "Hello! What can I do for you?"
          }
        ],
        "response_type": "text"
      }
    ]
  },
  "conditions": "#hello",
  "dialog_node": "node_1_1479323581900"
}

Delete dialog node

Delete a dialog node from a workspace.

Delete a dialog node from a workspace.

Delete a dialog node from a workspace.

Delete a dialog node from a workspace.

Delete a dialog node from a workspace.

DELETE /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}
ServiceCall<Void> deleteDialogNode(DeleteDialogNodeOptions deleteDialogNodeOptions)
deleteDialogNode(params)
delete_dialog_node(
        self,
        workspace_id: str,
        dialog_node: str,
        **kwargs,
    ) -> DetailedResponse
DeleteDialogNode(string workspaceId, string dialogNode)

Rate limit

This operation is limited to 500 requests per 30 minutes.

Request

Use the DeleteDialogNodeOptions.Builder to create a DeleteDialogNodeOptions object that contains the parameter values for the deleteDialogNode method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

  • dialog_node
    Required*
    string

    The dialog node ID (for example, node_1_1479323581900).

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

DeleteDialogNodeOptions

The deleteDialogNode options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • dialogNode
    Required*
    string

    The dialog node ID (for example, node_1_1479323581900).

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • dialog_node
    Required*
    str

    The dialog node ID (for example, node_1_1479323581900).

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • dialogNode
    Required*
    string

    The dialog node ID (for example, node_1_1479323581900).

  • curl -X DELETE -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/dialog_nodes/greeting?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.DeleteDialogNode(
    workspaceId: "{workspaceId}",
    dialogNode: "greeting"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";
String dialogNode = "greeting";

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

assistant.deleteDialogNode(options).execute();
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}',
  dialogNode: 'greeting'
};

assistant.deleteDialogNode(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.delete_dialog_node(
    workspace_id='{workspace_id}',
    dialog_node='greeting'
).get_result()

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

Response

Response type: object

Response Body

EmptyResponse

Status Code

  • 200

    Successful request

  • 400

    Invalid request

No Sample Response

This method does not specify any sample responses.

List log events in a workspace

List the events from the log of a specific workspace.

This method requires Manager access.

Note: If you use the cursor parameter to retrieve results one page at a time, subsequent requests must be no more than 5 minutes apart. Any returned value for the cursor parameter becomes invalid after 5 minutes. For more information about using pagination, see Pagination.

List the events from the log of a specific workspace.

This method requires Manager access.

Note: If you use the cursor parameter to retrieve results one page at a time, subsequent requests must be no more than 5 minutes apart. Any returned value for the cursor parameter becomes invalid after 5 minutes. For more information about using pagination, see Pagination.

List the events from the log of a specific workspace.

This method requires Manager access.

Note: If you use the cursor parameter to retrieve results one page at a time, subsequent requests must be no more than 5 minutes apart. Any returned value for the cursor parameter becomes invalid after 5 minutes. For more information about using pagination, see Pagination.

List the events from the log of a specific workspace.

This method requires Manager access.

Note: If you use the cursor parameter to retrieve results one page at a time, subsequent requests must be no more than 5 minutes apart. Any returned value for the cursor parameter becomes invalid after 5 minutes. For more information about using pagination, see Pagination.

List the events from the log of a specific workspace.

This method requires Manager access.

Note: If you use the cursor parameter to retrieve results one page at a time, subsequent requests must be no more than 5 minutes apart. Any returned value for the cursor parameter becomes invalid after 5 minutes. For more information about using pagination, see Pagination.

GET /v1/workspaces/{workspace_id}/logs
ServiceCall<LogCollection> listLogs(ListLogsOptions listLogsOptions)
listLogs(params)
list_logs(
        self,
        workspace_id: str,
        *,
        sort: Optional[str] = None,
        filter: Optional[str] = None,
        page_limit: Optional[int] = None,
        cursor: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
ListLogs(string workspaceId, string sort = null, string filter = null, long? pageLimit = null, string cursor = null)

Rate limit

If cursor is not specified, this operation is limited to 40 requests per 30 minutes. If cursor is specified, the limit is 120 requests per minute.

Request

Use the ListLogsOptions.Builder to create a ListLogsOptions object that contains the parameter values for the listLogs method.

Path Parameters

  • workspace_id
    Required*
    string

    Unique identifier of the workspace.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • sort
    string

    How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-).

  • filter
    string

    A cacheable parameter that limits the results to those matching the specified filter. For more information, see the documentation.

  • page_limit
    integer

    The number of records to return in each page of results.

    Note: If the API is not returning your data, try lowering the page_limit value.

    Default: 100

  • cursor
    string

    A token identifying the page of results to retrieve.

ListLogsOptions

The listLogs options.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • sort
    string

    How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-).

  • filter
    string

    A cacheable parameter that limits the results to those matching the specified filter. For more information, see the documentation.

  • pageLimit
    number

    The number of records to return in each page of results.

    Note: If the API is not returning your data, try lowering the page_limit value.

    Default: 100

  • cursor
    string

    A token identifying the page of results to retrieve.

parameters

  • workspace_id
    Required*
    str

    Unique identifier of the workspace.

  • sort
    str

    How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-).

  • filter
    str

    A cacheable parameter that limits the results to those matching the specified filter. For more information, see the documentation.

  • page_limit
    int

    The number of records to return in each page of results.

    Note: If the API is not returning your data, try lowering the page_limit value.

    Default: 100

  • cursor
    str

    A token identifying the page of results to retrieve.

parameters

  • workspaceId
    Required*
    string

    Unique identifier of the workspace.

  • sort
    string

    How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-).

  • filter
    string

    A cacheable parameter that limits the results to those matching the specified filter. For more information, see the documentation.

  • pageLimit
    long?

    The number of records to return in each page of results.

    Note: If the API is not returning your data, try lowering the page_limit value.

    Default: 100

  • cursor
    string

    A token identifying the page of results to retrieve.

  • curl -u "apikey:{apikey}" "{url}/v1/workspaces/{workspace_id}/logs?version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.ListLogs(
    workspaceId: "{workspaceId}"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String workspaceId = "{workspace_id}";

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

LogCollection response = assistant.listLogs(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  workspaceId: '{workspace_id}'
};

assistant.listLogs(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.list_logs(
    workspace_id='{workspace_id}'
).get_result()

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

Response

Response Body

LogCollection

LogCollection

LogCollection

LogCollection

LogCollection

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

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

List log events in all workspaces

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

Note: If you use the cursor parameter to retrieve results one page at a time, subsequent requests must be no more than 5 minutes apart. Any returned value for the cursor parameter becomes invalid after 5 minutes. For more information about using pagination, see Pagination.

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

Note: If you use the cursor parameter to retrieve results one page at a time, subsequent requests must be no more than 5 minutes apart. Any returned value for the cursor parameter becomes invalid after 5 minutes. For more information about using pagination, see Pagination.

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

Note: If you use the cursor parameter to retrieve results one page at a time, subsequent requests must be no more than 5 minutes apart. Any returned value for the cursor parameter becomes invalid after 5 minutes. For more information about using pagination, see Pagination.

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

Note: If you use the cursor parameter to retrieve results one page at a time, subsequent requests must be no more than 5 minutes apart. Any returned value for the cursor parameter becomes invalid after 5 minutes. For more information about using pagination, see Pagination.

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

Note: If you use the cursor parameter to retrieve results one page at a time, subsequent requests must be no more than 5 minutes apart. Any returned value for the cursor parameter becomes invalid after 5 minutes. For more information about using pagination, see Pagination.

GET /v1/logs
ServiceCall<LogCollection> listAllLogs(ListAllLogsOptions listAllLogsOptions)
listAllLogs(params)
list_all_logs(
        self,
        filter: str,
        *,
        sort: Optional[str] = None,
        page_limit: Optional[int] = None,
        cursor: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
ListAllLogs(string filter, string sort = null, long? pageLimit = null, string cursor = null)

Rate limit

If cursor is not specified, this operation is limited to 40 requests per 30 minutes. If cursor is specified, the limit is 120 requests per minute.

Request

Use the ListAllLogsOptions.Builder to create a ListAllLogsOptions object that contains the parameter values for the listAllLogs method.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • filter
    Required*
    string

    A cacheable parameter that limits the results to those matching the specified filter. You must specify a filter query that includes a value for language, as well as a value for request.context.system.assistant_id, workspace_id, or request.context.metadata.deployment. These required filters must be specified using the exact match (::) operator. For more information, see the documentation.

  • sort
    string

    How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-).

  • page_limit
    integer

    The number of records to return in each page of results.

    Default: 100

  • cursor
    string

    A token identifying the page of results to retrieve.

ListAllLogsOptions

The listAllLogs options.

parameters

  • filter
    Required*
    string

    A cacheable parameter that limits the results to those matching the specified filter. You must specify a filter query that includes a value for language, as well as a value for request.context.system.assistant_id, workspace_id, or request.context.metadata.deployment. These required filters must be specified using the exact match (::) operator. For more information, see the documentation.

  • sort
    string

    How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-).

  • pageLimit
    number

    The number of records to return in each page of results.

    Default: 100

  • cursor
    string

    A token identifying the page of results to retrieve.

parameters

  • filter
    Required*
    str

    A cacheable parameter that limits the results to those matching the specified filter. You must specify a filter query that includes a value for language, as well as a value for request.context.system.assistant_id, workspace_id, or request.context.metadata.deployment. These required filters must be specified using the exact match (::) operator. For more information, see the documentation.

  • sort
    str

    How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-).

  • page_limit
    int

    The number of records to return in each page of results.

    Default: 100

  • cursor
    str

    A token identifying the page of results to retrieve.

parameters

  • filter
    Required*
    string

    A cacheable parameter that limits the results to those matching the specified filter. You must specify a filter query that includes a value for language, as well as a value for request.context.system.assistant_id, workspace_id, or request.context.metadata.deployment. These required filters must be specified using the exact match (::) operator. For more information, see the documentation.

  • sort
    string

    How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-).

  • pageLimit
    long?

    The number of records to return in each page of results.

    Default: 100

  • cursor
    string

    A token identifying the page of results to retrieve.

  • curl -u "apikey:{apikey}" "{url}/v1/logs?version=2021-06-14&filter=(language::en,request.context.metadata.deployment::testDeployment)"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.ListAllLogs(
    filter: "language::en,request.context.metadata.deployment::testDeployment"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String filter = "language::en,request.context.metadata.deployment::testDeployment";

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

LogCollection response = assistant.listAllLogs(options).execute().getResult();

System.out.println(response);
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

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

assistant.listAllLogs(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response=assistant.list_all_logs(
    filter='language::en,request.context.metadata.deployment::testDeployment'
).get_result()

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

Response

Response Body

LogCollection

LogCollection

LogCollection

LogCollection

LogCollection

Status Code

  • 200

    Successful request.

  • 400

    Invalid request.

Example responses
  • {
  "logs": [
    {
      "request": {
        "input": {
          "text": "Good morning"
        },
        "context": {
          "metadata": {
            "deployment": "deployment_1"
          }
        }
      },
      "response": {
        "intents": [
          {
            "intent": "hello",
            "confidence": 1
          }
        ],
        "entities": [],
        "input": {
          "text": "Good morning"
        },
        "output": {
          "text": [
            "Hi! What can I do for you?"
          ],
          "nodes_visited": [
            "node_2_1501875253968"
          ],
          "log_messages": []
        },
        "context": {
          "metadata": {
            "deployment": "testDeployment"
          },
          "conversation_id": "81a43b48-7dca-4a7d-a0d7-6fed03fcee69",
          "system": {
            "dialog_stack": [
              {
                "dialog_node": "root"
              }
            ],
            "dialog_turn_counter": 1,
            "dialog_request_counter": 1,
            "_node_output_map": {
              "node_2_1501875253968": [
                0
              ]
            },
            "branch_exited": true,
            "branch_exited_reason": "completed"
          }
        }
      },
      "language": "en",
      "workspace_id": "{workspace_id}",
      "request_timestamp": "2017-09-13T19:52:32.611Z",
      "response_timestamp": "2017-09-13T19:52:32.628Z",
      "log_id": "aa886a8a-bac5-4b91-8323-2fd61a69c9d3"
    }
  ],
  "pagination": {}
}
  • {
  "logs": [
    {
      "request": {
        "input": {
          "text": "Good morning"
        },
        "context": {
          "metadata": {
            "deployment": "deployment_1"
          }
        }
      },
      "response": {
        "intents": [
          {
            "intent": "hello",
            "confidence": 1
          }
        ],
        "entities": [],
        "input": {
          "text": "Good morning"
        },
        "output": {
          "text": [
            "Hi! What can I do for you?"
          ],
          "nodes_visited": [
            "node_2_1501875253968"
          ],
          "log_messages": []
        },
        "context": {
          "metadata": {
            "deployment": "testDeployment"
          },
          "conversation_id": "81a43b48-7dca-4a7d-a0d7-6fed03fcee69",
          "system": {
            "dialog_stack": [
              {
                "dialog_node": "root"
              }
            ],
            "dialog_turn_counter": 1,
            "dialog_request_counter": 1,
            "_node_output_map": {
              "node_2_1501875253968": [
                0
              ]
            },
            "branch_exited": true,
            "branch_exited_reason": "completed"
          }
        }
      },
      "language": "en",
      "workspace_id": "{workspace_id}",
      "request_timestamp": "2017-09-13T19:52:32.611Z",
      "response_timestamp": "2017-09-13T19:52:32.628Z",
      "log_id": "aa886a8a-bac5-4b91-8323-2fd61a69c9d3"
    }
  ],
  "pagination": {}
}

Delete labeled data

Deletes all data associated with a specified customer ID. The method has no effect if no data is associated with the customer ID.

You associate a customer ID with data by passing the X-Watson-Metadata header with a request that passes data. For more information about personal data and customer IDs, see Information security.

Note: This operation is intended only for deleting data associated with a single specific customer, not for deleting data associated with multiple customers or for any other purpose. For more information, see Labeling and deleting data in Watson Assistant.

Deletes all data associated with a specified customer ID. The method has no effect if no data is associated with the customer ID.

You associate a customer ID with data by passing the X-Watson-Metadata header with a request that passes data. For more information about personal data and customer IDs, see Information security.

Note: This operation is intended only for deleting data associated with a single specific customer, not for deleting data associated with multiple customers or for any other purpose. For more information, see Labeling and deleting data in Watson Assistant.

Deletes all data associated with a specified customer ID. The method has no effect if no data is associated with the customer ID.

You associate a customer ID with data by passing the X-Watson-Metadata header with a request that passes data. For more information about personal data and customer IDs, see Information security.

Note: This operation is intended only for deleting data associated with a single specific customer, not for deleting data associated with multiple customers or for any other purpose. For more information, see Labeling and deleting data in Watson Assistant.

Deletes all data associated with a specified customer ID. The method has no effect if no data is associated with the customer ID.

You associate a customer ID with data by passing the X-Watson-Metadata header with a request that passes data. For more information about personal data and customer IDs, see Information security.

Note: This operation is intended only for deleting data associated with a single specific customer, not for deleting data associated with multiple customers or for any other purpose. For more information, see Labeling and deleting data in Watson Assistant.

Deletes all data associated with a specified customer ID. The method has no effect if no data is associated with the customer ID.

You associate a customer ID with data by passing the X-Watson-Metadata header with a request that passes data. For more information about personal data and customer IDs, see Information security.

Note: This operation is intended only for deleting data associated with a single specific customer, not for deleting data associated with multiple customers or for any other purpose. For more information, see Labeling and deleting data in Watson Assistant.

DELETE /v1/user_data
ServiceCall<Void> deleteUserData(DeleteUserDataOptions deleteUserDataOptions)
deleteUserData(params)
delete_user_data(
        self,
        customer_id: str,
        **kwargs,
    ) -> DetailedResponse
DeleteUserData(string customerId)

Rate limit

This operation is limited to 4 requests per minute.

Request

Use the DeleteUserDataOptions.Builder to create a DeleteUserDataOptions object that contains the parameter values for the deleteUserData method.

Query Parameters

  • version
    Required*
    string

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2021-11-27.

  • customer_id
    Required*
    string

    The customer ID for which all data is to be deleted.

DeleteUserDataOptions

The deleteUserData options.

parameters

  • customerId
    Required*
    string

    The customer ID for which all data is to be deleted.

parameters

  • customer_id
    Required*
    str

    The customer ID for which all data is to be deleted.

parameters

  • customerId
    Required*
    string

    The customer ID for which all data is to be deleted.

  • curl -X DELETE -u "apikey:{apikey}" "{url}/v1/user_data?customer_id={id}&version=2021-06-14"
  • IamAuthenticator authenticator = new IamAuthenticator(
    apikey: "{apikey}"
    );

AssistantService assistant = new AssistantService("2021-06-14", authenticator);
assistant.SetServiceUrl("{url}");

var result = assistant.DeleteUserData(
    customerId: "{id}"
    );

Console.WriteLine(result.Response);
  • IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
Assistant assistant = new Assistant("2021-06-14", authenticator);
assistant.setServiceUrl("{url}");

String customerId = "{id}";

DeleteUserDataOptions options = new DeleteUserDataOptions.Builder(customerId).build();

assistant.deleteUserData(options).execute();    
  • const AssistantV1 = require('ibm-watson/assistant/v1');
const { IamAuthenticator } = require('ibm-watson/auth');

const assistant = new AssistantV1({
  version: '2021-06-14',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  serviceUrl: '{url}',
});

const params = {
  customerId: '{id}'
};

assistant.deleteUserData(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log(err)
  });
  • import json
from ibm_watson import AssistantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
assistant = AssistantV1(
    version='2021-06-14',
    authenticator = authenticator
)

assistant.set_service_url('{url}')

response = assistant.delete_user_data(
    customer_id = '{id}'
).get_result()

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

Response

Response type: object

Response Body

EmptyResponse

Status Code

  • 202

    The request to delete data was successfully submitted.

  • 400

    Bad Request. The request did not pass a customer ID:

    • No customer ID found in the request

No Sample Response

This method does not specify any sample responses.

id=curlclassName=tab-item-selected