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