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.

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 in Salesforce Help.

Create an External Client App

To securely use Connect API endpoints for ADL, you must create an External Client App (ECA).

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

When creating the app, include these settings.

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)
Select these additional OAuth settings:
- Enable Client Credentials Flow
- Issue JSON Web Token (JWT)-based access tokens for named users
- For more information on OAuth settings and security, see Configure the External Client App OAuth Settings.
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.

From Setup, find and select External Client Apps.
Select your app and click the Settings tab.
Expand the OAuth Settings section.
Click the Consumer Key and Consumer Secret button, and copy your secrets. You need these values to mint this token.
Important: Store your consumer secret in a secure location.
From Setup, in the Quick Find box, enter My Domain, and then select My Domain.
Copy the value shown in the Current My Domain URL field.
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.

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.

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

Run this command block to get an access token.

1# Get token via client_credentials flow
2RESPONSE=$(curl -s -X POST \
3  "$SF_INSTANCE_URL/services/oauth2/token" \
4  -d "grant_type=client_credentials" \
5  -d "client_id=$SF_CLIENT_ID" \
6  -d "client_secret=$SF_CLIENT_SECRET")
7
8ACCESS_TOKEN=$(echo $RESPONSE | jq -r '.access_token')
9ORG_URL=$(echo $RESPONSE | jq -r '.instance_url')
10
11# Verify ADL API
12curl -s "$INSTANCE_URL/services/data/v66.0/einstein/data-libraries" \
13  -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.

1# Generate a unique library name
2ADL_PREFIX="your_prefix"
3ADL_SUFFIX=$(date +%m%d)_$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c3)
4ADL_DevName="${ADL_PREFIX}_${ADL_SUFFIX}"
5ADL_Name="${ADL_PREFIX} ${ADL_SUFFIX}"
6
7# Point to your test file (change this path)
8FILE_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.