List counterexamples

GET /v1/workspaces/{workspace_id}/counterexamples

List the counterexamples for a workspace. Counterexamples are examples that have been marked as irrelevant input.

Request

Path Parameters

Query Parameters

page_limit

integer

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

include_count

boolean

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

sort

string

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

cursor

string

A token identifying the page of results to retrieve.

include_audit

boolean

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

Response

200 - Successful request.

counterexamples

array

An array of objects describing the examples marked as irrelevant input.

pagination

Pagination

The pagination data for the returned objects. For more information about using pagination, see Pagination.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Request Body

Counterexample

The content of the new counterexample.

text

Required *

string

The text of a user input marked as irrelevant input. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

201 - Successful request.

text

string

The text of a user input marked as irrelevant input. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Get counterexample

GET /v1/workspaces/{workspace_id}/counterexamples/{text}

Get information about a counterexample. Counterexamples are examples that have been marked as irrelevant input.

Request

Path Parameters

Query Parameters

include_audit

boolean

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

Response

200 - Successful request.

text

string

The text of a user input marked as irrelevant input. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Update counterexample

POST /v1/workspaces/{workspace_id}/counterexamples/{text}

Update the text of a counterexample. Counterexamples are examples that have been marked as irrelevant input.

Request

Request Body

UpdateCounterexample

The text of the counterexample.

text

string

The text of a user input marked as irrelevant input. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

200 - Successful request.

text

string

The text of a user input marked as irrelevant input. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Delete counterexample

DELETE /v1/workspaces/{workspace_id}/counterexamples/{text}

Delete a counterexample from a workspace. Counterexamples are examples that have been marked as irrelevant input.

Request

Response

200 - Successful request.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

List entities

GET /v1/workspaces/{workspace_id}/entities

List the entities for a workspace.

Request

Path Parameters

Query Parameters

export

boolean

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

page_limit

integer

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

include_count

boolean

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

sort

string

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

cursor

string

A token identifying the page of results to retrieve.

include_audit

boolean

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

Response

200 - Successful request.

entities

array

An array of objects describing the entities defined for the workspace.

pagination

Pagination

The pagination data for the returned objects. For more information about using pagination, see Pagination.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Request Body

CreateEntity

The content of the new entity.

entity

Required *

string

The name of the entity. This string must conform to the following restrictions:

  • It can contain only Unicode alphanumeric, underscore, and hyphen characters.
  • If you specify an entity name beginning with the reserved prefix `sys-`, it must be the name of a system entity that you want to enable. (Any entity content specified with the request is ignored.)

description

string

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

metadata

object

Any metadata related to the entity.

fuzzy_match

boolean

Whether to use fuzzy matching for the entity.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

values

array

An array of objects describing the entity values.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

201 - Successful request.

entity

string

The name of the entity. This string must conform to the following restrictions:

  • It can contain only Unicode alphanumeric, underscore, and hyphen characters.
  • If you specify an entity name beginning with the reserved prefix `sys-`, it must be the name of a system entity that you want to enable. (Any entity content specified with the request is ignored.)

description

string

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

metadata

object

Any metadata related to the entity.

fuzzy_match

boolean

Whether to use fuzzy matching for the entity.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

values

array

An array of objects describing the entity values.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Get entity

GET /v1/workspaces/{workspace_id}/entities/{entity}

Get information about an entity, optionally including all entity content.

Request

Path Parameters

Query Parameters

export

boolean

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

include_audit

boolean

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

Response

200 - Successful request.

entity

string

The name of the entity. This string must conform to the following restrictions:

  • It can contain only Unicode alphanumeric, underscore, and hyphen characters.
  • If you specify an entity name beginning with the reserved prefix `sys-`, it must be the name of a system entity that you want to enable. (Any entity content specified with the request is ignored.)

description

string

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

metadata

object

Any metadata related to the entity.

fuzzy_match

boolean

Whether to use fuzzy matching for the entity.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

values

array

An array of objects describing the entity values.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Update 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

Request Body

UpdateEntity

The updated content of the entity. Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) For example, if you update the values for an entity, the previously existing values are discarded and replaced with the new values specified in the update.

entity

string

The name of the entity. This string must conform to the following restrictions:

  • It can contain only Unicode alphanumeric, underscore, and hyphen characters.
  • It cannot begin with the reserved prefix `sys-`.

description

string

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

metadata

object

Any metadata related to the entity.

fuzzy_match

boolean

Whether to use fuzzy matching for the entity.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

values

array

An array of objects describing the entity values.

Path Parameters

Query Parameters

append

boolean

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

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

include_audit

boolean

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

Response

200 - Successful request.

entity

string

The name of the entity. This string must conform to the following restrictions:

  • It can contain only Unicode alphanumeric, underscore, and hyphen characters.
  • If you specify an entity name beginning with the reserved prefix `sys-`, it must be the name of a system entity that you want to enable. (Any entity content specified with the request is ignored.)

description

string

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

metadata

object

Any metadata related to the entity.

