Create a conversational skill provider

POST /v2/providers

Create a new conversational skill provider.

Request

Request Body

Provider

The properties of the new conversational skill provider.

provider_id

Required *

string

The unique identifier of the provider.

specification

Required *

ProviderSpecification

The specification of the provider.

servers

Required *

array

An array of objects defining all endpoints of the provider.

Note: Multiple array items are reserved for future use.

components

object

An object defining various reusable definitions of the provider.

private

Required *

ProviderPrivate

Private information of the provider.

authentication

Required *

object

Private authentication information of the provider.

Path Parameters

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 `2024-08-25`.

Response

200 - Successful request.

provider_id

string

The unique identifier of the provider.

specification

object

The specification of the provider.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

List conversational skill providers

GET /v2/providers

List the conversational skill providers associated with a Watson Assistant service instance.

Request

Path Parameters

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 `2024-08-25`.

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 conversational skill providers 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.

conversational_skill_providers

array

An array of objects describing the conversational skill providers associated with the 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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Update a conversational skill provider

POST /v2/providers/{provider_id}

Update a new conversational skill provider.

Request

Request Body

UpdateProvider

The properties of the new conversational skill provider.

specification

Required *

ProviderSpecification

The specification of the provider.

servers

Required *

array

An array of objects defining all endpoints of the provider.

Note: Multiple array items are reserved for future use.

components

object

An object defining various reusable definitions of the provider.

private

Required *

ProviderPrivate

Private information of the provider.

authentication

Required *

object

Private authentication information of the provider.

Path Parameters

provider_id

Required *

string

Unique identifier of the conversational skill provider.

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 `2024-08-25`.

Response

200 - Successful request.

provider_id

string

The unique identifier of the provider.

specification

object

The specification of the provider.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Create an assistant

POST /v2/assistants

Create a new assistant.

Request

Request Body

AssistantData

The properties of the new assistant.

assistant_id

Required *

string

The unique identifier of the assistant.

name

string

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

description

string

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

language

Required *

string

The language of the assistant.

assistant_skills

Required *

array

An array of skill references identifying the skills associated with the assistant.

assistant_environments

Required *

array

An array of objects describing the environments defined for the assistant.

Path Parameters

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 `2024-08-25`.

Response

200 - Successful request.

assistant_id

string

The unique identifier of the assistant.

name

string

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

description

string

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

language

string

The language of the assistant.

assistant_skills

array

An array of skill references identifying the skills associated with the assistant.

assistant_environments

array

An array of objects describing the environments defined for the assistant.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

List assistants

GET /v2/assistants

List the assistants associated with a watsonx Assistant service instance.

Request

Path Parameters

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 `2024-08-25`.

page_limit

integer

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

include_count

boolean

sort

string

The attribute by which returned assistants 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.

assistants

array

An array of objects describing the assistants associated with the 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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Delete assistant

DELETE /v2/assistants/{assistant_id}

Delete an assistant.

Request

Path Parameters

assistant_id

Required *

string

Unique identifier of the assistant. To get the assistant ID in the watsonx Assistant interface, open the Assistant settings page, and scroll to the Assistant IDs and API details section and click View Details.

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 `2024-08-25`.

Response

200 - Successful request.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Send user input to assistant (stateful)

POST /v2/assistants/{assistant_id}/environments/{environment_id}/sessions/{session_id}/message

Send user input to an assistant and receive a response, with conversation state (including context data) stored by watsonx Assistant for the duration of the session.

Request

Request Body

MessageRequest

The message to be sent. This includes the user's input, along with optional content such as intents and entities.

input

MessageInput

An input object that includes the input text.

message_type

string

The type of the message:

`text`: The user input is processed normally by the assistant.
`search`: Only search results are returned. (Any dialog or action skill is bypassed.)

Note: A `search` message results in an error if no search skill is configured for the assistant.

text

string

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

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.

suggestion_id

string

For internal use only.

attachments

array

An array of multimedia attachments to be sent with the message. Attachments are not processed by the assistant itself, but can be sent to external services by webhooks.

Note: Attachments are not supported on IBM Cloud Pak for Data.

analytics

RequestAnalytics

An optional object containing analytics data. Currently, this data is used only for events sent to the Segment extension.

options

object

Optional properties that control how the assistant responds.

context

object

