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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
page_limit
int
The number of records to return in each page of results.
Default: 100
include_count
bool
Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is `true`, the `pagination` object in the response includes the `total` property.
Default: false
sort
str
The attribute by which returned counterexamples will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
Allowed values: text, updated
cursor
str
A token identifying the page of results to retrieve.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
text
Required *
str
The text of a user input marked as irrelevant input. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
Constraints:
- Min length: 1
- Max length: 1024
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
text
Required *
str
The text of a user input counterexample (for example, `What are you wearing?`).
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
text
Required *
str
The text of a user input counterexample (for example, `What are you wearing?`).
new_text
str
The text of a user input marked as irrelevant input. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
Constraints:
- Min length: 1
- Max length: 1024
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
text
Required *
str
The text of a user input counterexample (for example, `What are you wearing?`).
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
export
bool
Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included.
Default: false
page_limit
int
The number of records to return in each page of results.
Default: 100
include_count
bool
Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is `true`, the `pagination` object in the response includes the `total` property.
Default: false
sort
str
The attribute by which returned entities will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
Allowed values: entity, updated
cursor
str
A token identifying the page of results to retrieve.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity. This string must conform to the following restrictions:
- It can contain only Unicode alphanumeric, underscore, and hyphen characters.
- If you specify an entity name beginning with the reserved prefix `sys-`, it must be the name of a system entity that you want to enable. (Any entity content specified with the request is ignored.).
Constraints:
- Min length: 1
- Max length: 64
description
str
The description of the entity. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 128
metadata
dict
Any metadata related to the entity.
fuzzy_match
bool
Whether to use fuzzy matching for the entity.
values
List[CreateValue]
An array of objects describing the entity values.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
export
bool
Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included.
Default: false
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
new_entity
str
The name of the entity. This string must conform to the following restrictions:
- It can contain only Unicode alphanumeric, underscore, and hyphen characters.
- It cannot begin with the reserved prefix `sys-`.
Constraints:
- Min length: 1
- Max length: 64
new_description
str
The description of the entity. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 128
new_metadata
dict
Any metadata related to the entity.
new_fuzzy_match
bool
Whether to use fuzzy matching for the entity.
new_values
List[CreateValue]
An array of objects describing the entity values.
append
bool
Whether the new data is to be appended to the existing data in the entity. If append=`false`, elements included in the new data completely replace the corresponding existing elements, including all subelements. For example, if the new data for the entity includes values and append=`false`, all existing values for the entity are discarded and replaced with the new values.
If append=`true`, existing elements are preserved, and the new elements are added. If any elements in the new data collide with existing elements, the update request fails.
Default: false
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
export
bool
Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included.
Default: false
page_limit
int
The number of records to return in each page of results.
Default: 100
include_count
bool
Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is `true`, the `pagination` object in the response includes the `total` property.
Default: false
sort
str
The attribute by which returned entity values will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
Allowed values: value, updated
cursor
str
A token identifying the page of results to retrieve.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
value
Required *
str
The text of the entity value. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
Constraints:
- Min length: 1
- Max length: 64
metadata
dict
Any metadata related to the entity value.
type
str
Specifies the type of entity value.
Allowed values: synonyms, patterns
Default: synonyms
synonyms
List[str]
An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
patterns
List[str]
An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.
Constraints:
- Max items: 5
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
value
Required *
str
The text of the entity value.
export
bool
Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included.
Default: false
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
value
Required *
str
The text of the entity value.
new_value
str
The text of the entity value. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
Constraints:
- Min length: 1
- Max length: 64
new_metadata
dict
Any metadata related to the entity value.
new_type
str
Specifies the type of entity value.
Allowed values: synonyms, patterns
Default: synonyms
new_synonyms
List[str]
An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
new_patterns
List[str]
An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.
Constraints:
- Max items: 5
append
bool
Whether the new data is to be appended to the existing data in the entity value. If append=`false`, elements included in the new data completely replace the corresponding existing elements, including all subelements. For example, if the new data for the entity value includes synonyms and append=`false`, all existing synonyms for the entity value are discarded and replaced with the new synonyms.
If append=`true`, existing elements are preserved, and the new elements are added. If any elements in the new data collide with existing elements, the update request fails.
Default: false
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
value
Required *
str
The text of the entity value.
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
value
Required *
str
The text of the entity value.
page_limit
int
The number of records to return in each page of results.
Default: 100
include_count
bool
Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is `true`, the `pagination` object in the response includes the `total` property.
Default: false
sort
str
The attribute by which returned entity value synonyms will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
Allowed values: synonym, updated
cursor
str
A token identifying the page of results to retrieve.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
value
Required *
str
The text of the entity value.
synonym
Required *
str
The text of the synonym. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
Constraints:
- Min length: 1
- Max length: 64
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
value
Required *
str
The text of the entity value.
synonym
Required *
str
The text of the synonym.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
value
Required *
str
The text of the entity value.
synonym
Required *
str
The text of the synonym.
new_synonym
str
The text of the synonym. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
Constraints:
- Min length: 1
- Max length: 64
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
value
Required *
str
The text of the entity value.
synonym
Required *
str
The text of the synonym.
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
entity
Required *
str
The name of the entity.
export
bool
Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included.
Default: false
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
export
bool
Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included.
Default: false
page_limit
int
The number of records to return in each page of results.
Default: 100
include_count
bool
Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is `true`, the `pagination` object in the response includes the `total` property.
Default: false
sort
str
The attribute by which returned intents will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
Allowed values: intent, updated
cursor
str
A token identifying the page of results to retrieve.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
intent
Required *
str
The name of the intent. This string must conform to the following restrictions:
- It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
- It cannot begin with the reserved prefix `sys-`.
Constraints:
- Min length: 1
- Max length: 128
description
str
The description of the intent. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 128
examples
List[Example]
An array of user input examples for the intent.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
intent
Required *
str
The intent name.
export
bool
Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included.
Default: false
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
intent
Required *
str
The intent name.
new_intent
str
The name of the intent. This string must conform to the following restrictions:
- It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
- It cannot begin with the reserved prefix `sys-`.
Constraints:
- Min length: 1
- Max length: 128
new_description
str
The description of the intent. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 128
new_examples
List[Example]
An array of user input examples for the intent.
append
bool
Whether the new data is to be appended to the existing data in the object. If append=`false`, elements included in the new data completely replace the corresponding existing elements, including all subelements. For example, if the new data for the intent includes examples and append=`false`, all existing examples for the intent are discarded and replaced with the new examples.
If append=`true`, existing elements are preserved, and the new elements are added. If any elements in the new data collide with existing elements, the update request fails.
Default: false
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
intent
Required *
str
The intent name.
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
intent
Required *
str
The intent name.
page_limit
int
The number of records to return in each page of results.
Default: 100
include_count
bool
Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is `true`, the `pagination` object in the response includes the `total` property.
Default: false
sort
str
The attribute by which returned examples will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
Allowed values: text, updated
cursor
str
A token identifying the page of results to retrieve.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
intent
Required *
str
The intent name.
text
Required *
str
The text of a user input example. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
Constraints:
- Min length: 1
- Max length: 1024
mentions
List[Mention]
An array of contextual entity mentions.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
intent
Required *
str
The intent name.
text
Required *
str
The text of the user input example.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
intent
Required *
str
The intent name.
text
Required *
str
The text of the user input example.
new_text
str
The text of the user input example. This string must conform to the following restrictions:
- It cannot contain carriage return, newline, or tab characters.
- It cannot consist of only whitespace characters.
Constraints:
- Min length: 1
- Max length: 1024
new_mentions
List[Mention]
An array of contextual entity mentions.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
intent
Required *
str
The intent name.
text
Required *
str
The text of the user input example.
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
page_limit
int
The number of records to return in each page of results.
Default: 100
include_count
bool
Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is `true`, the `pagination` object in the response includes the `total` property.
Default: false
sort
str
The attribute by which returned dialog nodes will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
Allowed values: dialog_node, updated
cursor
str
A token identifying the page of results to retrieve.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
dialog_node
Required *
str
The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.
This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.
Constraints:
- Min length: 1
- Max length: 1024
description
str
The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 128
conditions
str
The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 2048
parent
str
The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.
previous_sibling
str
The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.
output
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
dict
The metadata for the dialog node.
next_step
DialogNodeNextStep
The next step to execute following this dialog node.
title
str
A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the `suggestion` response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the `connect_to_agent` response type.
This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.
Constraints:
- Min length: 1
- Max length: 512
type
str
How the dialog node is processed.
Allowed values: standard, event_handler, frame, slot, response_condition, folder
event_name
str
How an `event_handler` node is processed.
Allowed values: focus, input, filled, validate, filled_multiple, generic, nomatch, nomatch_responses_depleted, digression_return_prompt
variable
str
The location in the dialog context where output is stored.
actions
List[DialogNodeAction]
An array of objects describing any actions to be invoked by the dialog node.
Constraints:
- Max items: 5
digress_in
str
Whether this top-level dialog node can be digressed into.
Allowed values: not_available, returns, does_not_return
digress_out
str
Whether this dialog node can be returned to after a digression.
Allowed values: allow_returning, allow_all, allow_all_never_return
digress_out_slots
str
Whether the user can digress to top-level nodes while filling out slots.
Allowed values: not_allowed, allow_returning, allow_all
user_label
str
A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).
Constraints:
- Min length: 1
- Max length: 512
disambiguation_opt_out
bool
Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.
Default: false
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
dialog_node
Required *
str
The dialog node ID (for example, `node_1_1479323581900`).
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
dialog_node
Required *
str
The dialog node ID (for example, `node_1_1479323581900`).
new_dialog_node
str
The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.
This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.
Constraints:
- Min length: 1
- Max length: 1024
new_description
str
The description of the dialog node. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 128
new_conditions
str
The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 2048
new_parent
str
The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.
new_previous_sibling
str
The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.
new_output
DialogNodeOutput
The output of the dialog node. For more information about how to specify dialog node output, see the documentation.
new_context
DialogNodeContext
The context for the dialog node.
new_metadata
dict
The metadata for the dialog node.
new_next_step
DialogNodeNextStep
The next step to execute following this dialog node.
new_title
str
A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the `suggestion` response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the `connect_to_agent` response type.
This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.
Constraints:
- Min length: 1
- Max length: 512
new_type
str
How the dialog node is processed.
Allowed values: standard, event_handler, frame, slot, response_condition, folder
new_event_name
str
How an `event_handler` node is processed.
Allowed values: focus, input, filled, validate, filled_multiple, generic, nomatch, nomatch_responses_depleted, digression_return_prompt
new_variable
str
The location in the dialog context where output is stored.
new_actions
List[DialogNodeAction]
An array of objects describing any actions to be invoked by the dialog node.
Constraints:
- Max items: 5
new_digress_in
str
Whether this top-level dialog node can be digressed into.
Allowed values: not_available, returns, does_not_return
new_digress_out
str
Whether this dialog node can be returned to after a digression.
Allowed values: allow_returning, allow_all, allow_all_never_return
new_digress_out_slots
str
Whether the user can digress to top-level nodes while filling out slots.
Allowed values: not_allowed, allow_returning, allow_all
new_user_label
str
A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).
Constraints:
- Min length: 1
- Max length: 512
new_disambiguation_opt_out
bool
Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.
Default: false
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
dialog_node
Required *
str
The dialog node ID (for example, `node_1_1479323581900`).
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
Parameters
page_limit
int
The number of records to return in each page of results.
Default: 100
include_count
bool
Whether to include information about the number of records that satisfy the request, regardless of the page limit. If this parameter is `true`, the `pagination` object in the response includes the `total` property.
Default: false
sort
str
The attribute by which returned workspaces will be sorted. To reverse the sort order, prefix the value with a minus sign (`-`).
Allowed values: name, updated
cursor
str
A token identifying the page of results to retrieve.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
name
str
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 64
description
str
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 128
language
str
The language of the workspace.
dialog_nodes
List[DialogNode]
An array of objects describing the dialog nodes in the workspace.
counterexamples
List[Counterexample]
An array of objects defining input examples that have been marked as irrelevant input.
metadata
dict
Any metadata related to the workspace.
learning_opt_out
bool
Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. `true` indicates that workspace training data is not to be used.
Default: false
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
webhooks
List[Webhook]
A webhook that can be used by dialog nodes to make programmatic calls to an external function.
Note: Currently, only a single webhook named `main_webhook` is supported.
intents
List[CreateIntent]
An array of objects defining the intents for the workspace.
entities
List[CreateEntity]
An array of objects describing the entities for the workspace.
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
export
bool
Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included.
Default: false
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
sort
str
Indicates how the returned workspace data will be sorted. This parameter is valid only if export=`true`. Specify `sort=stable` to sort all workspace objects by unique identifier, in ascending alphabetical order.
Allowed values: stable
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
name
str
The name of the workspace. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 64
description
str
The description of the workspace. This string cannot contain carriage return, newline, or tab characters.
Constraints:
- Min length: 1
- Max length: 128
language
str
The language of the workspace.
dialog_nodes
List[DialogNode]
An array of objects describing the dialog nodes in the workspace.
counterexamples
List[Counterexample]
An array of objects defining input examples that have been marked as irrelevant input.
metadata
dict
Any metadata related to the workspace.
learning_opt_out
bool
Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. `true` indicates that workspace training data is not to be used.
Default: false
system_settings
WorkspaceSystemSettings
Global settings for the workspace.
webhooks
List[Webhook]
A webhook that can be used by dialog nodes to make programmatic calls to an external function.
Note: Currently, only a single webhook named `main_webhook` is supported.
intents
List[CreateIntent]
An array of objects defining the intents for the workspace.
entities
List[CreateEntity]
An array of objects describing the entities for the workspace.
append
bool
Whether the new data is to be appended to the existing data in the object. If append=`false`, elements included in the new data completely replace the corresponding existing elements, including all subelements. For example, if the new data for a workspace includes entities and append=`false`, all existing entities in the workspace are discarded and replaced with the new entities.
If append=`true`, existing elements are preserved, and the new elements are added. If any elements in the new data collide with existing elements, the update request fails.
Default: false
include_audit
bool
Whether to include the audit properties (`created` and `updated` timestamps) in the response.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
input
MessageInput
An input object that includes the input text.
intents
List[RuntimeIntent]
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
List[RuntimeEntity]
Entities to use when evaluating the message. Include entities from the previous response to continue using those entities rather than detecting entities in the new input.
alternate_intents
bool
Whether to return more than one intent. A value of `true` indicates that all matching intents are returned.
Default: false
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.
user_id
str
A string value that identifies the user who is interacting with the workspace. The client must provide a unique identifier for each individual end user who accesses the application. For user-based plans, this user ID is used to identify unique users for billing purposes. This string cannot contain carriage return, newline, or tab characters. If no value is specified in the input, user_id is automatically set to the value of context.conversation_id.
Note: This property is the same as the user_id property in the context metadata. If user_id is specified in both locations in a message request, the value specified at the root is used.
Constraints:
- Min length: 1
- Max length: 256
nodes_visited_details
bool
Whether to include additional diagnostic information about the dialog nodes that were visited during processing of the message.
Default: false
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
sort
str
How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (`-`).
filter
str
A cacheable parameter that limits the results to those matching the specified filter. For more information, see the documentation.
page_limit
int
The number of records to return in each page of results.
Note: If the API is not returning your data, try lowering the page_limit value.
Default: 100
cursor
str
A token identifying the page of results to retrieve.
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
Parameters
filter
Required *
str
A cacheable parameter that limits the results to those matching the specified filter. You must specify a filter query that includes a value for `language`, as well as a value for `request.context.system.assistant_id`, `workspace_id`, or `request.context.metadata.deployment`. These required filters must be specified using the exact match (`::`) operator. For more information, see the documentation.
sort
str
How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (`-`).
page_limit
int
The number of records to return in each page of results.
Default: 100
cursor
str
A token identifying the page of results to retrieve.
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
Parameters
workspace_id
Required *
str
Unique identifier of the workspace.
input
List[BulkClassifyUtterance]
An array of input utterances to classify.
Constraints:
- Min items: 1
- Max items: 50
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
Parameters
customer_id
Required *
str
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.