fuzzy_match

boolean

Whether to use fuzzy matching for the entity.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

values

array

An array of objects describing the entity values.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Delete entity

DELETE /v1/workspaces/{workspace_id}/entities/{entity}

Delete an entity from a workspace, or disable a system entity.

Request

Response

200 - Successful request.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

List entity values

GET /v1/workspaces/{workspace_id}/entities/{entity}/values

List the values for an entity.

Request

Path Parameters

Query Parameters

export

boolean

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

page_limit

integer

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

include_count

boolean

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

sort

string

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

cursor

string

A token identifying the page of results to retrieve.

include_audit

boolean

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

Response

200 - Successful request.

values

array

An array of entity values.

pagination

Pagination

The pagination data for the returned objects. For more information about using pagination, see Pagination.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Request Body

CreateValue

The new entity value.

value

Required *

string

The text of the entity value. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

metadata

object

Any metadata related to the entity value.

type

string

Specifies the type of entity value.

synonyms

array

An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

patterns

array

An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

201 - Successful request.

value

string

The text of the entity value. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

metadata

object

Any metadata related to the entity value.

type

string

Specifies the type of entity value.

synonyms

array

An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

patterns

array

An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Get entity value

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}

Get information about an entity value.

Request

Path Parameters

Query Parameters

export

boolean

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

include_audit

boolean

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

Response

200 - Successful request.

value

string

The text of the entity value. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

metadata

object

Any metadata related to the entity value.

type

string

Specifies the type of entity value.

synonyms

array

An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

patterns

array

An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Update entity 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

Request Body

UpdateValue

The updated content of the entity value.

Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) For example, if you update the synonyms for an entity value, the previously existing synonyms are discarded and replaced with the new synonyms specified in the update.

value

string

The text of the entity value. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

metadata

object

Any metadata related to the entity value.

type

string

Specifies the type of entity value.

synonyms

array

An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

patterns

array

An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Path Parameters

Query Parameters

append

boolean

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

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

include_audit

boolean

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

Response

200 - Successful request.

value

string

The text of the entity value. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

metadata

object

Any metadata related to the entity value.

type

string

Specifies the type of entity value.

synonyms

array

An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

patterns

array

An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression; for more information about how to specify a pattern, see the documentation.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Delete entity value

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}

Delete a value from an entity.

Request

Response

200 - Successful request.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

List entity value synonyms

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms

List the synonyms for an entity value.

Request

Path Parameters

Query Parameters

page_limit

integer

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

include_count

boolean

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

sort

string

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

cursor

string

A token identifying the page of results to retrieve.

include_audit

boolean

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

Response

200 - Successful request.

synonyms

array

An array of synonyms.

pagination

Pagination

The pagination data for the returned objects. For more information about using pagination, see Pagination.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Request Body

Synonym

The new synonym.

synonym

Required *

string

The text of the synonym. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

201 - Successful request.

synonym

string

The text of the synonym. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Get entity value synonym

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}

Get information about a synonym of an entity value.

Request

Path Parameters

Query Parameters

include_audit

boolean

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

Response

200 - Successful request.

synonym

string

The text of the synonym. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Update entity 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

Request Body

UpdateSynonym

The updated entity value synonym.

synonym

string

The text of the synonym. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

200 - Successful request.

synonym

string

The text of the synonym. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Delete entity value synonym

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}

Delete a synonym from an entity value.

Request

Response

200 - Successful request.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

List entity mentions

GET /v1/workspaces/{workspace_id}/entities/{entity}/mentions

List mentions for a contextual entity. An entity mention is an occurrence of a contextual entity in the context of an intent user input example.

Request

Path Parameters

Query Parameters

export

boolean

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

include_audit

boolean

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

Response

200 - Successful request.

examples

array

An array of objects describing the entity mentions defined for an entity.

pagination

Pagination

The pagination data for the returned objects. For more information about using pagination, see Pagination.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

List intents

GET /v1/workspaces/{workspace_id}/intents

List the intents for a workspace.

Request

Path Parameters

Query Parameters

export

boolean

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

page_limit

integer

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

include_count

boolean

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

sort

string

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

cursor

string

A token identifying the page of results to retrieve.

include_audit

boolean

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

Response

200 - Successful request.

intents

array

An array of objects describing the intents defined for the workspace.

pagination

Pagination

The pagination data for the returned objects. For more information about using pagination, see Pagination.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Request Body

CreateIntent

The content of the new intent.

intent

Required *

string

The name of the intent. This string must conform to the following restrictions:

  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
  • It cannot begin with the reserved prefix `sys-`.

description

string

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

examples

array

An array of user input examples for the intent.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

201 - Successful request.

intent

string

The name of the intent. This string must conform to the following restrictions:

  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
  • It cannot begin with the reserved prefix `sys-`.

description

string

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

examples

array

An array of user input examples for the intent.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Get intent

GET /v1/workspaces/{workspace_id}/intents/{intent}

Get information about an intent, optionally including all intent content.