Context data for the conversation. You can use this property to set or modify context variables, which can also be accessed by dialog nodes. The context is stored by the assistant on a per-session basis.

Note: The total size of the context data stored for a stateful session cannot exceed 100KB.

global

object

Session context data that is shared by all skills used by the assistant.

skills

object

Context data specific to particular skills used by the assistant.

integrations

object

An object containing context data that is specific to particular integrations. For more information, see the documentation.

user_id

string

A string value that identifies the user who is interacting with the assistant. 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.global.session_id.

Note: This property is the same as the user_id property in the global system context. If user_id is specified in both locations, the value specified at the root is used.

Path Parameters

assistant_id

Required *

string

environment_id

Required *

string

Unique identifier of the environment. To find the environment ID in the watsonx Assistant user interface, open the environment settings and click API Details. Note: Currently, the API does not support creating environments.

session_id

Required *

string

Unique identifier of the session.

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 `2024-08-25`.

Response

200 - Successful request.

output

MessageOutput

Assistant output to be rendered or processed by the client.

context

object

Context data for the conversation. You can use this property to access context variables. The context is stored by the assistant on a per-session basis.

Note: The context is included in message responses only if return_context=`true` in the message request. Full context is always included in logs.

user_id

string

Note: This property is the same as the user_id property in the global system context.

masked_output

MaskedOutput

Assistant output to be rendered or processed by the client.

masked_input

MaskedInput

An input object that includes the input text.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Send user input to assistant (stateless)

POST /v2/assistants/{assistant_id}/environments/{environment_id}/message

Send user input to an assistant and receive a response, with conversation state (including context data) managed by your application.

Request

Request Body

StatelessMessageRequest

The message to be sent. This includes the user's input, context data, and optional content such as intents and entities.

input

StatelessMessageInput

An input object that includes the input text.

message_type

string

The type of the message:

`text`: The user input is processed normally by the assistant.
`search`: Only search results are returned. (Any dialog or action skill is bypassed.)

Note: A `search` message results in an error if no search skill is configured for the assistant.

text

string

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

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.

suggestion_id

string

For internal use only.

attachments

array

An array of multimedia attachments to be sent with the message. Attachments are not processed by the assistant itself, but can be sent to external services by webhooks.

Note: Attachments are not supported on IBM Cloud Pak for Data.

analytics

RequestAnalytics

An optional object containing analytics data. Currently, this data is used only for events sent to the Segment extension.

options

object

Optional properties that control how the assistant responds.

context

object

Context data for the conversation. You can use this property to set or modify context variables, which can also be accessed by dialog nodes. The context is not stored by the assistant. To maintain session state, include the context from the previous response.

Note: The total size of the context data for a stateless session cannot exceed 250KB.

global

object

Session context data that is shared by all skills used by the assistant.

skills

object

Context data specific to particular skills used by the assistant.

integrations

object

An object containing context data that is specific to particular integrations. For more information, see the documentation.

user_id

string

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

Path Parameters

assistant_id

Required *

string

environment_id

Required *

string

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 `2024-08-25`.

Response

200 - Successful request.

output

MessageOutput

Assistant output to be rendered or processed by the client.

context

object

Context data for the conversation. You can use this property to access context variables. The context is not stored by the assistant; to maintain session state, include the context from the response in the next message.

masked_output

MaskedOutput

Assistant output to be rendered or processed by the client.

masked_input

MaskedInput

An input object that includes the input text.

user_id

string

Note: This property is the same as the user_id property in the global system context.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Send user input to assistant (stateful)

POST /v2/assistants/{assistant_id}/environments/{environment_id}/sessions/{session_id}/message_stream

Send user input to an assistant and receive a streamed response, with conversation state (including context data) stored by watsonx Assistant for the duration of the session.

Request

Request Body

MessageRequest

The message to be sent. This includes the user's input, along with optional content such as intents and entities.

input

MessageInput

An input object that includes the input text.

message_type

string

The type of the message:

`text`: The user input is processed normally by the assistant.
`search`: Only search results are returned. (Any dialog or action skill is bypassed.)

Note: A `search` message results in an error if no search skill is configured for the assistant.

text

string

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

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.

suggestion_id

string

For internal use only.

attachments

array

An array of multimedia attachments to be sent with the message. Attachments are not processed by the assistant itself, but can be sent to external services by webhooks.

