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.

Update workspace method instead.">

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.

Update workspace method instead.">

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 workspace method instead.">

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.

Update entity method instead.">

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 method instead.">

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.

Update entity or Update entity value method instead.">

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 or Update entity value method instead.">

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.

Update workspace method instead.">

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 workspace method instead.">

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.

Update intent method instead.">

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 intent method instead.">

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.

Update workspace method instead.">

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 workspace method instead.">

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.

Create workspace

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.

Update workspace

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.

documentation.">

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.

Pagination.">

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.

Pagination.">

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.

Identify intents and entities in multiple user utterances

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.

Information security.

Note: This operation is intended only for deleting data associated with a single specific customer, not for deleting data associated with multiple customers or for any other purpose. For more information, see Labeling and deleting data in Watson Assistant.">

Delete 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.