Request

Path Parameters

Query Parameters

export

boolean

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

include_audit

boolean

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

Response

200 - Successful request.

intent

string

The name of the intent. This string must conform to the following restrictions:

  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
  • It cannot begin with the reserved prefix `sys-`.

description

string

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

examples

array

An array of user input examples for the intent.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Update 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

Request Body

UpdateIntent

The updated content of the intent.

Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) For example, if you update the user input examples for an intent, the previously existing examples are discarded and replaced with the new examples specified in the update.

intent

string

The name of the intent. This string must conform to the following restrictions:

  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
  • It cannot begin with the reserved prefix `sys-`.

description

string

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

examples

array

An array of user input examples for the intent.

Path Parameters

Query Parameters

append

boolean

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

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

include_audit

boolean

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

Response

200 - Successful request.

intent

string

The name of the intent. This string must conform to the following restrictions:

  • It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters.
  • It cannot begin with the reserved prefix `sys-`.

description

string

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

examples

array

An array of user input examples for the intent.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Delete intent

DELETE /v1/workspaces/{workspace_id}/intents/{intent}

Delete an intent from a workspace.

Request

Response

200 - Successful request.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

List user input examples

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples

List the user input examples for an intent, optionally including contextual entity mentions.

Request

Path Parameters

Query Parameters

page_limit

integer

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

include_count

boolean

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

sort

string

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

cursor

string

A token identifying the page of results to retrieve.

include_audit

boolean

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

Response

200 - Successful request.

examples

array

An array of objects describing the examples defined for the intent.

pagination

Pagination

The pagination data for the returned objects. For more information about using pagination, see Pagination.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Request Body

Example

The content of the new user input example.

text

Required *

string

The text of a user input example. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

mentions

array

An array of contextual entity mentions.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

201 - Successful request.

text

string

The text of a user input example. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

mentions

array

An array of contextual entity mentions.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Get user input example

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}

Get information about a user input example.

Request

Path Parameters

Query Parameters

include_audit

boolean

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

Response

200 - Successful request.

text

string

The text of a user input example. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

mentions

array

An array of contextual entity mentions.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Update 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

Request Body

UpdateExample

The new text of the user input example.

text

string

The text of the user input example. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

mentions

array

An array of contextual entity mentions.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

200 - Successful request.

text

string

The text of a user input example. This string must conform to the following restrictions:

  • It cannot contain carriage return, newline, or tab characters.
  • It cannot consist of only whitespace characters.

mentions

array

An array of contextual entity mentions.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Delete user input example

DELETE /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}

Delete a user input example from an intent.

Request

Response

200 - Successful request.

400 - Invalid request

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

List dialog nodes

GET /v1/workspaces/{workspace_id}/dialog_nodes

List the dialog nodes for a workspace.

Request

Path Parameters

Query Parameters

page_limit

integer

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

include_count

boolean

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

sort

string

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

cursor

string

A token identifying the page of results to retrieve.

include_audit

boolean

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

Response

200 - Successful request

dialog_nodes

array

An array of objects describing the dialog nodes defined for the workspace.

pagination

Pagination

The pagination data for the returned objects. For more information about using pagination, see Pagination.

400 - Invalid request

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Request Body

DialogNode

A CreateDialogNode object defining the content of the new dialog node.

dialog_node

Required *

string

The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.

This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

description

string

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

conditions

string

The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.

parent

string

The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.

previous_sibling

string

The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.

output

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

generic

array

An array of objects describing the output defined for the dialog node.

integrations

object

Output intended for specific integrations. For more information, see the documentation.

modifiers

object

Options that modify how specified output is handled.

context

DialogNodeContext

The context for the dialog node.

integrations

object

Context data intended for specific integrations.

metadata

object

The metadata for the dialog node.

next_step

DialogNodeNextStep

The next step to execute following this dialog node.

behavior

Required *

string

What happens after the dialog node completes. The valid values depend on the node type:

  • The following values are valid for any node:
    • `get_user_input`
    • `skip_user_input`
    • `jump_to`
  • If the node is of type `event_handler` and its parent node is of type `slot` or `frame`, additional values are also valid:
    • if event_name=`filled` and the type of the parent node is `slot`:
    • `reprompt`
    • `skip_all_slots`
  • if event_name=`nomatch` and the type of the parent node is `slot`:
    • `reprompt`
    • `skip_slot`
    • `skip_all_slots`
  • if event_name=`generic` and the type of the parent node is `frame`:
    • `reprompt`
    • `skip_slot`
    • `skip_all_slots`

If you specify `jump_to`, then you must also specify a value for the `dialog_node` property.

dialog_node

string

The unique ID of the dialog node to process next. This parameter is required if behavior=`jump_to`.

selector

string

Which part of the dialog node to process next.

title

string

A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the `suggestion` response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the `connect_to_agent` response type.

This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

type

string

How the dialog node is processed.

event_name

string

How an `event_handler` node is processed.

variable

string

The location in the dialog context where output is stored.