Note: Attachments are not supported on IBM Cloud Pak for Data.

analytics

RequestAnalytics

An optional object containing analytics data. Currently, this data is used only for events sent to the Segment extension.

options

object

Optional properties that control how the assistant responds.

context

object

Note: The total size of the context data stored for a stateful session cannot exceed 100KB.

global

object

Session context data that is shared by all skills used by the assistant.

skills

object

Context data specific to particular skills used by the assistant.

integrations

object

An object containing context data that is specific to particular integrations. For more information, see the documentation.

user_id

string

Note: This property is the same as the user_id property in the global system context. If user_id is specified in both locations, the value specified at the root is used.

Path Parameters

assistant_id

Required *

string

environment_id

Required *

string

session_id

Required *

string

Unique identifier of the session.

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 `2024-08-25`.

Response

200 - Successful request.

Send user input to assistant (stateless)

POST /v2/assistants/{assistant_id}/environments/{environment_id}/message_stream

Send user input to an assistant and receive a response, with conversation state (including context data) managed by your application.

Request

Request Body

MessageRequest

The message to be sent. This includes the user's input, along with optional content such as intents and entities.

input

MessageInput

An input object that includes the input text.

message_type

string

The type of the message:

`text`: The user input is processed normally by the assistant.
`search`: Only search results are returned. (Any dialog or action skill is bypassed.)

Note: A `search` message results in an error if no search skill is configured for the assistant.

text

string

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

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.

suggestion_id

string

For internal use only.

attachments

array

An array of multimedia attachments to be sent with the message. Attachments are not processed by the assistant itself, but can be sent to external services by webhooks.

Note: Attachments are not supported on IBM Cloud Pak for Data.

analytics

RequestAnalytics

An optional object containing analytics data. Currently, this data is used only for events sent to the Segment extension.

options

object

Optional properties that control how the assistant responds.

context

object

Note: The total size of the context data stored for a stateful session cannot exceed 100KB.

global

object

Session context data that is shared by all skills used by the assistant.

skills

object

Context data specific to particular skills used by the assistant.

integrations

object

An object containing context data that is specific to particular integrations. For more information, see the documentation.

user_id

string

Note: This property is the same as the user_id property in the global system context. If user_id is specified in both locations, the value specified at the root is used.

Path Parameters

assistant_id

Required *

string

environment_id

Required *

string

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 `2024-08-25`.

Response

200 - Successful request.

Create a session

POST /v2/assistants/{assistant_id}/environments/{environment_id}/sessions

Create a new session. A session is used to send user input to a skill and receive responses. It also maintains the state of the conversation. A session persists until it is deleted, or until it times out because of inactivity. (For more information, see the documentation.)

Request

Request Body

CreateSession

analytics

RequestAnalytics

An optional object containing analytics data. Currently, this data is used only for events sent to the Segment extension.

browser

string

The browser that was used to send the message that triggered the event.

device

string

The type of device that was used to send the message that triggered the event.

pageUrl

string

The URL of the web page that was used to send the message that triggered the event.

Response

201 - Successful request.

session_id

string

The session ID.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Delete session

DELETE /v2/assistants/{assistant_id}/environments/{environment_id}/sessions/{session_id}

Deletes a session explicitly before it times out. (For more information about the session inactivity timeout, see the documentation).

Request

Response

200 - Successful request.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Pagination.">

List log events for an assistant

GET /v2/assistants/{assistant_id}/logs

List the events from the log of an assistant.

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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

List environments

GET /v2/assistants/{assistant_id}/environments

List the environments associated with an assistant.

Request

Path Parameters

Query Parameters

page_limit

integer

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

include_count

boolean

sort

string

The attribute by which returned environments 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.

environments

array

An array of objects describing the environments associated with an assistant.

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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Get environment

GET /v2/assistants/{assistant_id}/environments/{environment_id}

Get information about an environment. For more information about environments, see Environments.

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.

name

string

The name of the environment.

description

string

The description of the environment.

assistant_id

string

The assistant ID of the assistant the environment is associated with.

environment_id

string

The environment ID of the environment.

environment

string

The type of the environment. All environments other than the `draft` and `live` environments have the type `staging`.

release_reference

object

An object describing the release that is currently deployed in the environment.

orchestration

object

The search skill orchestration settings for the environment.

session_timeout

integer

