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/files Upload file GET /ml/v1/files List files GET /ml/v1/files/{file_id}/content Retrieve file POST /ml/v1/batches Create batch GET /ml/v1/batches List batches GET /ml/v1/batches/{batch_id} Retrieve batch POST /ml/v1/batches/{batch_id}/cancel Cancel batch 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 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}/chat/completions Infer chat completions 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/v4/deployments/{id_or_name}/ai_service Execute AI service POST /ml/v4/deployments/{id_or_name}/ai_service_stream Execute AI service stream POST /ml/v1/text/evaluations Submit a new Evaluation GET /ml/v1/text/evaluations Get list of Evaluations GET /ml/v1/text/evaluations/{id} Get Evalutation with given ID DELETE /ml/v1/text/evaluations/{id} Cancel or delete Evaluation with given ID 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 GET /ml/v1/gpus See available GPUs 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}/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/chat/completions Chat Completions POST /ml/v1/text/chat Infer text POST /ml/v1/text/chat_stream Infer text event stream POST /ml/v1/text/classifications Start a text classification request GET /ml/v1/text/classifications Retrieve the text classification requests GET /ml/v1/text/classifications/{id} Get the results of the request DELETE /ml/v1/text/classifications/{id} Delete the request POST /ml/v1/text/schemas/create Start a create schema request GET /ml/v1/text/schemas/create Retrieve the create schema requests GET /ml/v1/text/schemas/create/{id} Get the results of the request DELETE /ml/v1/text/schemas/create/{id} Delete the request POST /ml/v1/text/schemas/improve Start a improve schema request GET /ml/v1/text/schemas/improve Retrieve the improve schema requests GET /ml/v1/text/schemas/improve/{id} Get the results of the request DELETE /ml/v1/text/schemas/improve/{id} Delete the request POST /ml/v1/text/schemas/merge Start a merge schema request GET /ml/v1/text/schemas/merge Retrieve the merge schema requests GET /ml/v1/text/schemas/merge/{id} Get the results of the request DELETE /ml/v1/text/schemas/merge/{id} Delete the request POST /ml/v1/text/schemas/cluster Start a cluster schema request GET /ml/v1/text/schemas/cluster Retrieve the cluster schema requests GET /ml/v1/text/schemas/cluster/{id} Get the results of the request DELETE /ml/v1/text/schemas/cluster/{id} Delete the request 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/similarities Detect text similarities 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/image Create an image 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 POST /v1/transactional_vector_indexes Create a vector index. PATCH /v1/transactional_vector_indexes/{index_id} Update a vector index GET /v1/transactional_vector_indexes/{index_id}/status Get status of a vector index POST /ml/v1/geospatial/transformations Create a geospatial transformation GET /ml/v1/geospatial/transformations Retrieve the geospatial transformation requests GET /ml/v1/geospatial/transformations/{id} Get a geospatial transformation DELETE /ml/v1/geospatial/transformations/{id} Delete a geospatial transformation POST /ml/v1/tuning/documents Create a document extraction GET /ml/v1/tuning/documents Get document extractions GET /ml/v1/tuning/documents/{id} Get document extraction DELETE /ml/v1/tuning/documents/{id} Cancel the document extraction POST /v2/synthetic_data/generation/unstructured Create a synthetic unstructured data generation job POST /ml/v1/tuning/synthetic_data Create a synthetic data generation job GET /ml/v1/tuning/synthetic_data Get synthetic data generation jobs GET /ml/v1/tuning/synthetic_data/{id} Get synthetic data generation job DELETE /ml/v1/tuning/synthetic_data/{id} Cancel the synthetic data generation POST /ml/v1/tuning/taxonomies_imports Create a taxonomy job GET /ml/v1/tuning/taxonomies_imports Get taxonomy jobs GET /ml/v1/tuning/taxonomies_imports/{id} Get taxonomy job DELETE /ml/v1/tuning/taxonomies_imports/{id} Cancel or delete the taxonomy job POST /ml/gateway/v1/audio/speech Create Speech POST /ml/gateway/v1/chat/completions Create Chat Completions POST /ml/gateway/v1/completions Create Text Completions POST /ml/gateway/v1/embeddings Create Embeddings POST /ml/gateway/v1/images/generations Create Image Generations GET /ml/gateway/v1/models List All Models GET /ml/gateway/v1/models/{model_uuid} Get Existing Model DELETE /ml/gateway/v1/models/{model_uuid} Delete Existing Model GET /ml/gateway/v1/tenant Get Current Tenant PUT /ml/gateway/v1/tenant Replace Current Tenant PATCH /ml/gateway/v1/tenant Update Current Tenant DELETE /ml/gateway/v1/tenant Delete Current Tenant GET /ml/gateway/v1/tenant/config Get Current Tenant Configuration PUT /ml/gateway/v1/tenant/config Update Current Tenant Configuration DELETE /ml/gateway/v1/tenant/config Delete Current Tenant Configuration POST /ml/gateway/v1/tenant/jwt Create Tenant JWT GET /ml/gateway/v1/policies List All Policies POST /ml/gateway/v1/policies Create New Policy GET /ml/gateway/v1/policies/{policy_uuid} Get Specific Policy PUT /ml/gateway/v1/policies/{policy_uuid} Update Existing Policy DELETE /ml/gateway/v1/policies/{policy_uuid} Delete Existing Policy GET /ml/gateway/v1/providers List All Providers POST /ml/gateway/v1/providers/anthropic Create New Anthropic Provider POST /ml/gateway/v1/providers/azure_openai Create New Azure OpenAI Provider POST /ml/gateway/v1/providers/bedrock Create New AWS Bedrock Provider POST /ml/gateway/v1/providers/cerebras Create New Cerebras Provider POST /ml/gateway/v1/providers/cohere Create New Cohere Provider POST /ml/gateway/v1/providers/gemini Create New Gemini Provider POST /ml/gateway/v1/providers/groq Create New Groq Provider POST /ml/gateway/v1/providers/mistral Create New Mistral Provider POST /ml/gateway/v1/providers/nim Create New Nvidia NIM Provider POST /ml/gateway/v1/providers/ollama Create New Ollama Provider POST /ml/gateway/v1/providers/openai Create New OpenAI Provider GET /ml/gateway/v1/providers/search Find Existing Providers POST /ml/gateway/v1/providers/validate Validate Provider Credentials POST /ml/gateway/v1/providers/watsonxai Create New IBM Watsonx.ai Provider POST /ml/gateway/v1/providers/xai Create New xAI Provider GET /ml/gateway/v1/providers/{provider_uuid} Get Existing Provider DELETE /ml/gateway/v1/providers/{provider_uuid} Delete Existing Provider PUT /ml/gateway/v1/providers/{provider_uuid}/anthropic Replace Existing Anthropic Provider PUT /ml/gateway/v1/providers/{provider_uuid}/azure_openai Replace Existing Azure OpenAI Provider PUT /ml/gateway/v1/providers/{provider_uuid}/bedrock Replace Existing AWS Bedrock Provider PUT /ml/gateway/v1/providers/{provider_uuid}/cerebras Replace Existing Cerebras Provider PUT /ml/gateway/v1/providers/{provider_uuid}/cohere Replace Existing Cohere Provider PUT /ml/gateway/v1/providers/{provider_uuid}/gemini Replace Existing Gemini Provider PUT /ml/gateway/v1/providers/{provider_uuid}/groq Replace Existing Groq Provider PUT /ml/gateway/v1/providers/{provider_uuid}/mistral Replace Existing Mistral Provider PUT /ml/gateway/v1/providers/{provider_uuid}/ollama Replace Existing Ollama Provider GET /ml/gateway/v1/providers/{provider_uuid}/models List Provider Models POST /ml/gateway/v1/providers/{provider_uuid}/models Create New Model PUT /ml/gateway/v1/providers/{provider_uuid}/models/{model_uuid} Replace Existing Model PATCH /ml/gateway/v1/providers/{provider_uuid}/models/{model_uuid} Update Existing Model DELETE /ml/gateway/v1/providers/{provider_uuid}/models/{model_uuid} Delete Existing Model GET /ml/gateway/v1/providers/{provider_uuid}/models_available List Available Models PUT /ml/gateway/v1/providers/{provider_uuid}/nim Replace Existing Nvidia NIM Provider PUT /ml/gateway/v1/providers/{provider_uuid}/openai Replace Existing OpenAI Provider PUT /ml/gateway/v1/providers/{provider_uuid}/watsonxai Replace Existing IBM Watsonx.ai Provider PUT /ml/gateway/v1/providers/{provider_uuid}/xai Replace Existing xAI Provider GET /ml/gateway/v1/load_balancers List Load Balancers POST /ml/gateway/v1/load_balancers Create Load Balancer GET /ml/gateway/v1/load_balancers/{load_balancer_uuid} Get Load Balancer PUT /ml/gateway/v1/load_balancers/{load_balancer_uuid} Update Load Balancer DELETE /ml/gateway/v1/load_balancers/{load_balancer_uuid} Delete Load Balancer GET /ml/gateway/v1/load_balancers/{load_balancer_uuid}/backends List Backends POST /ml/gateway/v1/load_balancers/{load_balancer_uuid}/backends Create Backend GET /ml/gateway/v1/load_balancers/{load_balancer_uuid}/backends/{load_balancer_backend_uuid} Get Load Balancer Backend PUT /ml/gateway/v1/load_balancers/{load_balancer_uuid}/backends/{load_balancer_backend_uuid} Replace Load Balancer Backend DELETE /ml/gateway/v1/load_balancers/{load_balancer_uuid}/backends/{load_balancer_backend_uuid} Delete Load Balancer Backend GET /ml/gateway/v1/rate_limits List Rate Limit Configurations POST /ml/gateway/v1/rate_limits Create Rate Limit Configuration GET /ml/gateway/v1/rate_limits/{ratelimit_uuid} Get Rate Limit Configuration PUT /ml/gateway/v1/rate_limits/{ratelimit_uuid} Replace Rate Limit Configuration DELETE /ml/gateway/v1/rate_limits/{ratelimit_uuid} Delete Rate Limit Configuration POST /ml/gateway/v1/responses Create Response GET /ml/gateway/v1/usage Get Tenant Usage GET /ml/gateway/v1/usage/user Get User Usage GET /v1-beta/utility_agent_tools Get utility agent tools GET /v1-beta/utility_agent_tools/{tool_id} Get utility agent tool POST /v1-beta/utility_agent_tools/run Run a utility agent tool POST /v1-beta/utility_agent_tools/run/{tool_id} Run a utility agent tool