actions

array

An array of objects describing any actions to be invoked by the dialog node.

digress_in

string

Whether this top-level dialog node can be digressed into.

digress_out

string

Whether this dialog node can be returned to after a digression.

digress_out_slots

string

Whether the user can digress to top-level nodes while filling out slots.

user_label

string

A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).

disambiguation_opt_out

boolean

Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.

disabled

boolean

For internal use only.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

201 - Successful request

dialog_node

string

The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.

This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

description

string

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

conditions

string

The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.

parent

string

The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.

previous_sibling

string

The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.

output

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

context

DialogNodeContext

The context for the dialog node.

metadata

object

The metadata for the dialog node.

next_step

DialogNodeNextStep

The next step to execute following this dialog node.

title

string

A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the `suggestion` response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the `connect_to_agent` response type.

This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

type

string

How the dialog node is processed.

event_name

string

How an `event_handler` node is processed.

variable

string

The location in the dialog context where output is stored.

actions

array

An array of objects describing any actions to be invoked by the dialog node.

digress_in

string

Whether this top-level dialog node can be digressed into.

digress_out

string

Whether this dialog node can be returned to after a digression.

digress_out_slots

string

Whether the user can digress to top-level nodes while filling out slots.

user_label

string

A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).

disambiguation_opt_out

boolean

Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.

disabled

boolean

For internal use only.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Get dialog node

GET /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}

Get information about a dialog node.

Request

Path Parameters

Query Parameters

include_audit

boolean

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

Response

200 - Successful request

dialog_node

string

The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.

This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

description

string

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

conditions

string

The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.

parent

string

The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.

previous_sibling

string

The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.

output

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

context

DialogNodeContext

The context for the dialog node.

metadata

object

The metadata for the dialog node.

next_step

DialogNodeNextStep

The next step to execute following this dialog node.

title

string

A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the `suggestion` response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the `connect_to_agent` response type.

This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

type

string

How the dialog node is processed.

event_name

string

How an `event_handler` node is processed.

variable

string

The location in the dialog context where output is stored.

actions

array

An array of objects describing any actions to be invoked by the dialog node.

digress_in

string

Whether this top-level dialog node can be digressed into.

digress_out

string

Whether this dialog node can be returned to after a digression.

digress_out_slots

string

Whether the user can digress to top-level nodes while filling out slots.

user_label

string

A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).

disambiguation_opt_out

boolean

Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.

disabled

boolean

For internal use only.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Update 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

Request Body

UpdateDialogNode

The updated content of the dialog node.

Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) For example, if you update the actions for a dialog node, the previously existing actions are discarded and replaced with the new actions specified in the update.

dialog_node

string

The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.

This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

description

string

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

conditions

string

The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.

parent

string

The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.

previous_sibling

string

The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.

output

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

generic

array

An array of objects describing the output defined for the dialog node.

integrations

object

Output intended for specific integrations. For more information, see the documentation.

modifiers

object

Options that modify how specified output is handled.

context

DialogNodeContext

The context for the dialog node.

integrations

object

Context data intended for specific integrations.

metadata

object

The metadata for the dialog node.

next_step

DialogNodeNextStep

The next step to execute following this dialog node.

behavior

Required *

string

What happens after the dialog node completes. The valid values depend on the node type:

  • The following values are valid for any node:
    • `get_user_input`
    • `skip_user_input`
    • `jump_to`
  • If the node is of type `event_handler` and its parent node is of type `slot` or `frame`, additional values are also valid:
    • if event_name=`filled` and the type of the parent node is `slot`:
    • `reprompt`
    • `skip_all_slots`
  • if event_name=`nomatch` and the type of the parent node is `slot`:
    • `reprompt`
    • `skip_slot`
    • `skip_all_slots`
  • if event_name=`generic` and the type of the parent node is `frame`:
    • `reprompt`
    • `skip_slot`
    • `skip_all_slots`

If you specify `jump_to`, then you must also specify a value for the `dialog_node` property.

dialog_node

string

The unique ID of the dialog node to process next. This parameter is required if behavior=`jump_to`.

selector

string

Which part of the dialog node to process next.

title

string

A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the `suggestion` response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the `connect_to_agent` response type.

This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

type

string

How the dialog node is processed.

event_name

string

How an `event_handler` node is processed.

variable

string

The location in the dialog context where output is stored.

actions

array

An array of objects describing any actions to be invoked by the dialog node.

digress_in

string

Whether this top-level dialog node can be digressed into.

digress_out

string

Whether this dialog node can be returned to after a digression.

digress_out_slots

string

Whether the user can digress to top-level nodes while filling out slots.

user_label

string

A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).

disambiguation_opt_out

boolean

Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.

disabled

boolean

For internal use only.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

200 - Successful request

dialog_node

string

The unique ID of the dialog node. This is an internal identifier used to refer to the dialog node from other dialog nodes and in the diagnostic information included with message responses.

This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

description

string

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

conditions

string

The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters.

parent

string

