# Get Started with ADL API

This guide shows you how to work with Connect REST API resources to manage Agentforce data libraries (ADL).

## Prerequisites

There are a few tools and items that we need for this quick start. The instructions focus on macOS and Linux but they should work with minimal changes on a different OS.

### Salesforce CLI

Salesforce CLI is a command-line interface that simplifies development and build automation when working with your Salesforce org. We use it to authenticate and get information about an org.\
Install the CLI by using the [Salesforce CLI Setup Guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm#sfdx_setup_install_cli_macos).

### jq

We use jq for parsing JSON. To see if jq is already installed on your computer, run:\
`jq --version`

If jq isn’t installed, run:\
`brew install jq`

### PDF File

You need a PDF on your machine. The content doesn't matter. We use the PDF as a file in your first data library.

### Test Org

Set up an org for the quick start. For org requirements, see [Setting Up Data Libraries](https://help.salesforce.com/s/articleView?id=ai.data_library_setup.htm\&type=5) in Salesforce Help.

### Create an External Client App

To securely use Connect API endpoints for ADL, you must create an [External Client App (ECA)](https://help.salesforce.com/s/articleView?id=xcloud.external_client_apps.htm\&type=5).

Create an external client app with OAuth and usage of a JWT access token enabled. Use these instructions to get set up: [Create a Local External Client App](https://help.salesforce.com/s/articleView?id=xcloud.create_a_local_external_client_app.htm\&type=5)

When creating the app, include these settings.

1. Use these OAuth Scopes:

   - **Access Connect REST API Resources (chatter_api)**
   - **Manage user data via APIs (api)**
   - **Manage user data via Web browsers (web)**
   - **Perform requests at any time (refresh_token, offline_access)**

   ![OAuth scopes settings](https://a.sfdcstatic.com/developer-website/sfdocs/genai/media/testing-eca-oauth.png)

2. Select these additional OAuth settings:

   - **Enable Client Credentials Flow**
   - **Issue JSON Web Token (JWT)-based access tokens for named users**

   ![OAuth flow and security settings](https://a.sfdcstatic.com/developer-website/sfdocs/genai/media/testing-eca-oauth-flow.png)

   - For more information on OAuth settings and security, see [Configure the External Client App OAuth Settings](https://help.salesforce.com/s/articleView?id=xcloud.configure_external_client_app_oauth_settings.htm\&language=en_US\&type=5).

3. After creating the app, make sure that the API caller has the correct client credentials and that the client can issue JWT-based access tokens.

   - Click the **Policies** tab for the app, and then click **Edit**.
   - Select the **Enable Client Credentials Flow** checkbox.
   - Specify the client user in the **Run As** field.
   - Select the **Issue JSON Web Token (JWT)-based access tokens** checkbox. By default, this token expires in 30 minutes. You can change this value to less than 30 minutes.

### Get Credentials

To create a token, you need the consumer key and the consumer secret from your ECA.

1. From Setup, find and select **External Client Apps**.
2. Select your app and click the **Settings** tab.
3. Expand the **OAuth Settings** section.
4. Click the **Consumer Key and Consumer Secret** button, and copy your secrets. You need these values to mint this token.
5. **Important:** Store your consumer secret in a secure location.
6. From Setup, in the Quick Find box, enter `My Domain`, and then select **My Domain**.
7. Copy the value shown in the **Current My Domain URL** field.
8. Request a JWT access token from Salesforce by using a POST request, specifying the values for your consumer key, consumer secret, and domain name.

### Get an Access Token

All calls to Connect API require an access token. Create a token by using the consumer key, the consumer secret, and your domain name. For more information, see the [Connect REST API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/quickstart_connecting.htm).

In a Terminal, set these environment variables after you replace `{CONSUMER_KEY}`, `{CONSUMER_SECRET}`, and `{MY_DOMAIN_URL}` with values from your org.

- `MY_DOMAIN_URL`: Get the domain from Setup by searching for **My Domain**. Copy the value shown in the **Current My Domain URL** field.
- `CONSUMER_KEY`, `CONSUMER_SECRET`: Get the consumer key and secret by following the instructions in Get Credentials.

```
export SF_CLIENT_ID={CONSUMER_KEY}
export SF_CLIENT_SECRET={CONSUMER_SECRET}
export SF_INSTANCE_URL=https://{MY_DOMAIN_URL}.my.salesforce.com
```

Run this command block to get an access token.

```
# Get token via client_credentials flow
RESPONSE=$(curl -s -X POST \
  "$SF_INSTANCE_URL/services/oauth2/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=$SF_CLIENT_ID" \
  -d "client_secret=$SF_CLIENT_SECRET")

ACCESS_TOKEN=$(echo $RESPONSE | jq -r '.access_token')
ORG_URL=$(echo $RESPONSE | jq -r '.instance_url')

# Verify ADL API
curl -s "$INSTANCE_URL/services/data/v66.0/einstein/data-libraries" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq '.'

```

If you get a JSON response (even an empty array), OAuth is working.

### Set Up Shell Variables

Copy and paste this block into your terminal. It sets up a unique library name for your session.

Update `FILE_NAME` to point to your test PDF.

```shell
# Generate a unique library name
ADL_PREFIX="your_prefix"
ADL_SUFFIX=$(date +%m%d)_$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c3)
ADL_DevName="${ADL_PREFIX}_${ADL_SUFFIX}"
ADL_Name="${ADL_PREFIX} ${ADL_SUFFIX}"

# Point to your test file (change this path)
FILE_NAME="/Users/yourname/Downloads/file1.pdf"
```

We're using a specific library naming convention for this quick start. You can choose any naming scheme for your libraries.