Adding files to reference from the API

Last updated: Feb 21, 2025

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 tune a foundation model programmatically, you must provide a training data file.

You can add files by creating one of the following asset types:

Connection asset
Data asset

For more information, see Data references in the IBM watsonx.ai as a service API documentation.

Adding files by creating a connection asset from the UI

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

To add files by creating a connection asset from the product user interface that you can reference from the API, complete the following steps:

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>"
   }
```

Adding files by creating a data asset from the UI

To add files by creating a data asset from the product user inteface that you can reference from the API, complete the following steps:

From the project overview page, click the Add data to work with tile.
Click Local file, and then click Data asset.
Click Browse to find and select the file that you want to upload.
Click Open, and then click Done.
Click to open the file that you just added from the All assets list.
In the location field for the web browser, copy the data asset ID that is displayed between the data-assets/ and /preview segments of the URL for the current page.

An example data asset ID is 1e6591a2-c69d-4716-92e3-73e8c2270956.

You can specify this data asset ID when you reference the file from the API.
```
{
  "training_data_references": [
  {
    "type": "data_asset",
    "location": {
      "href": "/v2/assets/<asset_id>?project_id=<project_id>"
    }
  }
 ]
}
```

Parent topic: REST API