The unique ID of the parent dialog node. This property is omitted if the dialog node has no parent.

previous_sibling

string

The unique ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling.

output

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

context

DialogNodeContext

The context for the dialog node.

metadata

object

The metadata for the dialog node.

next_step

DialogNodeNextStep

The next step to execute following this dialog node.

title

string

A human-readable name for the dialog node. If the node is included in disambiguation, this title is used to populate the label property of the corresponding suggestion in the `suggestion` response type (unless it is overridden by the user_label property). The title is also used to populate the topic property in the `connect_to_agent` response type.

This string can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters.

type

string

How the dialog node is processed.

event_name

string

How an `event_handler` node is processed.

variable

string

The location in the dialog context where output is stored.

actions

array

An array of objects describing any actions to be invoked by the dialog node.

digress_in

string

Whether this top-level dialog node can be digressed into.

digress_out

string

Whether this dialog node can be returned to after a digression.

digress_out_slots

string

Whether the user can digress to top-level nodes while filling out slots.

user_label

string

A label that can be displayed externally to describe the purpose of the node to users. If set, this label is used to identify the node in disambiguation responses (overriding the value of the title property).

disambiguation_opt_out

boolean

Whether the dialog node should be excluded from disambiguation suggestions. Valid only when type=`standard` or `frame`.

disabled

boolean

For internal use only.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Invalid request

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Delete dialog node

DELETE /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}

Delete a dialog node from a workspace.

Request

Response

200 - Successful request

400 - Invalid request

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

List workspaces

GET /v1/workspaces

List the workspaces associated with a Watson Assistant service instance.

Request

Path Parameters

Query Parameters

page_limit

integer

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

include_count

boolean

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

sort

string

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

cursor

string

A token identifying the page of results to retrieve.

include_audit

boolean

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

Response

200 - Successful request.

workspaces

array

An array of objects describing the workspaces associated with the service instance.

pagination

Pagination

The pagination data for the returned objects. For more information about using pagination, see Pagination.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Request Body

CreateWorkspace

name

string

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

description

string

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

language

string

The language of the workspace.

workspace_id

string

The workspace ID of the workspace.

dialog_nodes

array

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

counterexamples

array

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

metadata

object

Any metadata related to the workspace.

learning_opt_out

boolean

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

system_settings

WorkspaceSystemSettings

Global settings for the workspace.

tooling

WorkspaceSystemSettingsTooling

Workspace settings related to the Watson Assistant user interface.

disambiguation

WorkspaceSystemSettingsDisambiguation

Workspace settings related to the disambiguation feature.

human_agent_assist

object

For internal use only.

spelling_suggestions

boolean

Whether spelling correction is enabled for the workspace.

spelling_auto_correct

boolean

Whether autocorrection is enabled for the workspace. If spelling correction is enabled and this property is `false`, any suggested corrections are returned in the suggested_text property of the message response. If this property is `true`, any corrections are automatically applied to the user input, and the original text is returned in the original_text property of the message response.

system_entities

WorkspaceSystemSettingsSystemEntities

Workspace settings related to the behavior of system entities.

off_topic

WorkspaceSystemSettingsOffTopic

Workspace settings related to detection of irrelevant input.

auto_learn

object

For internal use only.

nlp

WorkspaceSystemSettingsNlp

Workspace settings related to the version of the training algorithms currently used by the skill.

status

string

The current status of the workspace:

  • Available: The workspace is available and ready to process messages.
  • Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
  • Non Existent: The workspace does not exist.
  • Processing: An asynchronous operation has not yet completed.
  • Training: The workspace is training based on new data such as intents or examples.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail.

webhooks

array

intents

array

An array of objects defining the intents for the workspace.

entities

array

An array of objects describing the entities for the workspace.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

201 - Successful request.

name

string

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

description

string

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

language

string

The language of the workspace.

workspace_id

string

The workspace ID of the workspace.

dialog_nodes

array

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

counterexamples

array

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

metadata

object

Any metadata related to the workspace.

learning_opt_out

boolean

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

system_settings

WorkspaceSystemSettings

Global settings for the workspace.

status

string

The current status of the workspace:

  • Available: The workspace is available and ready to process messages.
  • Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
  • Non Existent: The workspace does not exist.
  • Processing: An asynchronous operation has not yet completed.
  • Training: The workspace is training based on new data such as intents or examples.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail.

webhooks

array

intents

array

An array of intents.

entities

array

An array of objects describing the entities for the workspace.

counts

WorkspaceCounts

An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Get information about a workspace

GET /v1/workspaces/{workspace_id}

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

Request

Path Parameters

Query Parameters

export

boolean

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

include_audit

boolean

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

sort

string

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

Response

200 - Successful request.

name

string

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

description

string

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

language

string

The language of the workspace.

workspace_id

string

The workspace ID of the workspace.

dialog_nodes

array

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

counterexamples

array

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

metadata

object

Any metadata related to the workspace.

learning_opt_out

boolean

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

system_settings

WorkspaceSystemSettings