The session inactivity timeout setting for the environment (in seconds).

integration_references

array

An array of objects describing the integrations that exist in the environment.

skill_references

array

An array of objects identifying the skills (such as action and dialog) that exist in the environment.

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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Update environment

POST /v2/assistants/{assistant_id}/environments/{environment_id}

Update an environment with new or modified data. For more information about environments, see Environments.

Request

Request Body

UpdateEnvironment

The updated properties of the environment.

name

string

The name of the environment.

description

string

The description of the environment.

assistant_id

string

The assistant ID of the assistant the environment is associated with.

environment_id

string

The environment ID of the environment.

environment

string

The type of the environment. All environments other than the `draft` and `live` environments have the type `staging`.

release_reference

object

An object describing the release that is currently deployed in the environment.

release

string

The name of the deployed release.

orchestration

object

The search skill orchestration settings for the environment.

search_skill_fallback

boolean

Whether to fall back to a search skill when responding to messages that do not match any intent or action defined in dialog or action skills. (If no search skill is configured for the environment, this property is ignored.)

session_timeout

integer

The session inactivity timeout setting for the environment (in seconds).

integration_references

array

An array of objects describing the integrations that exist in the environment.

skill_references

array

An array of objects identifying the skills (such as action and dialog) that exist in the environment.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Response

200 - Successful request.

name

string

The name of the environment.

description

string

The description of the environment.

assistant_id

string

The assistant ID of the assistant the environment is associated with.

environment_id

string

The environment ID of the environment.

environment

string

The type of the environment. All environments other than the `draft` and `live` environments have the type `staging`.

release_reference

object

An object describing the release that is currently deployed in the environment.

orchestration

object

The search skill orchestration settings for the environment.

session_timeout

integer

The session inactivity timeout setting for the environment (in seconds).

integration_references

array

An array of objects describing the integrations that exist in the environment.

skill_references

array

An array of objects identifying the skills (such as action and dialog) that exist in the environment.

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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Create release

POST /v2/assistants/{assistant_id}/releases

Create a new release using the current content of the dialog and action skills in the draft environment. (In the watsonx Assistant user interface, a release is called a version.)

Request

Request Body

Release

An object describing the release.

release

string

The name of the release. The name is the version number (an integer), returned as a string.

description

string

The description of the release.

environment_references

array

An array of objects describing the environments where this release has been deployed.

content

object

An object identifying the versionable content objects (such as skill snapshots) that are included in the release.

skills

array

The skill snapshots that are included in the release.

status

string

The current status of the release:

Available: The release is available for deployment.
Failed: An asynchronous publish operation has failed.
Processing: An asynchronous publish operation has not yet completed.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

Response

202 - Request to create release has been accepted successfully.

release

string

The name of the release. The name is the version number (an integer), returned as a string.

description

string

The description of the release.

environment_references

array

An array of objects describing the environments where this release has been deployed.

content

object

An object identifying the versionable content objects (such as skill snapshots) that are included in the release.

status

string

The current status of the release:

Available: The release is available for deployment.
Failed: An asynchronous publish operation has failed.
Processing: An asynchronous publish operation has not yet completed.

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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

List releases

GET /v2/assistants/{assistant_id}/releases

List the releases associated with an assistant. (In the watsonx Assistant user interface, a release is called a version.)

Request

Path Parameters

Query Parameters

page_limit

integer

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

include_count

boolean

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.

releases

array

An array of objects describing the releases associated with an assistant.

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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Get release

GET /v2/assistants/{assistant_id}/releases/{release}

Get information about a release.

Release data is not available until publishing of the release completes. If publishing is still in progress, 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 release data.

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. Note that this does not mean that the asynchronous create operation has completed or was successful. Check the value of the status property to determine the status of the operation.

release

string

The name of the release. The name is the version number (an integer), returned as a string.

description

string

The description of the release.

environment_references

array

An array of objects describing the environments where this release has been deployed.

content

object

An object identifying the versionable content objects (such as skill snapshots) that are included in the release.

status

string

The current status of the release:

Available: The release is available for deployment.
Failed: An asynchronous publish operation has failed.
Processing: An asynchronous publish operation has not yet completed.

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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Delete release

DELETE /v2/assistants/{assistant_id}/releases/{release}

Delete a release. (In the watsonx Assistant user interface, a release is called a version.)

Request

