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