Global settings for the workspace.

status

string

The current status of the workspace:

  • Available: The workspace is available and ready to process messages.
  • Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
  • Non Existent: The workspace does not exist.
  • Processing: An asynchronous operation has not yet completed.
  • Training: The workspace is training based on new data such as intents or examples.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail.

webhooks

array

intents

array

An array of intents.

entities

array

An array of objects describing the entities for the workspace.

counts

WorkspaceCounts

An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Request Body

UpdateWorkspace

Valid data defining the new and updated workspace content.

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

name

string

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

description

string

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

language

string

The language of the workspace.

workspace_id

string

The workspace ID of the workspace.

dialog_nodes

array

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

counterexamples

array

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

metadata

object

Any metadata related to the workspace.

learning_opt_out

boolean

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

system_settings

WorkspaceSystemSettings

Global settings for the workspace.

tooling

WorkspaceSystemSettingsTooling

Workspace settings related to the Watson Assistant user interface.

disambiguation

WorkspaceSystemSettingsDisambiguation

Workspace settings related to the disambiguation feature.

human_agent_assist

object

For internal use only.

spelling_suggestions

boolean

Whether spelling correction is enabled for the workspace.

spelling_auto_correct

boolean

Whether autocorrection is enabled for the workspace. If spelling correction is enabled and this property is `false`, any suggested corrections are returned in the suggested_text property of the message response. If this property is `true`, any corrections are automatically applied to the user input, and the original text is returned in the original_text property of the message response.

system_entities

WorkspaceSystemSettingsSystemEntities

Workspace settings related to the behavior of system entities.

off_topic

WorkspaceSystemSettingsOffTopic

Workspace settings related to detection of irrelevant input.

auto_learn

object

For internal use only.

nlp

WorkspaceSystemSettingsNlp

Workspace settings related to the version of the training algorithms currently used by the skill.

status

string

The current status of the workspace:

  • Available: The workspace is available and ready to process messages.
  • Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
  • Non Existent: The workspace does not exist.
  • Processing: An asynchronous operation has not yet completed.
  • Training: The workspace is training based on new data such as intents or examples.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail.

webhooks

array

intents

array

An array of objects defining the intents for the workspace.

entities

array

An array of objects describing the entities for the workspace.

Path Parameters

Query Parameters

append

boolean

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

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

include_audit

boolean

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

Response

200 - Successful request.

name

string

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

description

string

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

language

string

The language of the workspace.

workspace_id

string

The workspace ID of the workspace.

dialog_nodes

array

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

counterexamples

array

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

metadata

object

Any metadata related to the workspace.

learning_opt_out

boolean

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

system_settings

WorkspaceSystemSettings

Global settings for the workspace.

status

string

The current status of the workspace:

  • Available: The workspace is available and ready to process messages.
  • Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
  • Non Existent: The workspace does not exist.
  • Processing: An asynchronous operation has not yet completed.
  • Training: The workspace is training based on new data such as intents or examples.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail.

webhooks

array

intents

array

An array of intents.

entities

array

An array of objects describing the entities for the workspace.

counts

WorkspaceCounts

An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Delete workspace

DELETE /v1/workspaces/{workspace_id}

Delete a workspace from the service instance.

Request

Response

200 - Successful request.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Request Body

MessageRequest

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

input

MessageInput

An input object that includes the input text.

text

string

The text of the user input. This string cannot contain carriage return, newline, or tab characters.

spelling_suggestions

boolean

Whether to use spelling correction when processing the input. This property overrides the value of the spelling_suggestions property in the workspace settings.

spelling_auto_correct

boolean

Whether to use autocorrection when processing the input. If spelling correction is used and this property is `false`, any suggested corrections are returned in the suggested_text property of the message response. If this property is `true`, any corrections are automatically applied to the user input, and the original text is returned in the original_text property of the message response. This property overrides the value of the spelling_auto_correct property in the workspace settings.

suggested_text

string

Any suggested corrections of the input text. This property is returned only if spelling correction is enabled and autocorrection is disabled.

original_text

string

The original user input text. This property is returned only if autocorrection is enabled and the user input was corrected.

intents

array

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

entities

array

Entities to use when evaluating the message. Include entities from the previous response to continue using those entities rather than detecting entities in the new input.

alternate_intents

boolean

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

context

Context

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

conversation_id

string

