List counterexamples
GET /v1/workspaces/{workspace_id}/counterexamples
List the counterexamples for a workspace. Counterexamples are examples that have been marked as irrelevant input.
Request
Path Parameters
Query Parameters
page_limit
integer
The number of records to return in each page of results.
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.
sort
string
The attribute by which returned counterexamples will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
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.
Response
200 - Successful request.
counterexamples
array
An array of objects describing the examples marked as irrelevant input.
pagination
Pagination
The pagination data for the returned objects. For more information about using pagination, see Pagination.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Create counterexample
POST /v1/workspaces/{workspace_id}/counterexamples
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.
Request
Request Body
Counterexample
The content of the new counterexample.
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.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
201 - Successful request.
text
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.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Get counterexample
GET /v1/workspaces/{workspace_id}/counterexamples/{text}
Get information about a counterexample. Counterexamples are examples that have been marked as irrelevant input.
Request
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
text
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.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Update counterexample
POST /v1/workspaces/{workspace_id}/counterexamples/{text}
Update the text of a counterexample. Counterexamples are examples that have been marked as irrelevant input.
Request
Request Body
UpdateCounterexample
The text of the counterexample.
text
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.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
text
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.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Delete counterexample
DELETE /v1/workspaces/{workspace_id}/counterexamples/{text}
Delete a counterexample from a workspace. Counterexamples are examples that have been marked as irrelevant input.
Request
Response
200 - Successful request.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
List entities
GET /v1/workspaces/{workspace_id}/entities
List the entities for a workspace.
Request
Path Parameters
Query Parameters
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.
page_limit
integer
The number of records to return in each page of results.
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.
sort
string
The attribute by which returned entities will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
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.
Response
200 - Successful request.
entities
array
An array of objects describing the entities defined for the workspace.
pagination
Pagination
The pagination data for the returned objects. For more information about using pagination, see Pagination.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Create entity
POST /v1/workspaces/{workspace_id}/entities
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.
Request
Request Body
CreateEntity
The content of the new entity.
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.)
description
string
The description of the entity. This string cannot contain carriage return, newline, or tab characters.
metadata
object
Any metadata related to the entity.
fuzzy_match
boolean
Whether to use fuzzy matching for the entity.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
values
array
An array of objects describing the entity values.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
201 - Successful request.
entity
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.)
description
string
The description of the entity. This string cannot contain carriage return, newline, or tab characters.
metadata
object
Any metadata related to the entity.
fuzzy_match
boolean
Whether to use fuzzy matching for the entity.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
values
array
An array of objects describing the entity values.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Get entity
GET /v1/workspaces/{workspace_id}/entities/{entity}
Get information about an entity, optionally including all entity content.
Request
Path Parameters
Query Parameters
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.
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
entity
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.)
description
string
The description of the entity. This string cannot contain carriage return, newline, or tab characters.
metadata
object
Any metadata related to the entity.
fuzzy_match
boolean
Whether to use fuzzy matching for the entity.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
values
array
An array of objects describing the entity values.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Update entity
POST /v1/workspaces/{workspace_id}/entities/{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.
Request
Request Body
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.
entity
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-`.
description
string
The description of the entity. This string cannot contain carriage return, newline, or tab characters.
metadata
object
Any metadata related to the entity.
fuzzy_match
boolean
Whether to use fuzzy matching for the entity.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
values
array
An array of objects describing the entity values.
Path Parameters
Query Parameters
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.
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
entity
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.)
description
string
The description of the entity. This string cannot contain carriage return, newline, or tab characters.
metadata
object
Any metadata related to the entity.
fuzzy_match
boolean
Whether to use fuzzy matching for the entity.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
values
array
An array of objects describing the entity values.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Delete entity
DELETE /v1/workspaces/{workspace_id}/entities/{entity}
Delete an entity from a workspace, or disable a system entity.
Request
Response
200 - Successful request.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
List entity values
GET /v1/workspaces/{workspace_id}/entities/{entity}/values
List the values for an entity.
Request
Path Parameters
Query Parameters
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.
page_limit
integer
The number of records to return in each page of results.
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.
sort
string
The attribute by which returned entity values will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
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.
Response
200 - Successful request.
values
array
An array of entity values.
pagination
Pagination
The pagination data for the returned objects. For more information about using pagination, see Pagination.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Create entity value
POST /v1/workspaces/{workspace_id}/entities/{entity}/values
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.
Request
Request Body
CreateValue
The new entity value.
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.
metadata
object
Any metadata related to the entity value.
type
string
Specifies the type of entity value.
synonyms
array
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.
patterns
array
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.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
201 - Successful request.
value
string
The text of the entity value. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
metadata
object
Any metadata related to the entity value.
type
string
Specifies the type of entity value.
synonyms
array
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.
patterns
array
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.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Get entity value
GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
Get information about an entity value.
Request
Path Parameters
Query Parameters
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.
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
value
string
The text of the entity value. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
metadata
object
Any metadata related to the entity value.
type
string
Specifies the type of entity value.
synonyms
array
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.
patterns
array
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.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Update entity value
POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{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.
Request
Request Body
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.
value
string
The text of the entity value. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
metadata
object
Any metadata related to the entity value.
type
string
Specifies the type of entity value.
synonyms
array
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.
patterns
array
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.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
Path Parameters
Query Parameters
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.
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
value
string
The text of the entity value. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
metadata
object
Any metadata related to the entity value.
type
string
Specifies the type of entity value.
synonyms
array
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.
patterns
array
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.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Delete entity value
DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
Delete a value from an entity.
Request
Response
200 - Successful request.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
List entity value synonyms
GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms
List the synonyms for an entity value.
Request
Path Parameters
Query Parameters
page_limit
integer
The number of records to return in each page of results.
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.
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 (`-`).
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.
Response
200 - Successful request.
synonyms
array
An array of synonyms.
pagination
Pagination
The pagination data for the returned objects. For more information about using pagination, see Pagination.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Create entity value synonym
POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms
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.
Request
Request Body
Synonym
The new synonym.
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.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
201 - Successful request.
synonym
string
The text of the synonym. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Get entity value synonym
GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
Get information about a synonym of an entity value.
Request
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
synonym
string
The text of the synonym. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Update entity value synonym
POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{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.
Request
Request Body
UpdateSynonym
The updated entity value synonym.
synonym
string
The text of the synonym. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
synonym
string
The text of the synonym. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Delete entity value synonym
DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
Delete a synonym from an entity value.
Request
Response
200 - Successful request.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
List entity mentions
GET /v1/workspaces/{workspace_id}/entities/{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.
Request
Path Parameters
Query Parameters
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.
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
examples
array
An array of objects describing the entity mentions defined for an entity.
pagination
Pagination
The pagination data for the returned objects. For more information about using pagination, see Pagination.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
List intents
GET /v1/workspaces/{workspace_id}/intents
List the intents for a workspace.
Request
Path Parameters
Query Parameters
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.
page_limit
integer
The number of records to return in each page of results.
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.
sort
string
The attribute by which returned intents will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
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.
Response
200 - Successful request.
intents
array
An array of objects describing the intents defined for the workspace.
pagination
Pagination
The pagination data for the returned objects. For more information about using pagination, see Pagination.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Create intent
POST /v1/workspaces/{workspace_id}/intents
Create a new intent.
If you want to create multiple intents with a single API call, consider using the Update workspace method instead.
Request
Request Body
CreateIntent
The content of the new intent.
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-`.
description
string
The description of the intent. This string cannot contain carriage return, newline, or tab characters.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
examples
array
An array of user input examples for the intent.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
201 - Successful request.
intent
string
The name of the intent. This string must conform to the following restrictions:
- It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
- It cannot begin with the reserved prefix `sys-`.
description
string
The description of the intent. This string cannot contain carriage return, newline, or tab characters.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
examples
array
An array of user input examples for the intent.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Get intent
GET /v1/workspaces/{workspace_id}/intents/{intent}
Get information about an intent, optionally including all intent content.
Request
Path Parameters
Query Parameters
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.
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
intent
string
The name of the intent. This string must conform to the following restrictions:
- It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
- It cannot begin with the reserved prefix `sys-`.
description
string
The description of the intent. This string cannot contain carriage return, newline, or tab characters.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
examples
array
An array of user input examples for the intent.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Update intent
POST /v1/workspaces/{workspace_id}/intents/{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.
Request
Request Body
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.
intent
string
The name of the intent. This string must conform to the following restrictions:
- It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
- It cannot begin with the reserved prefix `sys-`.
description
string
The description of the intent. This string cannot contain carriage return, newline, or tab characters.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
examples
array
An array of user input examples for the intent.
Path Parameters
Query Parameters
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.
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
intent
string
The name of the intent. This string must conform to the following restrictions:
- It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
- It cannot begin with the reserved prefix `sys-`.
description
string
The description of the intent. This string cannot contain carriage return, newline, or tab characters.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
examples
array
An array of user input examples for the intent.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Delete intent
DELETE /v1/workspaces/{workspace_id}/intents/{intent}
Delete an intent from a workspace.
Request
Response
200 - Successful request.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
List user input examples
GET /v1/workspaces/{workspace_id}/intents/{intent}/examples
List the user input examples for an intent, optionally including contextual entity mentions.
Request
Path Parameters
Query Parameters
page_limit
integer
The number of records to return in each page of results.
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.
sort
string
The attribute by which returned examples will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
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.
Response
200 - Successful request.
examples
array
An array of objects describing the examples defined for the intent.
pagination
Pagination
The pagination data for the returned objects. For more information about using pagination, see Pagination.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Create user input example
POST /v1/workspaces/{workspace_id}/intents/{intent}/examples
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.
Request
Request Body
Example
The content of the new user input example.
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.
mentions
array
An array of contextual entity mentions.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
201 - Successful request.
text
string
The text of a user input example. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
mentions
array
An array of contextual entity mentions.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Get user input example
GET /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
Get information about a user input example.
Request
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
text
string
The text of a user input example. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
mentions
array
An array of contextual entity mentions.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Update user input example
POST /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
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.
Request
Request Body
UpdateExample
The new text of the user input example.
text
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.
mentions
array
An array of contextual entity mentions.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
text
string
The text of a user input example. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
mentions
array
An array of contextual entity mentions.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Delete user input example
DELETE /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
Delete a user input example from an intent.
Request
Response
200 - Successful request.
400 - Invalid request
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
List dialog nodes
GET /v1/workspaces/{workspace_id}/dialog_nodes
List the dialog nodes for a workspace.
Request
Path Parameters
Query Parameters
page_limit
integer
The number of records to return in each page of results.
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.
sort
string
The attribute by which returned dialog nodes will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
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.
Response
200 - Successful request
dialog_nodes
array
An array of objects describing the dialog nodes defined for the workspace.
pagination
Pagination
The pagination data for the returned objects. For more information about using pagination, see Pagination.
400 - Invalid request
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Create dialog node
POST /v1/workspaces/{workspace_id}/dialog_nodes
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.
Request
Request Body
DialogNode
A CreateDialogNode object defining the content of the new dialog node.
dialog_node
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.
description
string
The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.
conditions
string
The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.
parent
string
The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.
previous_sibling
string
The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.
output
DialogNodeOutput
The output of the dialog node. For more information about how to specify dialog node output, see the documentation.
generic
array
An array of objects describing the output defined for the dialog node.
integrations
object
Output intended for specific integrations. For more information, see the documentation.
modifiers
object
Options that modify how specified output is handled.
context
DialogNodeContext
The context for the dialog node.
integrations
object
Context data intended for specific integrations.
metadata
object
The metadata for the dialog node.
next_step
DialogNodeNextStep
The next step to execute following this dialog node.
behavior
Required *
string
What happens after the dialog node completes. The valid values depend on the node type:
- The following values are valid for any node:
- `get_user_input`
- `skip_user_input`
- `jump_to`
- If the node is of type `event_handler` and its parent node is of type `slot` or `frame`, additional values are also valid:
- if event_name=`filled` and the type of the parent node is `slot`:
- `reprompt`
- `skip_all_slots`
- if event_name=`nomatch` and the type of the parent node is `slot`:
- `reprompt`
- `skip_slot`
- `skip_all_slots`
- if event_name=`generic` and the type of the parent node is `frame`:
- `reprompt`
- `skip_slot`
- `skip_all_slots`
If you specify `jump_to`, then you must also specify a value for the `dialog_node` property.
dialog_node
string
The unique ID of the dialog node to process next. This parameter is required if behavior=`jump_to`.
selector
string
Which part of the dialog node to process next.
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.
type
string
How the dialog node is processed.
event_name
string
How an `event_handler` node is processed.
variable
string
The location in the dialog context where output is stored.
actions
array
An array of objects describing any actions to be invoked by the dialog node.
digress_in
string
Whether this top-level dialog node can be digressed into.
digress_out
string
Whether this dialog node can be returned to after a digression.
digress_out_slots
string
Whether the user can digress to top-level nodes while filling out slots.
user_label
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).
disambiguation_opt_out
boolean
Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.
disabled
boolean
For internal use only.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
201 - Successful request
dialog_node
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.
description
string
The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.
conditions
string
The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.
parent
string
The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.
previous_sibling
string
The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.
output
DialogNodeOutput
The output of the dialog node. For more information about how to specify dialog node output, see the documentation.
context
DialogNodeContext
The context for the dialog node.
metadata
object
The metadata for the dialog node.
next_step
DialogNodeNextStep
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.
type
string
How the dialog node is processed.
event_name
string
How an `event_handler` node is processed.
variable
string
The location in the dialog context where output is stored.
actions
array
An array of objects describing any actions to be invoked by the dialog node.
digress_in
string
Whether this top-level dialog node can be digressed into.
digress_out
string
Whether this dialog node can be returned to after a digression.
digress_out_slots
string
Whether the user can digress to top-level nodes while filling out slots.
user_label
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).
disambiguation_opt_out
boolean
Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.
disabled
boolean
For internal use only.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Get dialog node
GET /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}
Get information about a dialog node.
Request
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request
dialog_node
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.
description
string
The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.
conditions
string
The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.
parent
string
The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.
previous_sibling
string
The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.
output
DialogNodeOutput
The output of the dialog node. For more information about how to specify dialog node output, see the documentation.
context
DialogNodeContext
The context for the dialog node.
metadata
object
The metadata for the dialog node.
next_step
DialogNodeNextStep
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.
type
string
How the dialog node is processed.
event_name
string
How an `event_handler` node is processed.
variable
string
The location in the dialog context where output is stored.
actions
array
An array of objects describing any actions to be invoked by the dialog node.
digress_in
string
Whether this top-level dialog node can be digressed into.
digress_out
string
Whether this dialog node can be returned to after a digression.
digress_out_slots
string
Whether the user can digress to top-level nodes while filling out slots.
user_label
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).
disambiguation_opt_out
boolean
Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.
disabled
boolean
For internal use only.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Update dialog node
POST /v1/workspaces/{workspace_id}/dialog_nodes/{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.
Request
Request Body
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.
dialog_node
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.
description
string
The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.
conditions
string
The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.
parent
string
The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.
previous_sibling
string
The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.
output
DialogNodeOutput
The output of the dialog node. For more information about how to specify dialog node output, see the documentation.
generic
array
An array of objects describing the output defined for the dialog node.
integrations
object
Output intended for specific integrations. For more information, see the documentation.
modifiers
object
Options that modify how specified output is handled.
context
DialogNodeContext
The context for the dialog node.
integrations
object
Context data intended for specific integrations.
metadata
object
The metadata for the dialog node.
next_step
DialogNodeNextStep
The next step to execute following this dialog node.
behavior
Required *
string
What happens after the dialog node completes. The valid values depend on the node type:
- The following values are valid for any node:
- `get_user_input`
- `skip_user_input`
- `jump_to`
- If the node is of type `event_handler` and its parent node is of type `slot` or `frame`, additional values are also valid:
- if event_name=`filled` and the type of the parent node is `slot`:
- `reprompt`
- `skip_all_slots`
- if event_name=`nomatch` and the type of the parent node is `slot`:
- `reprompt`
- `skip_slot`
- `skip_all_slots`
- if event_name=`generic` and the type of the parent node is `frame`:
- `reprompt`
- `skip_slot`
- `skip_all_slots`
If you specify `jump_to`, then you must also specify a value for the `dialog_node` property.
dialog_node
string
The unique ID of the dialog node to process next. This parameter is required if behavior=`jump_to`.
selector
string
Which part of the dialog node to process next.
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.
type
string
How the dialog node is processed.
event_name
string
How an `event_handler` node is processed.
variable
string
The location in the dialog context where output is stored.
actions
array
An array of objects describing any actions to be invoked by the dialog node.
digress_in
string
Whether this top-level dialog node can be digressed into.
digress_out
string
Whether this dialog node can be returned to after a digression.
digress_out_slots
string
Whether the user can digress to top-level nodes while filling out slots.
user_label
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).
disambiguation_opt_out
boolean
Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.
disabled
boolean
For internal use only.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request
dialog_node
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.
description
string
The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.
conditions
string
The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.
parent
string
The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.
previous_sibling
string
The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.
output
DialogNodeOutput
The output of the dialog node. For more information about how to specify dialog node output, see the documentation.
context
DialogNodeContext
The context for the dialog node.
metadata
object
The metadata for the dialog node.
next_step
DialogNodeNextStep
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.
type
string
How the dialog node is processed.
event_name
string
How an `event_handler` node is processed.
variable
string
The location in the dialog context where output is stored.
actions
array
An array of objects describing any actions to be invoked by the dialog node.
digress_in
string
Whether this top-level dialog node can be digressed into.
digress_out
string
Whether this dialog node can be returned to after a digression.
digress_out_slots
string
Whether the user can digress to top-level nodes while filling out slots.
user_label
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).
disambiguation_opt_out
boolean
Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.
disabled
boolean
For internal use only.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
400 - Invalid request
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Delete dialog node
DELETE /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}
Delete a dialog node from a workspace.
Request
Response
200 - Successful request
400 - Invalid request
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
List workspaces
GET /v1/workspaces
List the workspaces associated with a Watson Assistant service instance.
Request
Path Parameters
Query Parameters
page_limit
integer
The number of records to return in each page of results.
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.
sort
string
The attribute by which returned workspaces will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
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.
Response
200 - Successful request.
workspaces
array
An array of objects describing the workspaces associated with the service instance.
pagination
Pagination
The pagination data for the returned objects. For more information about using pagination, see Pagination.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
POST /v1/workspaces
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.
Request
Request Body
CreateWorkspace
name
string
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
description
string
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
language
string
The language of the workspace.
workspace_id
string
The workspace ID of the workspace.
dialog_nodes
array
An array of objects describing the dialog nodes in the workspace.
counterexamples
array
An array of objects defining input examples that have been marked as irrelevant input.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
metadata
object
Any metadata related to the workspace.
learning_opt_out
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.
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
tooling
WorkspaceSystemSettingsTooling
Workspace settings related to the Watson Assistant user interface.
disambiguation
WorkspaceSystemSettingsDisambiguation
Workspace settings related to the disambiguation feature.
human_agent_assist
object
For internal use only.
spelling_suggestions
boolean
Whether spelling correction is enabled for the workspace.
spelling_auto_correct
boolean
Whether autocorrection is enabled for the workspace. If spelling correction is enabled and this property is `false`, any suggested corrections are returned in the suggested_text property of the message response. If this property is `true`, any corrections are automatically applied to the user input, and the original text is returned in the original_text property of the message response.
system_entities
WorkspaceSystemSettingsSystemEntities
Workspace settings related to the behavior of system entities.
off_topic
WorkspaceSystemSettingsOffTopic
Workspace settings related to detection of irrelevant input.
auto_learn
object
For internal use only.
nlp
WorkspaceSystemSettingsNlp
Workspace settings related to the version of the training algorithms currently used by the skill.
status
string
The current status of the workspace:
- Available: The workspace is available and ready to process messages.
- Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
- Non Existent: The workspace does not exist.
- Processing: An asynchronous operation has not yet completed.
- Training: The workspace is training based on new data such as intents or examples.
status_errors
array
An array of messages about errors that caused an asynchronous operation to fail.
webhooks
array
intents
array
An array of objects defining the intents for the workspace.
entities
array
An array of objects describing the entities for the workspace.
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
201 - Successful request.
name
string
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
description
string
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
language
string
The language of the workspace.
workspace_id
string
The workspace ID of the workspace.
dialog_nodes
array
An array of objects describing the dialog nodes in the workspace.
counterexamples
array
An array of objects defining input examples that have been marked as irrelevant input.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
metadata
object
Any metadata related to the workspace.
learning_opt_out
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.
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
status
string
The current status of the workspace:
- Available: The workspace is available and ready to process messages.
- Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
- Non Existent: The workspace does not exist.
- Processing: An asynchronous operation has not yet completed.
- Training: The workspace is training based on new data such as intents or examples.
status_errors
array
An array of messages about errors that caused an asynchronous operation to fail.
webhooks
array
intents
array
An array of intents.
entities
array
An array of objects describing the entities for the workspace.
counts
WorkspaceCounts
An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Get information about a workspace
GET /v1/workspaces/{workspace_id}
Get information about a workspace, optionally including all workspace content.
Request
Path Parameters
Query Parameters
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.
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
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.
Response
200 - Successful request.
name
string
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
description
string
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
language
string
The language of the workspace.
workspace_id
string
The workspace ID of the workspace.
dialog_nodes
array
An array of objects describing the dialog nodes in the workspace.
counterexamples
array
An array of objects defining input examples that have been marked as irrelevant input.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
metadata
object
Any metadata related to the workspace.
learning_opt_out
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.
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
status
string
The current status of the workspace:
- Available: The workspace is available and ready to process messages.
- Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
- Non Existent: The workspace does not exist.
- Processing: An asynchronous operation has not yet completed.
- Training: The workspace is training based on new data such as intents or examples.
status_errors
array
An array of messages about errors that caused an asynchronous operation to fail.
webhooks
array
intents
array
An array of intents.
entities
array
An array of objects describing the entities for the workspace.
counts
WorkspaceCounts
An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
POST /v1/workspaces/{workspace_id}
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.
Request
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.
name
string
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
description
string
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
language
string
The language of the workspace.
workspace_id
string
The workspace ID of the workspace.
dialog_nodes
array
An array of objects describing the dialog nodes in the workspace.
counterexamples
array
An array of objects defining input examples that have been marked as irrelevant input.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
metadata
object
Any metadata related to the workspace.
learning_opt_out
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.
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
tooling
WorkspaceSystemSettingsTooling
Workspace settings related to the Watson Assistant user interface.
disambiguation
WorkspaceSystemSettingsDisambiguation
Workspace settings related to the disambiguation feature.
human_agent_assist
object
For internal use only.
spelling_suggestions
boolean
Whether spelling correction is enabled for the workspace.
spelling_auto_correct
boolean
Whether autocorrection is enabled for the workspace. If spelling correction is enabled and this property is `false`, any suggested corrections are returned in the suggested_text property of the message response. If this property is `true`, any corrections are automatically applied to the user input, and the original text is returned in the original_text property of the message response.
system_entities
WorkspaceSystemSettingsSystemEntities
Workspace settings related to the behavior of system entities.
off_topic
WorkspaceSystemSettingsOffTopic
Workspace settings related to detection of irrelevant input.
auto_learn
object
For internal use only.
nlp
WorkspaceSystemSettingsNlp
Workspace settings related to the version of the training algorithms currently used by the skill.
status
string
The current status of the workspace:
- Available: The workspace is available and ready to process messages.
- Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
- Non Existent: The workspace does not exist.
- Processing: An asynchronous operation has not yet completed.
- Training: The workspace is training based on new data such as intents or examples.
status_errors
array
An array of messages about errors that caused an asynchronous operation to fail.
webhooks
array
intents
array
An array of objects defining the intents for the workspace.
entities
array
An array of objects describing the entities for the workspace.
Path Parameters
Query Parameters
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.
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Response
200 - Successful request.
name
string
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
description
string
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
language
string
The language of the workspace.
workspace_id
string
The workspace ID of the workspace.
dialog_nodes
array
An array of objects describing the dialog nodes in the workspace.
counterexamples
array
An array of objects defining input examples that have been marked as irrelevant input.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
metadata
object
Any metadata related to the workspace.
learning_opt_out
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.
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
status
string
The current status of the workspace:
- Available: The workspace is available and ready to process messages.
- Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
- Non Existent: The workspace does not exist.
- Processing: An asynchronous operation has not yet completed.
- Training: The workspace is training based on new data such as intents or examples.
status_errors
array
An array of messages about errors that caused an asynchronous operation to fail.
webhooks
array
intents
array
An array of intents.
entities
array
An array of objects describing the entities for the workspace.
counts
WorkspaceCounts
An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Delete workspace
DELETE /v1/workspaces/{workspace_id}
Delete a workspace from the service instance.
Request
Response
200 - Successful request.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
Get response to user input
POST /v1/workspaces/{workspace_id}/message
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.
Request
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.
input
MessageInput
An input object that includes the input text.
text
string
The text of the user input. This string cannot contain carriage return, newline, or tab characters.
spelling_suggestions
boolean
Whether to use spelling correction when processing the input. This property overrides the value of the spelling_suggestions property in the workspace settings.
spelling_auto_correct
boolean
Whether to use autocorrection when processing the input. If spelling correction is used and this property is `false`, any suggested corrections are returned in the suggested_text property of the message response. If this property is `true`, any corrections are automatically applied to the user input, and the original text is returned in the original_text property of the message response. This property overrides the value of the spelling_auto_correct property in the workspace settings.
suggested_text
string
Any suggested corrections of the input text. This property is returned only if spelling correction is enabled and autocorrection is disabled.
original_text
string
The original user input text. This property is returned only if autocorrection is enabled and the user input was corrected.
intents
array
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
array
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.
alternate_intents
boolean
Whether to return more than one intent. A value of `true` indicates that all matching intents are returned.
context
Context
State information for the conversation. To maintain state, include the context from the previous response.
conversation_id
string
The unique identifier of the conversation. The conversation ID cannot contain any of the following characters: `+` `=` `&&` `||` `>` `<` `!` `(` `)` `{` `}` `[` `]` `^` `"` `~` `*` `?` `:` `` `/`
system
object
For internal use only.
metadata
MessageContextMetadata
Metadata related to the message.
output
OutputData
An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log.
nodes_visited
array
An array of the nodes that were triggered to create the response, in the order in which they were visited. This information is useful for debugging and for tracing the path taken through the node tree.
nodes_visited_details
array
An array of objects containing detailed diagnostic information about the nodes that were triggered during processing of the input message. Included only if nodes_visited_details is set to `true` in the message request.
log_messages
Required *
array
An array of up to 50 messages logged with the request.
generic
array
Output intended for any channel. It is the responsibility of the client application to implement the supported response types.
actions
array
An array of objects describing any actions requested by the dialog node.
user_id
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.
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.
Response
200 - Successful request.
input
MessageInput
An input object that includes the input text.
intents
array
An array of intents recognized in the user input, sorted in descending order of confidence
entities
array
An array of entities identified in the user input.
alternate_intents
boolean
Whether to return more than one intent. A value of `true` indicates that all matching intents are returned.
context
Context
State information for the conversation. To maintain state, include the context from the previous response.
output
OutputData
An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log.
actions
array
An array of objects describing any actions requested by the dialog node.
user_id
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.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
List log events in a workspace
GET /v1/workspaces/{workspace_id}/logs
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.
Request
Path Parameters
Query Parameters
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.
cursor
string
A token identifying the page of results to retrieve.
Response
200 - Successful request.
logs
array
An array of objects describing log events.
pagination
LogPagination
The pagination data for the returned objects. For more information about using pagination, see Pagination.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
List log events in all workspaces
GET /v1/logs
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.
Request
Path Parameters
Query 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 (`-`).
page_limit
integer
The number of records to return in each page of results.
cursor
string
A token identifying the page of results to retrieve.
Response
200 - Successful request.
logs
array
An array of objects describing log events.
pagination
LogPagination
The pagination data for the returned objects. For more information about using pagination, see Pagination.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
POST /v1/workspaces/{workspace_id}/bulk_classify
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.
Request
Request Body
BulkClassifyInput
An input object that includes the text to classify.
input
Required *
array
An array of input utterances to classify.
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`.
Response
200 - Successful request.
output
array
An array of objects that contain classification information for the submitted input utterances.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
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 labeled data
DELETE /v1/user_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.
Request
Path Parameters
Query Parameters
customer_id
Required *
string
The customer ID for which all data is to be deleted.
Response
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`
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
POST /v1/workspaces_async
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.
Request
Request Body
CreateWorkspace
name
string
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
description
string
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
language
string
The language of the workspace.
workspace_id
string
The workspace ID of the workspace.
dialog_nodes
array
An array of objects describing the dialog nodes in the workspace.
counterexamples
array
An array of objects defining input examples that have been marked as irrelevant input.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
metadata
object
Any metadata related to the workspace.
learning_opt_out
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.
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
tooling
WorkspaceSystemSettingsTooling
Workspace settings related to the Watson Assistant user interface.
disambiguation
WorkspaceSystemSettingsDisambiguation
Workspace settings related to the disambiguation feature.
human_agent_assist
object
For internal use only.
spelling_suggestions
boolean
Whether spelling correction is enabled for the workspace.
spelling_auto_correct
boolean
Whether autocorrection is enabled for the workspace. If spelling correction is enabled and this property is `false`, any suggested corrections are returned in the suggested_text property of the message response. If this property is `true`, any corrections are automatically applied to the user input, and the original text is returned in the original_text property of the message response.
system_entities
WorkspaceSystemSettingsSystemEntities
Workspace settings related to the behavior of system entities.
off_topic
WorkspaceSystemSettingsOffTopic
Workspace settings related to detection of irrelevant input.
auto_learn
object
For internal use only.
nlp
WorkspaceSystemSettingsNlp
Workspace settings related to the version of the training algorithms currently used by the skill.
status
string
The current status of the workspace:
- Available: The workspace is available and ready to process messages.
- Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
- Non Existent: The workspace does not exist.
- Processing: An asynchronous operation has not yet completed.
- Training: The workspace is training based on new data such as intents or examples.
status_errors
array
An array of messages about errors that caused an asynchronous operation to fail.
webhooks
array
intents
array
An array of objects defining the intents for the workspace.
entities
array
An array of objects describing the entities for the workspace.
Response
202 - Successful request
name
string
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
description
string
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
language
string
The language of the workspace.
workspace_id
string
The workspace ID of the workspace.
dialog_nodes
array
An array of objects describing the dialog nodes in the workspace.
counterexamples
array
An array of objects defining input examples that have been marked as irrelevant input.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
metadata
object
Any metadata related to the workspace.
learning_opt_out
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.
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
status
string
The current status of the workspace:
- Available: The workspace is available and ready to process messages.
- Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
- Non Existent: The workspace does not exist.
- Processing: An asynchronous operation has not yet completed.
- Training: The workspace is training based on new data such as intents or examples.
status_errors
array
An array of messages about errors that caused an asynchronous operation to fail.
webhooks
array
intents
array
An array of intents.
entities
array
An array of objects describing the entities for the workspace.
counts
WorkspaceCounts
An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
POST /v1/workspaces_async/{workspace_id}
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.
Request
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.
name
string
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
description
string
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
language
string
The language of the workspace.
workspace_id
string
The workspace ID of the workspace.
dialog_nodes
array
An array of objects describing the dialog nodes in the workspace.
counterexamples
array
An array of objects defining input examples that have been marked as irrelevant input.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
metadata
object
Any metadata related to the workspace.
learning_opt_out
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.
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
tooling
WorkspaceSystemSettingsTooling
Workspace settings related to the Watson Assistant user interface.
disambiguation
WorkspaceSystemSettingsDisambiguation
Workspace settings related to the disambiguation feature.
human_agent_assist
object
For internal use only.
spelling_suggestions
boolean
Whether spelling correction is enabled for the workspace.
spelling_auto_correct
boolean
Whether autocorrection is enabled for the workspace. If spelling correction is enabled and this property is `false`, any suggested corrections are returned in the suggested_text property of the message response. If this property is `true`, any corrections are automatically applied to the user input, and the original text is returned in the original_text property of the message response.
system_entities
WorkspaceSystemSettingsSystemEntities
Workspace settings related to the behavior of system entities.
off_topic
WorkspaceSystemSettingsOffTopic
Workspace settings related to detection of irrelevant input.
auto_learn
object
For internal use only.
nlp
WorkspaceSystemSettingsNlp
Workspace settings related to the version of the training algorithms currently used by the skill.
status
string
The current status of the workspace:
- Available: The workspace is available and ready to process messages.
- Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
- Non Existent: The workspace does not exist.
- Processing: An asynchronous operation has not yet completed.
- Training: The workspace is training based on new data such as intents or examples.
status_errors
array
An array of messages about errors that caused an asynchronous operation to fail.
webhooks
array
intents
array
An array of objects defining the intents for the workspace.
entities
array
An array of objects describing the entities for the workspace.
Path Parameters
Query Parameters
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.
Response
202 - Successful request.
name
string
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
description
string
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
language
string
The language of the workspace.
workspace_id
string
The workspace ID of the workspace.
dialog_nodes
array
An array of objects describing the dialog nodes in the workspace.
counterexamples
array
An array of objects defining input examples that have been marked as irrelevant input.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
metadata
object
Any metadata related to the workspace.
learning_opt_out
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.
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
status
string
The current status of the workspace:
- Available: The workspace is available and ready to process messages.
- Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
- Non Existent: The workspace does not exist.
- Processing: An asynchronous operation has not yet completed.
- Training: The workspace is training based on new data such as intents or examples.
status_errors
array
An array of messages about errors that caused an asynchronous operation to fail.
webhooks
array
intents
array
An array of intents.
entities
array
An array of objects describing the entities for the workspace.
counts
WorkspaceCounts
An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.
GET /v1/workspaces_async/{workspace_id}/export
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.
Request
Path Parameters
Query Parameters
include_audit
boolean
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
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.
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.
Response
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.
name
string
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
description
string
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
language
string
The language of the workspace.
workspace_id
string
The workspace ID of the workspace.
dialog_nodes
array
An array of objects describing the dialog nodes in the workspace.
counterexamples
array
An array of objects defining input examples that have been marked as irrelevant input.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
metadata
object
Any metadata related to the workspace.
learning_opt_out
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.
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
status
string
The current status of the workspace:
- Available: The workspace is available and ready to process messages.
- Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
- Non Existent: The workspace does not exist.
- Processing: An asynchronous operation has not yet completed.
- Training: The workspace is training based on new data such as intents or examples.
status_errors
array
An array of messages about errors that caused an asynchronous operation to fail.
webhooks
array
intents
array
An array of intents.
entities
array
An array of objects describing the entities for the workspace.
counts
WorkspaceCounts
An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.
202 - Request to export workspace has been accepted successfully.
name
string
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
description
string
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
language
string
The language of the workspace.
workspace_id
string
The workspace ID of the workspace.
dialog_nodes
array
An array of objects describing the dialog nodes in the workspace.
counterexamples
array
An array of objects defining input examples that have been marked as irrelevant input.
created
string
The timestamp for creation of the object.
updated
string
The timestamp for the most recent update to the object.
metadata
object
Any metadata related to the workspace.
learning_opt_out
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.
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
status
string
The current status of the workspace:
- Available: The workspace is available and ready to process messages.
- Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
- Non Existent: The workspace does not exist.
- Processing: An asynchronous operation has not yet completed.
- Training: The workspace is training based on new data such as intents or examples.
status_errors
array
An array of messages about errors that caused an asynchronous operation to fail.
webhooks
array
intents
array
An array of intents.
entities
array
An array of objects describing the entities for the workspace.
counts
WorkspaceCounts
An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.
400 - Invalid request.
error
string
General description of an error.
errors
array
Collection of specific constraint violations associated with the error.
code
integer
HTTP status code for the error response.