Response

200 - Successful request.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Deploy release

POST /v2/assistants/{assistant_id}/releases/{release}/deploy

Update the environment with the content of the release. All snapshots saved as part of the release become active in the environment.

Request

Request Body

DeployReleaseRequest

An input object that identifies the environment where the release is to be deployed.

environment_id

Required *

string

The environment ID of the environment where the release is to be deployed.

Path Parameters

Query Parameters

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

description

string

The description of the environment.

assistant_id

string

The assistant ID of the assistant the environment is associated with.

environment_id

string

The environment ID of the environment.

environment

string

The type of the environment. All environments other than the `draft` and `live` environments have the type `staging`.

release_reference

object

An object describing the release that is currently deployed in the environment.

orchestration

object

The search skill orchestration settings for the environment.

session_timeout

integer

The session inactivity timeout setting for the environment (in seconds).

integration_references

array

An array of objects describing the integrations that exist in the environment.

skill_references

array

An array of objects identifying the skills (such as action and dialog) that exist in the environment.

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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Get skill

GET /v2/assistants/{assistant_id}/skills/{skill_id}

Get information about a skill.

Request

Response

200 - Successful request.

name

string

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

description

string

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

workspace

object

An object containing the conversational content of an action or dialog skill.

skill_id

string

The skill ID of the skill.

status

string

The current status of the skill:

Available: The skill 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 skill does not exist.
Processing: An asynchronous operation has not yet completed.
Training: The skill is training based on new data.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail. Included only if status=`Failed`.

status_description

string

The description of the failed asynchronous operation. Included only if status=`Failed`.

dialog_settings

object

For internal use only.

assistant_id

string

The unique identifier of the assistant the skill is associated with.

workspace_id

string

The unique identifier of the workspace that contains the skill content. Included only for action and dialog skills.

environment_id

string

The unique identifier of the environment where the skill is defined. For action and dialog skills, this is always the draft environment.

valid

boolean

Whether the skill is structurally valid.

next_snapshot_version

string

The name that will be given to the next snapshot that is created for the skill. A snapshot of each versionable skill is saved for each new release of an assistant.

search_settings

SearchSettings

An object describing the search skill configuration.

Note: Search settings are not supported in Import skills requests, and are not included in Export skills responses.

warnings

array

An array of warnings describing errors with the search skill configuration. Included only for search skills.

language

string

The language of the skill.

type

string

The type of skill.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Update skill

POST /v2/assistants/{assistant_id}/skills/{skill_id}

Update a skill with new or modified data.

**Note:** The update is performed asynchronously; you can see the status of the update by calling the **Get skill** method and checking the value of the **status** property.

Request

Request Body

UpdateSkill

The updated properties of the skill.

name

string

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

description

string

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

workspace

object

An object containing the conversational content of an action or dialog skill.

skill_id

string

The skill ID of the skill.

status

string

The current status of the skill:

Available: The skill 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 skill does not exist.
Processing: An asynchronous operation has not yet completed.
Training: The skill is training based on new data.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail. Included only if status=`Failed`.

status_description

string

The description of the failed asynchronous operation. Included only if status=`Failed`.

dialog_settings

object

For internal use only.

assistant_id

string

The unique identifier of the assistant the skill is associated with.

workspace_id

string

The unique identifier of the workspace that contains the skill content. Included only for action and dialog skills.

environment_id

string

The unique identifier of the environment where the skill is defined. For action and dialog skills, this is always the draft environment.

valid

boolean

Whether the skill is structurally valid.

next_snapshot_version

string

The name that will be given to the next snapshot that is created for the skill. A snapshot of each versionable skill is saved for each new release of an assistant.

search_settings

SearchSettings

An object describing the search skill configuration.

Note: Search settings are not supported in Import skills requests, and are not included in Export skills responses.

discovery

object

Configuration settings for the Watson Discovery service instance used by the search integration.

messages

Required *

object

The messages included with responses from the search integration.

schema_mapping

Required *

object

The mapping between fields in the Watson Discovery collection and properties in the search response.

elastic_search

object

Configuration settings for the Elasticsearch service used by the search integration. You can provide either basic auth or apiKey auth.

conversational_search

Required *

object

Configuration settings for conversational search.

server_side_search

object

Configuration settings for the server-side search service used by the search integration. You can provide either basic auth, apiKey auth or none.

