Referencing files from the API

Last updated: Dec 06, 2024

Learn how to add files to watsonx.ai that you want to reference programmatically.

To complete some tasks programmatically, you must be able to add files and reference them from the API. For example, to prompt tune a foundation model, you must provide a training data file.

One way to make a file available is to add the file to a new bucket in the IBM Cloud Object Storage service instance that is associated with your watsonx.ai project. (An IBM Cloud Object Storage service instance is created for you automatically when you create a watsonx.ai project from the user interface.)

Adding files by using the UI

The following steps outline how to add files that you can reference from the API by using the product user interface.

Add a bucket to the IBM Cloud Object Storage instance that is associated with your watsonx.ai project.

From the Resource list in IBM Cloud, expand Storage, and then click to open your IBM Cloud Object Storage service instance. Click Create bucket.
Add a file to the bucket.

From the Objects tab of the bucket, upload the file.

To reference the file from the API, you must create a connection to the IBM Cloud Object Storage service instance with the bucket where the file is stored.

From your project, choose New Asset > Connect to a data source, and choose IBM Cloud Object Storage, and then click Next.
Name the connection asset.

For the connection details, add the following information:

The name of the bucket that you created in step 1.
To get the login URL, open the storage bucket in IBM Cloud Object Storage, click the Configurations tab, and then copy the public endpoint URL.

For the credentials, choose the Access Key and Secret Key authentication option to connect to the data source. From the main service page for your IBM Cloud Object Storage service instance, click the Service credentials tab, and then find the key that you want to use and expand it so you can see the key details. The key that you use must include an HMAC credential. If you don't have an existing key with an HMAC credential, create one. Copy the following values to paste into the corresponding fields in the connection asset details page:

Copy from bucket	Paste to connection asset
access_key_id	Access key
secret_access_key	Secret key

For more information about how to create a connection to your IBM Cloud Object Storage service instance from your watsonx.ai project, see IBM Cloud Object Storage connection.

From the Assets page of your project, open the IBM Cloud Object Storage data connection asset. In the URL for the current page, copy the connection ID that is displayed after the /connections/ segment of the URL.

You can specify this connection ID, and other details, such as the bucket name, when you reference the file from the API.
```
"type": "connection_asset",
   "connection": {
     "id": "<connection_id>"
   }
```
For more information, see Data references in the IBM watsonx.ai as a service API documentation.

Parent topic: REST API