The unique identifier of the conversation. The conversation ID cannot contain any of the following characters: `+` `=` `&&` `||` `>` `<` `!` `(` `)` `{` `}` `[` `]` `^` `"` `~` `*` `?` `:` `&#x60; `/`

system

object

For internal use only.

metadata

MessageContextMetadata

Metadata related to the message.

output

OutputData

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

nodes_visited

array

An array of the nodes that were triggered to create the response, in the order in which they were visited. This information is useful for debugging and for tracing the path taken through the node tree.

nodes_visited_details

array

An array of objects containing detailed diagnostic information about the nodes that were triggered during processing of the input message. Included only if nodes_visited_details is set to `true` in the message request.

log_messages

Required *

array

An array of up to 50 messages logged with the request.

generic

array

Output intended for any channel. It is the responsibility of the client application to implement the supported response types.

actions

array

An array of objects describing any actions requested by the dialog node.

user_id

string

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

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

Path Parameters

workspace_id

Required *

string

Unique identifier of the workspace.

Query Parameters

version

Required *

string

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

nodes_visited_details

boolean

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

Response

200 - Successful request.

input

MessageInput

An input object that includes the input text.

intents

array

An array of intents recognized in the user input, sorted in descending order of confidence

entities

array

An array of entities identified in the user input.

alternate_intents

boolean

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

context

Context

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

output

OutputData

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

actions

array

An array of objects describing any actions requested by the dialog node.

user_id

string

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

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

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Path Parameters

Query Parameters

sort

string

How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (`-`).

filter

string

A cacheable parameter that limits the results to those matching the specified filter. For more information, see the documentation.

page_limit

integer

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

Note: If the API is not returning your data, try lowering the page_limit value.

cursor

string

A token identifying the page of results to retrieve.

Response

200 - Successful request.

logs

array

An array of objects describing log events.

pagination

LogPagination

The pagination data for the returned objects. For more information about using pagination, see Pagination.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Path Parameters

Query Parameters

filter

Required *

string

A cacheable parameter that limits the results to those matching the specified filter. You must specify a filter query that includes a value for `language`, as well as a value for `request.context.system.assistant_id`, `workspace_id`, or `request.context.metadata.deployment`. These required filters must be specified using the exact match (`::`) operator. For more information, see the documentation.

sort

string

How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (`-`).

page_limit

integer

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

cursor

string

A token identifying the page of results to retrieve.

Response

200 - Successful request.

logs

array

An array of objects describing log events.

pagination

LogPagination

The pagination data for the returned objects. For more information about using pagination, see Pagination.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Request Body

BulkClassifyInput

An input object that includes the text to classify.

input

Required *

array

An array of input utterances to classify.

Path Parameters

workspace_id

Required *

string

Unique identifier of the workspace.

Query Parameters

version

Required *

string

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

Response

200 - Successful request.

output

array

An array of objects that contain classification information for the submitted input utterances.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

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

Path Parameters

Query Parameters

customer_id

Required *

string

The customer ID for which all data is to be deleted.

Response

202 - The request to delete data was successfully submitted.

400 - Bad Request. The request did not pass a customer ID:

  • `No customer ID found in the request`

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Create workspace asynchronously

POST /v1/workspaces_async

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

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

Request

Request Body

CreateWorkspace

name

string

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

description

string

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

language

string

The language of the workspace.

workspace_id

string

The workspace ID of the workspace.

dialog_nodes

array

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

counterexamples

array

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

metadata

object

Any metadata related to the workspace.

learning_opt_out

boolean

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

system_settings

WorkspaceSystemSettings

Global settings for the workspace.

tooling

WorkspaceSystemSettingsTooling

Workspace settings related to the Watson Assistant user interface.

disambiguation

WorkspaceSystemSettingsDisambiguation

Workspace settings related to the disambiguation feature.

human_agent_assist

object

For internal use only.

spelling_suggestions

boolean

Whether spelling correction is enabled for the workspace.

spelling_auto_correct

boolean

Whether autocorrection is enabled for the workspace. If spelling correction is enabled and this property is `false`, any suggested corrections are returned in the suggested_text property of the message response. If this property is `true`, any corrections are automatically applied to the user input, and the original text is returned in the original_text property of the message response.

system_entities

WorkspaceSystemSettingsSystemEntities

Workspace settings related to the behavior of system entities.

off_topic

WorkspaceSystemSettingsOffTopic

Workspace settings related to detection of irrelevant input.

auto_learn

object

For internal use only.

nlp

WorkspaceSystemSettingsNlp

Workspace settings related to the version of the training algorithms currently used by the skill.

status

string

The current status of the workspace:

  • Available: The workspace is available and ready to process messages.
  • Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
  • Non Existent: The workspace does not exist.
  • Processing: An asynchronous operation has not yet completed.
  • Training: The workspace is training based on new data such as intents or examples.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail.

webhooks

array

intents

array

An array of objects defining the intents for the workspace.

entities

array

An array of objects describing the entities for the workspace.

Response

202 - Successful request

name

string

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

description

string

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

language

string

The language of the workspace.

workspace_id

string

The workspace ID of the workspace.

dialog_nodes

array

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

counterexamples

array

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

metadata

object

Any metadata related to the workspace.

learning_opt_out

boolean

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

system_settings

WorkspaceSystemSettings

Global settings for the workspace.

status

string

The current status of the workspace:

  • Available: The workspace is available and ready to process messages.
  • Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
  • Non Existent: The workspace does not exist.
  • Processing: An asynchronous operation has not yet completed.
  • Training: The workspace is training based on new data such as intents or examples.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail.

webhooks

array

intents

array

An array of intents.

entities

array

An array of objects describing the entities for the workspace.

counts

WorkspaceCounts

An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Update workspace asynchronously

POST /v1/workspaces_async/{workspace_id}

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

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

Request

Request Body

UpdateWorkspace

Valid data defining the new and updated workspace content.

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

name

string

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

description

string

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

language

string

The language of the workspace.

workspace_id

string

The workspace ID of the workspace.

dialog_nodes

array

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

counterexamples

array

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

metadata

object

Any metadata related to the workspace.

learning_opt_out

boolean

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

system_settings

WorkspaceSystemSettings

Global settings for the workspace.

tooling

WorkspaceSystemSettingsTooling

Workspace settings related to the Watson Assistant user interface.

disambiguation

WorkspaceSystemSettingsDisambiguation

Workspace settings related to the disambiguation feature.

human_agent_assist

object

For internal use only.

spelling_suggestions

boolean

Whether spelling correction is enabled for the workspace.

spelling_auto_correct

boolean

Whether autocorrection is enabled for the workspace. If spelling correction is enabled and this property is `false`, any suggested corrections are returned in the suggested_text property of the message response. If this property is `true`, any corrections are automatically applied to the user input, and the original text is returned in the original_text property of the message response.

system_entities

WorkspaceSystemSettingsSystemEntities

Workspace settings related to the behavior of system entities.

off_topic

WorkspaceSystemSettingsOffTopic

Workspace settings related to detection of irrelevant input.

auto_learn

object

For internal use only.

nlp

WorkspaceSystemSettingsNlp

Workspace settings related to the version of the training algorithms currently used by the skill.

status

string

The current status of the workspace:

  • Available: The workspace is available and ready to process messages.
  • Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
  • Non Existent: The workspace does not exist.
  • Processing: An asynchronous operation has not yet completed.
  • Training: The workspace is training based on new data such as intents or examples.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail.

webhooks

array

intents

array

An array of objects defining the intents for the workspace.

entities

array

An array of objects describing the entities for the workspace.

Path Parameters

Query Parameters

append

boolean

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

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

Response

202 - Successful request.

name

string

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

description

string

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

language

string

The language of the workspace.

workspace_id

string

The workspace ID of the workspace.

dialog_nodes

array

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

counterexamples

array

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

metadata

object

Any metadata related to the workspace.

learning_opt_out

boolean

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

system_settings

WorkspaceSystemSettings

Global settings for the workspace.

status

string

The current status of the workspace:

  • Available: The workspace is available and ready to process messages.
  • Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
  • Non Existent: The workspace does not exist.
  • Processing: An asynchronous operation has not yet completed.
  • Training: The workspace is training based on new data such as intents or examples.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail.

webhooks

array

intents

array

An array of intents.

entities

array

An array of objects describing the entities for the workspace.

counts

WorkspaceCounts

An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.

Export workspace asynchronously

GET /v1/workspaces_async/{workspace_id}/export

Export the entire workspace asynchronously, including all workspace content.

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

Request

Path Parameters

Query Parameters

include_audit

boolean

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

sort

string

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

verbose

boolean

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

Response

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

name

string

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

description

string

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

language

string

The language of the workspace.

workspace_id

string

The workspace ID of the workspace.

dialog_nodes

array

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

counterexamples

array

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

metadata

object

Any metadata related to the workspace.

learning_opt_out

boolean

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

system_settings

WorkspaceSystemSettings

Global settings for the workspace.

status

string

The current status of the workspace:

  • Available: The workspace is available and ready to process messages.
  • Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
  • Non Existent: The workspace does not exist.
  • Processing: An asynchronous operation has not yet completed.
  • Training: The workspace is training based on new data such as intents or examples.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail.

webhooks

array

intents

array

An array of intents.

entities

array

An array of objects describing the entities for the workspace.

counts

WorkspaceCounts

An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.

202 - Request to export workspace has been accepted successfully.

name

string

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

description

string

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

language

string

The language of the workspace.

workspace_id

string

The workspace ID of the workspace.

dialog_nodes

array

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

counterexamples

array

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

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

metadata

object

Any metadata related to the workspace.

learning_opt_out

boolean

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

system_settings

WorkspaceSystemSettings

Global settings for the workspace.

status

string

The current status of the workspace:

  • Available: The workspace is available and ready to process messages.
  • Failed: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
  • Non Existent: The workspace does not exist.
  • Processing: An asynchronous operation has not yet completed.
  • Training: The workspace is training based on new data such as intents or examples.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail.

webhooks

array

intents

array

An array of intents.

entities

array

An array of objects describing the entities for the workspace.

counts

WorkspaceCounts

An object containing properties that indicate how many intents, entities, and dialog nodes are defined in the workspace. This property is included only in responses from the Export workspace asynchronously method, and only when the verbose query parameter is set to `true`.

400 - Invalid request.

error

string

General description of an error.

errors

array

Collection of specific constraint violations associated with the error.

code

integer

HTTP status code for the error response.