client_side_search

object

Configuration settings for the client-side search service or server-side search service used by the search integration

warnings

array

An array of warnings describing errors with the search skill configuration. Included only for search skills.

Response

202 - Request to update skill has been accepted successfully.

name

string

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

description

string

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

workspace

object

An object containing the conversational content of an action or dialog skill.

skill_id

string

The skill ID of the skill.

status

string

The current status of the skill:

Available: The skill 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 skill does not exist.
Processing: An asynchronous operation has not yet completed.
Training: The skill is training based on new data.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail. Included only if status=`Failed`.

status_description

string

The description of the failed asynchronous operation. Included only if status=`Failed`.

dialog_settings

object

For internal use only.

assistant_id

string

The unique identifier of the assistant the skill is associated with.

workspace_id

string

The unique identifier of the workspace that contains the skill content. Included only for action and dialog skills.

environment_id

string

The unique identifier of the environment where the skill is defined. For action and dialog skills, this is always the draft environment.

valid

boolean

Whether the skill is structurally valid.

next_snapshot_version

string

The name that will be given to the next snapshot that is created for the skill. A snapshot of each versionable skill is saved for each new release of an assistant.

search_settings

SearchSettings

An object describing the search skill configuration.

Note: Search settings are not supported in Import skills requests, and are not included in Export skills responses.

warnings

array

An array of warnings describing errors with the search skill configuration. Included only for search skills.

language

string

The language of the skill.

type

string

The type of skill.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Export skills

GET /v2/assistants/{assistant_id}/skills_export

Asynchronously export the action skill and dialog skill (if enabled) for the assistant. Use this method to save all skill data from the draft environment so that you can import it to a different assistant using the Import skills method. Use `assistant_id` instead of `environment_id` to call this endpoint.

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 poll the status of the operation by calling the same request again and checking the value of the status property. If an error occurs (indicated by a status value of `Failed`), the `status_description` property provides more information about the error, and the `status_errors` property contains an array of error messages that caused the failure.

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.

Response

200 - Request to export skills has completed successfully.

assistant_skills

array

An array of objects describing the skills for the assistant. Included in responses only if status=`Available`.

assistant_state

AssistantState

Status information about the skills for the assistant. Included in responses only if status=`Available`.

202 - Request to export skills asynchronously has been accepted.

assistant_id

string

The assistant ID of the assistant.

status

string

The current status of the asynchronous operation:

`Available`: An asynchronous export is available.
`Completed`: An asynchronous import operation has completed successfully.
`Failed`: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
`Processing`: An asynchronous operation has not yet completed.

status_description

string

The description of the failed asynchronous operation. Included only if status=`Failed`.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail. Included only if status=`Failed`.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Import skills

POST /v2/assistants/{assistant_id}/skills_import

Asynchronously import skills into an existing assistant from a previously exported file. This method only imports assistants into a draft environment. Use `assistant_id` instead of `environment_id` to call this endpoint.

The request body for this method should contain the response data that was received from a previous call to the Export skills method, without modification.

A successful call to this method initiates an asynchronous import. The updated skills belonging to the assistant are not available until processing completes. To check the status of the asynchronous import operation, use the Get status of skills import method.

Request

Request Body

SkillsImport

An input object that contains the skills to import.

assistant_id

Required *

string

The assistant ID of the assistant.

status

Required *

string

The current status of the asynchronous operation:

`Available`: An asynchronous export is available.
`Completed`: An asynchronous import operation has completed successfully.
`Failed`: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
`Processing`: An asynchronous operation has not yet completed.

status_description

string

The description of the failed asynchronous operation. Included only if status=`Failed`.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail. Included only if status=`Failed`.

assistant_skills

Required *

array

An array of objects describing the skills for the assistant. Included in responses only if status=`Available`.

assistant_state

Required *

AssistantState

Status information about the skills for the assistant. Included in responses only if status=`Available`.

action_disabled

Required *

boolean

Whether the action skill is disabled in the draft environment.

dialog_disabled

Required *

boolean

Whether the dialog skill is disabled in the draft environment.

Path Parameters

Query Parameters

include_audit

boolean

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

Response

202 - Request to import skills has been accepted successfully.

assistant_id

string

The assistant ID of the assistant.

status

string

The current status of the asynchronous operation:

