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

Parameters

assistantId

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.

environmentId

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.

sessionId

Required *

string

Unique identifier of the session.

input

MessageInput

An input object that includes the input text.

context

MessageContext

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.

userId

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.

Constraints:

  • Min length: 1
  • Max length: 256

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

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.

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

Parameters

assistantId

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.

environmentId

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.

input

StatelessMessageInput

An input object that includes the input text.

context

StatelessMessageContext

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.

userId

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 in a message request, the value specified at the root is used.

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

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.

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

Parameters

assistantId

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.

environmentId

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.

sessionId

Required *

string

Unique identifier of the session.

input

MessageInput

An input object that includes the input text.

context

MessageContext

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.

userId

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.

Constraints:

  • Min length: 1
  • Max length: 256

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

Parameters

assistantId

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.

environmentId

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.

input

MessageInput

An input object that includes the input text.

context

MessageContext

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.

userId

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.

Constraints:

  • Min length: 1
  • Max length: 256

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

Parameters

assistantId

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.

environmentId

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.

analytics

RequestAnalytics

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

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

Parameters

assistantId

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.

environmentId

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.

sessionId

Required *

string

Unique identifier of the session.

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

Parameters

assistantId

Required *

string

The assistant ID or the environment ID of the environment where the assistant is deployed, depending on the type of request:

  • For message, session, and log requests, specify the environment ID of the environment where the assistant is deployed.
  • For all other requests, specify the assistant ID of the assistant.

To find the environment ID or assistant ID in the watsonx Assistant user interface, open the assistant settings and scroll to the Environments section.

Note: If you are using the classic Watson Assistant experience, always use the assistant ID. To find the assistant ID in the user interface, open the assistant settings and click API Details.

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.

pageLimit

number

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

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

Default: 100

cursor

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.

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

Parameters

skillId

Required *

string

Unique identifier of the skill. To find the skill ID in the watsonx Assistant user interface, open the skill settings and click API Details.

input

Required *

BulkClassifyUtterance[]

An array of input utterances to classify.

Constraints:

  • Min items: 1
  • Max items: 50

Response

200 - Successful request.

output

array

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

400 - Invalid request.

error

string

General description of an error.

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.

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.

Request

Parameters

customerId

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.

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.