Introduction to IBM watsonx.ai as a Service Using IBM watsonx.ai as a Service APIs, you can run text inference, prompt tuning and more on Large Language Models LLM. If you are looking for the IBM watsonx.ai software APIs, see herehttps://cloud.ibm.com/apidocs/watsonx-ai-cp. Step-by-step instructions on how to use IBM watsonx.ai as a Service can be found herehttps://dataplatform.cloud.ibm.com/docs/content/wsj/getting-started/get-started-wdp.html?context=wx&audience=wdp. There is a specialized python library that is available to access this REST APIhttps://ibm.github.io/watsonx-ai-python-sdk/. Endpoint URLs <-- Regional public endpoints -- The following URL represents the base URLs for the watsonx.ai API endpoints. When you call the API, use the URL and add the path for each method to form the complete API endpoint for your requests. Dallas: https://us-south.ml.cloud.ibm.com Frankfurt - https://eu-de.ml.cloud.ibm.com London - https://eu-gb.ml.cloud.ibm.com Tokyo - https://jp-tok.ml.cloud.ibm.com Sydney - https://au-syd.ml.cloud.ibm.com Toronto - https://ca-tor.ml.cloud.ibm.com Mumbai - https://ap-south-1.aws.wxai.ibm.com Note that for prompts, vector indexes and agent tools the base URLs are the following: Dallas: https://api.dataplatform.cloud.ibm.com/wx Frankfurt - https://api.eu-de.dataplatform.cloud.ibm.com/wx London - https://api.eu-gb.dataplatform.cloud.ibm.com/wx Tokyo - https://api.jp-tok.dataplatform.cloud.ibm.com/wx Sydney - https://api.au-syd.dai.cloud.ibm.com/wx Toronto - https://api.ca-tor.dai.cloud.ibm.com/wx Mumbai - https://api.ap-south-1.aws.data.ibm.com/wx Note that for notebooks the base URLs are the following: Dallas: https://api.dataplatform.cloud.ibm.com Frankfurt - https://api.eu-de.dataplatform.cloud.ibm.com London - https://api.eu-gb.dataplatform.cloud.ibm.com Tokyo - https://api.jp-tok.dataplatform.cloud.ibm.com Sydney - https://api.au-syd.dai.cloud.ibm.com Toronto - https://api.ca-tor.dai.cloud.ibm.com Mumbai - https://api.ap-south-1.aws.data.ibm.com Example request to a Dallas endpoint: sh curl -H "Authorization: Bearer {token}" -X {requestmethod} "https://us-south.ml.cloud.ibm.com/{methodendpoint}" Replace {requestmethod}, and {methodendpoint} in this example with the values for your particular API call. See the Authentication section below for more details about the bearer {token}. Authentication This API uses IBM Cloud Identity and Access Management IAM to authenticate requests. To work with the API, authenticate your application or service by including your IBM Cloud IAM access tokenhttps://cloud.ibm.com/docs/account?topic=account-iamtokenfromapikeyiamtokenfromapikey in API requests. IAM authentication. Replace {token} and {url}/{method} with your service credentials. bash curl -H "Authorization:Bearer {token}" -X "{url}/{method}" Authorization: Bearer {token} For example, if the token is tzLbqWhyALQawBg5TjRIf5sAznhrKQyvBFFaZbtF60m5 in the service credentials, include the credentials in your call like this: bash curl -H "Authorization:Bearer tzLbqWhyALQawBg5TjRIf5sAznhrKQyvBFFaZbtF60m5" -X "https://us-south.ml.cloud.ibm.com/ml/v4/models" Error handling This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 type response indicates success. | HTTP Code | Description | Recovery | |-----------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 | Success | The request was successful. | | 400 | Bad Request | The input parameters in the request body are either incomplete, or in the wrong format, or some other input validation failed. Be sure to include all required parameters in your request and check the request body. | | 401 | Unauthorized | You are not authorized to make this request. Log in and try again or provide a valid token. See Authenticating with IAM tokenshttps://cloud.ibm.com/docs/watson?topic=watson-iamiam for instructions on logging in. If this error persists, contact the account owner to check your permissions. | | 403 | Forbidden | The supplied authentication is not authorized. | | 404 | Not Found | The requested resource could not be found. | Note that 429 and 503 errors may mean that the model is overloaded or unavailable, check the error description for more details. Error response | Name | Description | |--------|-------------------------------------------------------------------------------------------------------| | trace | An identifier that can be used to trace the request. This can be set using X-Global-Transaction-Id. | | errors | The list of errors. | Errors | Name | Description | |-----------|-------------------------------------------------------------------------| | code | A simple string code that should convey the general sense of the error. | | message | The message that describes the error. | | moreinfo | A reference to a more detailed explanation when available. | Additional headers Some additional headers might be required to make successful requests to the API. Those additional headers are described below. An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services using one identifier. The header key must be set to X-Global-Transaction-Id and the value is anything that you choose. If there is not a transaction ID that is passed in, then one is generated randomly. API change log In this change log you can learn about the latest changes, improvements, and updates for the watsonx.ai API. The change log lists changes that have been made, ordered by the date they were released. Changes to existing API versions are designed to be compatible with existing client applications, if this is not the case then a new version date will be created. 14 March 2024 The watsonx.ai API is generally available. Use the watsonx.ai API to work with foundation models programmatically. 18 April 2024 The /ml/v1/text/embeddingstext-embeddings API was added to watsonx.ai, this is a non-breaking change and just adds this single API operation. Versioning API requests require a version parameter that takes the date in the format version=YYYY-MM-DD. Send the version parameter with every API request. When the API is changed in a way that is not compatible with previous versions, a new minor version is released. To take advantage of the changes in a new version, change the value of the version parameter to the new date. If you're not ready to update to that version, don't change your version date. <-- API requests require a version parameter that takes a date in the format version=YYYY-MM-DD. When there is a change to the API in a backwards-incompatible wayhttps://github.com/watson-developer-cloud/api-guidelines/versioning, there will be a new version date published. Send the version parameter with every API request. The service uses the API version for the date you specify or the most recent version before that date. It is not recommended defaulting to the current date. Instead, specify a date that matches a version that is compatible with your app and do not change it until your app is ready for a later version. -- Active Version Dates | Version date | Summary of changes | |--------------|-----------------------------------| | 2024-03-14 | Publication of the /ml/v1 APIs. | <-- Activity Tracker events You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method. For more information about how to track watsonx.ai activity, see Auditing events for watsonx.aihttps://dataplatform.cloud.ibm.com/docs/content/wsj/admin/at-events.html?context=analytics&audience=wdpwatsonxai. -- Data References Accessing data in a remote location such as a Cloud Object Storage bucket, or an SQL/no-SQL database requires the use of connectionasset or dataasset reference types. These reference types are created within a space or a project and are referenced in requests to represent input data and results locations. These types contain two parameter objects, connection and location, which require different values to be supplied based on the reference type. Using a dataasset, requires an href to be supplied to the location object whereas using a connectionasset requires the connectionid for the connection object and different location fields depending on the data source type. <-- , see Data reference Descriptionhttps://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/deploy-batch-data-sources.html?context=cpdaas&audience=wdp for details. See here for a reference API for connectionshttps://api.dataplatform.cloud.ibm.com/v2/dataflows/doc/dataassetandconnectionproperties.html. -- Example connectionasset payload: json { "trainingdatareferences": { "type": "connectionasset", "connection": { "id": "Method Path Summary POST /ml/v4/ai_services Create a new AI service GET /ml/v4/ai_services Retrieve the AI services GET /ml/v4/ai_services/{id} Retrieve the AI service PATCH /ml/v4/ai_services/{id} Update the AI service DELETE /ml/v4/ai_services/{id} Delete the AI service PUT /ml/v4/ai_services/{id}/code Upload the AI service code GET /ml/v4/ai_services/{id}/code Download the AI service code POST /ml/v4/ai_services/{id}/revisions Create a new AI service revision GET /ml/v4/ai_services/{id}/revisions Retrieve the AI service revisions POST /ml/v1/autoai/rags Create a new AutoAI RAG run GET /ml/v1/autoai/rags Retrieve the AutoAI RAG runs GET /ml/v1/autoai/rags/{id} Get an AutoAI RAG run DELETE /ml/v1/autoai/rags/{id} Cancel or delete an AutoAI RAG run GET /ml/v4/custom_foundation_models Retrieve the custom foundation models POST /ml/v4/deployments Create a new watsonx.ai deployment GET /ml/v4/deployments Retrieve the deployments GET /ml/v4/deployments/{deployment_id} Retrieve the deployment details PATCH /ml/v4/deployments/{deployment_id} Update the deployment metadata DELETE /ml/v4/deployments/{deployment_id} Delete the deployment POST /ml/v1/deployments/{id_or_name}/text/generation Infer text POST /ml/v1/deployments/{id_or_name}/text/generation_stream Infer text event stream POST /ml/v1/deployments/{id_or_name}/text/chat Infer text chat POST /ml/v1/deployments/{id_or_name}/text/chat_stream Infer text chat event stream POST /ml/v1/deployments/{id_or_name}/time_series/forecast Time series forecast POST /ml/v1/fine_tunings Create a fine tuning job GET /ml/v1/fine_tunings Retrieve the list of fine tuning jobs GET /ml/v1/fine_tunings/{id} Get a fine tuning job DELETE /ml/v1/fine_tunings/{id} Cancel or delete a fine tuning job GET /ml/v1/foundation_model_specs List the available foundation models GET /ml/v1/foundation_model_tasks List the supported tasks POST /v2/notebooks Create a new notebook. POST /v2/notebooks/list Retrieve the details of a large number of notebooks inside a project.
DELETE /v2/notebooks/{notebook_guid} Delete a particular notebook, including the notebook asset.
PUT /v2/notebooks/{notebook_guid} Revert the main notebook to a version.
PATCH /v2/notebooks/{notebook_guid} Update a particular notebook.
POST /v2/notebooks/{notebook_guid}/promote Promote a notebook from project to space. POST /v2/notebooks/{notebook_guid}/versions Create a new version. GET /v2/notebooks/{notebook_guid}/versions List the versions of a notebook. GET /v2/notebooks/{notebook_guid}/versions/{version_guid} Retrieve a notebook version. DELETE /v2/notebooks/{notebook_guid}/versions/{version_guid} Delete a notebook version. POST /v1/prompts Create a new prompt / prompt template GET /v1/prompts/{prompt_id} Get a prompt PATCH /v1/prompts/{prompt_id} Update a prompt DELETE /v1/prompts/{prompt_id} Delete a prompt PUT /v1/prompts/{prompt_id}/lock Prompt lock modifications GET /v1/prompts/{prompt_id}/lock Get current prompt lock status POST /v1/prompts/{prompt_id}/input Get the inference input string for a given prompt POST /v1/prompts/{prompt_id}/chat_items Add a new chat item to a prompt POST /v1/prompt_sessions Create a new prompt session GET /v1/prompt_sessions/{session_id} Get a prompt session PATCH /v1/prompt_sessions/{session_id} Update a prompt session DELETE /v1/prompt_sessions/{session_id} Delete a prompt session POST /v1/prompt_sessions/{session_id}/entries Add a new prompt to a prompt session GET /v1/prompt_sessions/{session_id}/entries Get entries for a prompt session POST /v1/prompt_sessions/{session_id}/entries/{entry_id}/chat_items Add a new chat item to a prompt session entry PUT /v1/prompt_sessions/{session_id}/lock Prompt session lock modifications GET /v1/prompt_sessions/{session_id}/lock Get current prompt session lock status GET /v1/prompt_sessions/{session_id}/entries/{entry_id} Get a prompt session entry DELETE /v1/prompt_sessions/{session_id}/entries/{entry_id} Delete a prompt session entry POST /ml/v1/text/chat Infer text POST /ml/v1/text/chat_stream Infer text event stream POST /ml/v1/text/detection HAP and PII detection for text POST /ml/v1/text/detection/context Detection task on input content based on context documents POST /ml/v1/text/detection/generated Detection task performing detection on prompt and generated text POST /ml/v1/text/embeddings Generate embeddings POST /ml/v1/text/extractions Start a text extraction request GET /ml/v1/text/extractions Retrieve the text extraction requests GET /ml/v1/text/extractions/{id} Get the results of the request DELETE /ml/v1/text/extractions/{id} Delete the request POST /ml/v1/text/generation Infer text POST /ml/v1/text/generation_stream Infer text event stream POST /ml/v1/text/rerank Generate rerank POST /ml/v1/text/tokenization Text tokenization POST /ml/v1/time_series/forecast Time series forecast POST /ml/v4/trainings Create a new watsonx.ai training GET /ml/v4/trainings Retrieve the list of trainings GET /ml/v4/trainings/{training_id} Retrieve the training DELETE /ml/v4/trainings/{training_id} Cancel or delete the training POST /v1/vector_indexes Create a vector index. GET /v1/vector_indexes/{index_id} Get a vector index PATCH /v1/vector_indexes/{index_id} Update a vector index DELETE /v1/vector_indexes/{index_id} Delete a vector index PUT /v1/vector_indexes/{index_id}/attachment Vector Index attachments modifications