`Available`: An asynchronous export is available.
`Completed`: An asynchronous import operation has completed successfully.
`Failed`: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
`Processing`: An asynchronous operation has not yet completed.

status_description

string

The description of the failed asynchronous operation. Included only if status=`Failed`.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail. Included only if status=`Failed`.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Get status of skills import

GET /v2/assistants/{assistant_id}/skills_import/status

Retrieve the status of an asynchronous import operation previously initiated by using the Import skills method.

Request

Response

200 - Successful request.

assistant_id

string

The assistant ID of the assistant.

status

string

The current status of the asynchronous operation:

`Available`: An asynchronous export is available.
`Completed`: An asynchronous import operation has completed successfully.
`Failed`: An asynchronous operation has failed. See the status_errors property for more information about the cause of the failure.
`Processing`: An asynchronous operation has not yet completed.

status_description

string

The description of the failed asynchronous operation. Included only if status=`Failed`.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail. Included only if status=`Failed`.

400 - Invalid request.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Identify intents and entities in multiple user utterances

POST /v2/skills/{skill_id}/workspace/bulk_classify

Send multiple user inputs to a dialog skill 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 skills or skill versions.

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

skill_id

Required *

string

Unique identifier of the skill. To find the action or dialog skill ID in the watsonx Assistant user interface, open the skill settings and click API Details. To find the search skill ID, use the Get environment API to retrieve the skill references for an environment and it will include the search skill info, if available.

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 `2024-08-25`.

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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

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 watsonx Assistant.">

Delete labeled data

DELETE /v2/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.

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.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific constraint violations associated with the error.

Create release export

POST /v2/assistants/{assistant_id}/releases/{release}/export

Initiate an asynchronous process which will create a downloadable Zip file artifact (/package) for an assistant release. This artifact will contain Action and/or Dialog skills that are part of the release. The Dialog skill will only be included in the event that coexistence is enabled on the assistant. The expected workflow with the use of Release Export endpoint is to first initiate the creation of the artifact with the POST endpoint and then poll the GET endpoint to retrieve the artifact. Once the artifact has been created, it will last for the duration (/scope) of the release.

Request

Response

200 - Successful request. The artifact creation might have succeeded or failed.

status

string

The current status of the release export creation process:

Available: The release export package is available for download.
Failed: The asynchronous release export package creation process has failed.
Processing: An asynchronous operation to create the release export package is underway and not yet completed.

task_id

string

A unique identifier for a background asynchronous task that is executing or has executed the operation.

assistant_id

string

The ID of the assistant to which the release belongs.

release

string

The name of the release. The name is the version number (an integer), returned as a string.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail. Included only if status=`Failed`.

status_description

string

The description of the failed asynchronous operation. Included only if status=`Failed`.

202 - Successful request that initiates the asynchronous process to create the release export package.

status

string

The current status of the release export creation process:

Available: The release export package is available for download.
Failed: The asynchronous release export package creation process has failed.
Processing: An asynchronous operation to create the release export package is underway and not yet completed.

task_id

string

A unique identifier for a background asynchronous task that is executing or has executed the operation.

assistant_id

string

The ID of the assistant to which the release belongs.

release

string

The name of the release. The name is the version number (an integer), returned as a string.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

404 - Unsuccessful request. Might indicate that one or more route parameters provided are wrong.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

425 - The release is not yet ready. Please try to create an export once the release is ready.

Get release export

GET /v2/assistants/{assistant_id}/releases/{release}/export

A dual function endpoint to either retrieve the Zip file artifact that is associated with an assistant release or, retrieve the status of the artifact's creation. It is assumed that the artifact creation was already initiated prior to calling this endpoint. In the event that the artifact is not yet created and ready for download, this endpoint can be used to poll the system until the creation is completed or has failed. On the other hand, if the artifact is created, this endpoint will return the Zip file artifact as an octet stream. Once the artifact has been created, it will last for the duration (/scope) of the release. <br /><br /> When you will have downloaded the Zip file artifact, you have one of three ways to import it into an assistant's draft environment. These are as follows. <br /><ol><li>Import the zip package in Tooling via <var>"Assistant Settings" -> "Download/Upload files" -> "Upload" -> "Assistant only"</var>.</li><li>Import the zip package via "Create release import" endpoint using the APIs.</li><li>Extract the contents of the Zip file artifact and individually import the skill JSONs via skill update endpoints.</li></ol>

Request

Response

200 - Successful request. Either retrieves the status of an on-going asynchronous process which is creating the Zip file artifact or, provides the artifact as in an octet stream response.

status

string

The current status of the release export creation process:

Available: The release export package is available for download.
Failed: The asynchronous release export package creation process has failed.
Processing: An asynchronous operation to create the release export package is underway and not yet completed.

task_id

string

A unique identifier for a background asynchronous task that is executing or has executed the operation.

assistant_id

string

The ID of the assistant to which the release belongs.

release

string

The name of the release. The name is the version number (an integer), returned as a string.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail. Included only if status=`Failed`.

status_description

string

The description of the failed asynchronous operation. Included only if status=`Failed`.

404 - Unsuccessful request. Might indicate that one or more route parameters provided are wrong or, that the creation of the artifact has never been initiated for the assistant release.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

Create release import

POST /v2/assistants/{assistant_id}/import

Import a previously exported assistant release Zip file artifact (/package) into an assistant. This endpoint creates (/initiates) an asynchronous task (/job) in the background which will import the artifact contents into the draft environment of the assistant on which this endpoint is called. Specifically, the asynchronous operation will override the action and/or dialog skills in the assistant. It will be worth noting that when the artifact that is provided to this endpoint is from an assistant release which has coexistence enabled (i.e., it has both action and dialog skills), the import process will automatically enable coexistence, if not already enabled, on the assistant into which said artifact is being uploaded to. On the other hand, if the artifact package being imported only has action skill in it, the import asynchronous process will only override the draft environment's action skill, regardless of whether coexistence is enabled on the assistant into which the package is being imported. Lastly, the system will only run one asynchronous import at a time on an assistant. As such, consecutive imports will override previous import's updates to the skills in the draft environment. Once created, you may poll the completion of the import via the "Get release import Status" endpoint.

Request

Request Body

Request body is an Octet-stream of the artifact Zip file that is being imported.

Response

202 - Successful request that initiates the asynchronous process to import the release export artifact (/package).

status

string

The current status of the artifact import process:

Failed: The asynchronous artifact import process has failed.
Processing: An asynchronous operation to import artifact is underway and not yet completed.

task_id

string

A unique identifier for a background asynchronous task that is executing or has executed the operation.

assistant_id

string

The ID of the assistant to which the release belongs.

skill_impact_in_draft

array

An array of skill types in the draft environment which will be overridden with skills from the artifact being imported.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

400 - Unsuccessful request and indicates that something is wrong with the Zip file artifact that was provided.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

errors

array

Collection of specific errors or problems in the provided assistant release artifact.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

404 - Unsuccessful request. Might indicate that one or more route parameters provided are wrong.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

409 - Unsuccessful request indicating that another artifact import is already underway. Try again after some time.

error

string

General description of an error.

code

integer

HTTP status code for the error response.

413 - The artifact that was provided is too large.

415 - An invalid request indicating that the "content-type" header in the request is set to a value other than "application/octet-stream".

error

string

General description of an error.

code

integer

HTTP status code for the error response.

Get release import Status

GET /v2/assistants/{assistant_id}/import

Monitor the status of an assistant release import. You may poll this endpoint until the status of the import has either succeeded or failed.

Request

Response

200 - Successful request that either returns the status of the last import that was executed or, a presently executing import.

status

string

The current status of the release import process:

Completed: The artifact import has completed.
Failed: The asynchronous artifact import process has failed.
Processing: An asynchronous operation to import the artifact is underway and not yet completed.

task_id

string

A unique identifier for a background asynchronous task that is executing or has executed the operation.

assistant_id

string

The ID of the assistant to which the release belongs.

status_errors

array

An array of messages about errors that caused an asynchronous operation to fail. Included only if status=`Failed`.

status_description

string

The description of the failed asynchronous operation. Included only if status=`Failed`.

skill_impact_in_draft

array

An array of skill types in the draft environment which will be overridden with skills from the artifact being imported.

created

string

The timestamp for creation of the object.

updated

string

The timestamp for the most recent update to the object.

404 - Unsuccessful request. Might indicate that one or more route parameters provided are wrong or, a release import may never have been initiated on this assistant.

error

string

General description of an error.

code

integer

HTTP status code for the error response.