All Reference

Agentforce Connect REST API

API docs by Redocly
All Reference

Agentforce Connect REST API

Agentforce Connect REST API (v67.0)

Download OpenAPI specification:Download

Note: The API Reference has a new three-panel layout. Browse grouped endpoints on the left, review endpoint details in the center, and access examples on the right.

Important: Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Agentforce Data Libraries Resources (Beta)

Agentforce Data Libraries enhance the accuracy of AI features like Agentforce Agents by connecting them to your trusted data sources. Data libraries use unstructured or semi-structured data so that they can take large sets of information that exist on the web, in documents, or as large text inputs in fields, and turn that into more useful, searchable information.

List Libraries

Get grounding libraries.

Note: Optional filtering by grounding source type is supported.

query Parameters
sourceType
string

Filter the list by grounding source type. If omitted, all libraries are returned.

Available in: v66.0

Responses

Response samples

Content type
application/json
{
  • "libraries": [
    ],
  • "totalSize": 0
}

Create a Library

Creates an AI Grounding Library. The source type is inferred from groundingSource (discriminator sourceType, or from populated fields). Supported source types:

  • SFDRIVE — File-based library. After creation, use the file upload workflow.
  • KNOWLEDGE — Knowledge article library. Specify knowledgeConfig with required fields.
  • RETRIEVER — Connect to an existing custom retriever by providing retrieverId. The retriever must be active; inactive retrievers are rejected with ADL_RETRIEVER_NOT_ACTIVE, and retrievers that can't be located are rejected with ADL_RETRIEVER_NOT_FOUND.

For SFDRIVE, after creation:

  • Poll /einstein/data-libraries/{libraryId}/upload-readiness until ready=true (the Unified Data Lake Object must be ACTIVE before upload)
  • POST to /einstein/data-libraries/{libraryId}/file-upload-urls with file names to get presigned S3 upload URLs
  • PUT files to the presigned URLs
  • POST to /einstein/data-libraries/{libraryId}/indexing with uploaded file paths and sizes.

For KNOWLEDGE, provisioning starts automatically after creation. Poll /status to track progress. For RETRIEVER, the library is immediately usable after creation (no upload workflow required).

Request Body schema: application/json
required
masterLabel
required
string <= 80 characters

Master label.

Available in: v66.0

developerName
required
string <= 80 characters ^[a-zA-Z][a-zA-Z0-9_]*$

Unique developer name (pattern ^[a-zA-Z][a-zA-Z0-9_]*$ ).

Available in: v66.0

description
string <= 255 characters

Description.

Available in: v66.0

dataSpaceScopeId
string

DataSpaceScope ID; defaults to the org’s default dataspace if omitted. Only the default dataspace is supported. Providing a non-default dataspace ID returns 400 with ADL_NON_DEFAULT_DATASPACE_NOT_SUPPORTED .

Available in: v66.0

object (GroundingSourceInput)

GroundingSourceInputRepresentation — infers SFDRIVE / KNOWLEDGE / RETRIEVER.

Available in: v66.0

Responses

Request samples

Content type
application/json
{
  • "masterLabel": "Product Documentation",
  • "developerName": "Product_Documentation",
  • "description": "Product manuals and guides for RAG grounding",
  • "dataSpaceScopeId": "9gTSG0000037LPN2A2",
  • "groundingSource": {
    }
}

Response samples

Content type
application/json
{
  • "libraryId": "1JDSG000007IbWX4A0",
  • "masterLabel": "Product Documentation",
  • "developerName": "Product_Documentation",
  • "description": "string",
  • "sourceType": "SFDRIVE",
  • "dataSpaceScopeId": "string",
  • "createdDate": "string",
  • "status": "READY",
  • "retrieverId": "string",
  • "retrieverLabel": "string",
  • "retriever": {
    },
  • "retrieverAction": {
    },
  • "groundingSource": {
    },
  • "fileAdlMode": 0,
  • "featureAssignments": [
    ]
}

Get a Library

Returns the type-specific details for one library.

path Parameters
libraryId
required
string^[a-zA-Z0-9]{18}$

AI Grounding Library ID (18-char Salesforce ID, key prefix 1JD)

Responses

Response samples

Content type
application/json
{
  • "libraryId": "1JDSG000007IbWX4A0",
  • "masterLabel": "Product Documentation",
  • "developerName": "Product_Documentation",
  • "description": "string",
  • "sourceType": "SFDRIVE",
  • "dataSpaceScopeId": "string",
  • "createdDate": "string",
  • "status": "READY",
  • "retrieverId": "string",
  • "retrieverLabel": "string",
  • "retriever": {
    },
  • "retrieverAction": {
    },
  • "groundingSource": {
    },
  • "fileAdlMode": 0,
  • "featureAssignments": [
    ]
}

Update a Library

Updates an existing AI Grounding Library with PATCH semantics. All fields are optional; only set fields are updated. Supported operations by source type:

  • SFDRIVE: update masterLabel, description (metadata only, no re-provisioning).
  • RETRIEVER: update masterLabel, description, or retrieverId (switch to a different retriever).
  • KNOWLEDGE: update masterLabel, description, or knowledge configuration fields (contentFields, isRestrictToPublicArticle, isDataCategoryRuleEnabled, dataCategorySelectionIds, dataCategorySelectionNames). primaryIndexField1 and primaryIndexField2 are immutable after creation.
  • SITEMAP: update masterLabel, description (metadata only, grounding source changes rejected).

Validation rules:

  • Attempting to change sourceType returns 400 with ADL_MISMATCH_SOURCE_TYPE.
  • Attempting to update primary index fields on KNOWLEDGE returns 400 with ADL_PRIMARY_FIELDS_IMMUTABLE.
  • Concurrent updates are blocked for KNOWLEDGE libraries during provisioning (returns 400 with ADL_UPDATE_IN_PROGRESS).

Returns updated library details with the same response shape as GET.

path Parameters
libraryId
required
string^[a-zA-Z0-9]{18}$

AI Grounding Library ID (18-char Salesforce ID, key prefix 1JD)

Request Body schema: application/json
required
masterLabel
string <= 80 characters

Updated master label.

description
string <= 255 characters

Updated description.

object (GroundingSourceInput)

GroundingSourceInputRepresentation .

Responses

Request samples

Content type
application/json
{
  • "masterLabel": "string",
  • "description": "string",
  • "groundingSource": {
    }
}

Response samples

Content type
application/json
{
  • "libraryId": "1JDSG000007IbWX4A0",
  • "masterLabel": "Product Documentation",
  • "developerName": "Product_Documentation",
  • "description": "string",
  • "sourceType": "SFDRIVE",
  • "dataSpaceScopeId": "string",
  • "createdDate": "string",
  • "status": "READY",
  • "retrieverId": "string",
  • "retrieverLabel": "string",
  • "retriever": {
    },
  • "retrieverAction": {
    },
  • "groundingSource": {
    },
  • "fileAdlMode": 0,
  • "featureAssignments": [
    ]
}

Delete a Library

Deletes the library and associated entities (cascade): FileRefs, KnowledgeConfig, LibSrcRel, SourceStages, GroundingSource, Retriever, SearchIndex. You can’t delete if the library is in use by an agent (400).

path Parameters
libraryId
required
string^[a-zA-Z0-9]{18}$

AI Grounding Library ID (18-char Salesforce ID, key prefix 1JD)

Responses

Generate URLs for Uploading Files

Generates presigned S3 URLs for uploading files to an existing SFDRIVE library.

path Parameters
libraryId
required
string^[a-zA-Z0-9]{18}$

AI Grounding Library ID (18-char Salesforce ID, key prefix 1JD)

Request Body schema: application/json
required
required
Array of objects (FileInfoInput)

List of FileInfoInputRepresentation objects.

Available in: v66.0

Responses

Request samples

Content type
application/json
{
  • "files": [
    ]
}

Response samples

Content type
application/json
{}

List Files in a Library

Returns a paginated list of file references for an SFDRIVE library. Includes per-file status for indexing visibility.

path Parameters
libraryId
required
string^[a-zA-Z0-9]{18}$

AI Grounding Library ID (18-char Salesforce ID, key prefix 1JD)

query Parameters
pageSize
string

Number of files listed per page. Default 50 .

Available in: v67.0

offset
integer

Offset into the result set. Default 0 .

Available in: v67.0

sortBy
string

Sort field. Default status (errors first).

Available in: v67.0

sortOrder
string

Sort direction.

Available in: v67.0

name
string

Filter by file name (case-insensitive contains match).

Available in: v67.0

status
string

Filter by file processing status.

Available in: v67.0

Responses

Response samples

Content type
application/json
{
  • "files": [
    ],
  • "totalSize": 0,
  • "currentPageUrl": "string",
  • "nextPageUrl": "string"
}

Add Files to a Library

Adds files to an existing SFDRIVE library and triggers SearchIndex re-hydration (day-2 incremental adds). At least one uploaded file is required. No duplicate file names in the batch are allowed. The total file count must not exceed 1000. SFDRIVE libraries only. Poll /status for progress.

path Parameters
libraryId
required
string^[a-zA-Z0-9]{18}$

AI Grounding Library ID (18-char Salesforce ID, key prefix 1JD)

Request Body schema: application/json
required
required
Array of objects (UploadedFileInfoInput)

At least one UploadedFileInfoInputRepresentation .

Available in: v66.0

Responses

Request samples

Content type
application/json
{
  • "uploadedFiles": [
    ]
}

Response samples

Content type
application/json
{
  • "libraryId": "string",
  • "filesAccepted": 0,
  • "groundingFileRefs": [
    ]
}

Delete a File from a Library

Deletes a single file from an SFDRIVE library. Performs synchronous deletion of the file from S3 and removes the AiGroundingFileRef record.

Note: SFDRIVE libraries only. Attempting to call this endpoint on a non-SFDRIVE library returns 400 with ADL_UNSUPPORTED_SOURCE_TYPE.

path Parameters
libraryId
required
string^[a-zA-Z0-9]{18}$

AI Grounding Library ID (18-char Salesforce ID, key prefix 1JD)

fileId
required
string^[a-zA-Z0-9]{18}$

is the 18 character AiGroundingFileRef record ID.

Responses

Index Library

Starts asynchronous indexing of Data Cloud resources (DLO, DMO, SearchIndex, Retriever).

Note: You can provision SFDRIVE libraries only with this endpoint. RETRIEVER libraries don’t need indexing. Attempting to provision a KNOWLEDGE or RETRIEVER library returns 400.

  • SFDRIVE: uploadedFiles must list uploaded files (paths and sizes).
  • The library must be upload-ready before calling this endpoint. Poll /einstein/data-libraries/{libraryId}/upload-readiness first.
  • Calling /einstein/data-libraries/{libraryId}/indexing before readiness returns 400 with "Library isn’t upload-ready yet."
path Parameters
libraryId
required
string^[a-zA-Z0-9]{18}$

AI Grounding Library ID (18-char Salesforce ID, key prefix 1JD)

Request Body schema: application/json
required
Array of objects (UploadedFileInfoInput)

UploadedFileInfoInputRepresentation entries. Required for SFDRIVE to confirm uploads.

Responses

Request samples

Content type
application/json
{
  • "uploadedFiles": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "libraryId": "string",
  • "sourceType": "SFDRIVE",
  • "status": "READY",
  • "message": "string",
  • "filesAccepted": 0
}

Check Library Status

Returns current library status derived from the SearchIndex runtime with per-stage detail. Use for polling after provisioning or re-provisioning. Suggested polling interval: 5–30 seconds.

path Parameters
libraryId
required
string^[a-zA-Z0-9]{18}$

AI Grounding Library ID (18-char Salesforce ID, key prefix 1JD)

query Parameters
includeArtifacts
boolean
Default: false

When true, resolves Data 360 asset artifacts (DLO, DMO, SearchIndex, Retriever) with entity IDs and developer names on each stage. Requires additional queries. Default: false (stages returned without artifacts for fast polling).

Responses

Response samples

Content type
application/json
{
  • "indexingStatus": {
    }
}

Check Upload Readiness

Checks whether the UDLO (Unified Data Lake Object) is ACTIVE and ready for file uploads.

SFDRIVE libraries only. Attempting to call this endpoint on a non-SFDRIVE library returns 400 with ADL_UNSUPPORTED_SOURCE_TYPE.

With waitMaxTime=0 (default), performs one check and returns immediately. With waitMaxTime > 0, the server polls internally until ready=true or the timeout, avoiding tight client polling loops.

path Parameters
libraryId
required
string^[a-zA-Z0-9]{18}$

AI Grounding Library ID (18-char Salesforce ID, key prefix 1JD)

query Parameters
waitMaxTime
string

Max milliseconds to wait for UDLO readiness (server-side polling). Default 0 : single immediate check. Range 1 – 120000 for wait behavior. Values < 0 or > 120000 produce 400.

Available in: v66.0

Responses

Response samples

Content type
application/json
{
  • "libraryId": "1JDSG000007IbWX4A0",
  • "ready": true,
  • "sourceType": "SFDRIVE",
  • "message": "UDLO is ACTIVE. Ready for file uploads."
}

Prompt Templates Resources

Get prompt template data and generate LLM responses using prompt templates.

Create Prompt Templates

Create prompt templates based on the input data.

Available in: v62.0

Request Body schema: application/json
required

Input representation for creating a prompt template.

Available in: v65.0

required
object (EinsteinPromptRecordInput)

Representation of the payload of the template to be created.

Responses

Request samples

Content type
application/json
{
  • "templateInput": {
    }
}

Response samples

Content type
application/json
{
  • "additionalData": {
    },
  • "errorMessages": [
    ],
  • "hasWarning": true,
  • "isSuccessful": true,
  • "statusCode": "string",
  • "templateId": "string",
  • "templateType": "string",
  • "versionId": "string",
  • "warningMessages": [
    ]
}

Get Prompt Templates

Get a list of prompt templates based on specified filters.

Available in: v62.0

query Parameters
fields
Array of strings

Comma-separated list of prompt template record fields to return, such as createdDate . If unspecified, all fields are returned.

Available in: v62.0

isActive
boolean

Specifies whether to return active prompt templates only. The default is false .

Available in: v62.0

offset
integer

Used for pagination. Number of rows to skip between returned prompt template records. The default value is 0 .

Available in: v62.0

pageLimit
integer

Used for pagination. Maximum number of prompt template records returned per page. The default value is 50 .

Available in: v62.0

query
string

User-entered search string. If unspecified, all prompt template records are returned.

Available in: v62.0

relatedEntity
string

Related entity to filter records by, such as Contact . If unspecified, all records with all related entities are returned.

Available in: v62.0

sortBy
string

Field to sort order the returned prompt template records by, such as createdDate . If unspecified, records are returned in the order they’re retrieved.

Available in: v62.0

type
string

Prompt template type to filter records by, such as einstein_gpt__salesEmail . If unspecified, records of all types are returned.

Available in: v62.0

Responses

Response samples

Content type
application/json
{
  • "hasMoreRecords": true,
  • "promptRecords": [
    ],
  • "totalPromptRecords": 0
}

Einstein Prompt Template Generations

Generates a response based on the specified prompt template and input parameters.

Available in: v60.0

path Parameters
promptTemplateDevName
required
string

Developer name of the prompt template.

query Parameters
versionId
string
Request Body schema: application/json

Prompt template input parameters and LLM provider to use for generation.

required
object (EinsteinLlmAdditionalConfigInput)

Configuration information for the LLM provider.

Available in: v60.0

citationMode
string
Enum: "post_generation" "off"

Mode of citations for the specified prompt template. Valid values are:

  • post_generation —Citations are generated after the generated response for the specified prompt template.
  • off —Citations aren't generated for the specified prompt template.

Available in: v62.0

required
object

Parameters and values to resolve the specified prompt template.

Available in: v60.0

isPreview
required
boolean

Specifies whether to only resolve the prompt template (true) or to resolve the prompt template and generate an LLM response (false).

Available in: v60.0

outputLanguage
string

Language code for the language to generate the LLM response in. See Supported Languages in Prompt Template Responses.

Available in: v61.0

object

Map of wrapped values, such as free-form user feedback, that can be used to resolve a specified prompt template.

Available in: v62.0

Responses

Request samples

Content type
application/json
{
  • "isPreview": false,
  • "inputParams": {
    },
  • "additionalConfig": {
    }
}

Response samples

Content type
application/json
{
  • "citations": {
    },
  • "fileData": [
    ],
  • "generationErrors": [
    ],
  • "generations": [
    ],
  • "isSummarized": true,
  • "mergeFieldInformation": {
    },
  • "parameters": {
    },
  • "prompt": "string",
  • "promptTemplateDevName": "string",
  • "renderConfiguration": {
    },
  • "requestId": "string",
  • "requestMessages": [
    ],
  • "responseMessages": [
    ],
  • "slotsMaskingInformation": [
    ]
}

Prompt Template Versions

Get a prompt template version.

Available in: v65.0

Alternate paths

  • /einstein/prompt-templates/{promptTemplateDevName}/versions/{versionId} - By Prompt Template Dev Name and Version ID
path Parameters
promptTemplateDevName
required
string

Developer name of the prompt template.

query Parameters
includingContent
boolean

If true , returns the version content.

Available in: v65.0

includingVersionDetail
boolean

If true , returns version children details, such as input and data provider.

Available in: v65.0

Responses

Response samples

Content type
application/json
{
  • "apiName": "string",
  • "childRelationships": {
    },
  • "fields": {
    },
  • "id": "string",
  • "isStandard": true
}

Prompt Template Versions

Create (POST).

Available in: v65.0

Alternate paths

  • /einstein/prompt-templates/{promptTemplateDevName}/versions/{versionId} - By Prompt Template Dev Name and Version ID
path Parameters
promptTemplateDevName
required
string

Developer name of the prompt template.

Request Body schema: application/json
required

Input representation for creating a prompt template.

Available in: v65.0

required
object (EinsteinPromptRecordInput)

Representation of the payload of the template to be created.

Responses

Request samples

Content type
application/json
{
  • "templateInput": {
    }
}

Response samples

Content type
application/json
{
  • "additionalData": {
    },
  • "errorMessages": [
    ],
  • "hasWarning": true,
  • "isSuccessful": true,
  • "statusCode": "string",
  • "templateId": "string",
  • "templateType": "string",
  • "versionId": "string",
  • "warningMessages": [
    ]
}

Prompt Template Versions

Create (POST) and update (PUT) a prompt template version.

Available in: v65.0

Alternate paths

  • /einstein/prompt-templates/{promptTemplateDevName}/versions/{versionId} - By Prompt Template Dev Name and Version ID
path Parameters
promptTemplateDevName
required
string

Developer name of the prompt template.

Request Body schema: application/json
required

Input representation for creating a prompt template.

Available in: v65.0

required
object (EinsteinPromptRecordInput)

Representation of the payload of the template to be created.

Responses

Request samples

Content type
application/json
{
  • "templateInput": {
    }
}

Response samples

Content type
application/json
{
  • "additionalData": {
    },
  • "errorMessages": [
    ],
  • "hasWarning": true,
  • "isSuccessful": true,
  • "statusCode": "string",
  • "templateId": "string",
  • "templateType": "string",
  • "versionId": "string",
  • "warningMessages": [
    ]
}

Prompt Template Versions (By Prompt Template Dev Name and Version ID)

Available in: v65.0

Alternate path for Prompt Template Versions. Variant: By Prompt Template Dev Name and Version ID. Canonical documentation path: /einstein/prompt-templates/{promptTemplateDevName}/versions.

path Parameters
promptTemplateDevName
required
string

Developer name of the prompt template.

versionId
required
string

ID of the version.

query Parameters
includingContent
boolean

If true , returns the version content.

Available in: v65.0

includingVersionDetail
boolean

If true , returns version children details, such as input and data provider.

Available in: v65.0

Responses

Response samples

Content type
application/json
{
  • "apiName": "string",
  • "childRelationships": {
    },
  • "fields": {
    },
  • "id": "string",
  • "isStandard": true
}

Prompt Template Versions (By Prompt Template Dev Name and Version ID)

Available in: v65.0

Alternate path for Prompt Template Versions. Variant: By Prompt Template Dev Name and Version ID. Canonical documentation path: /einstein/prompt-templates/{promptTemplateDevName}/versions.

path Parameters
promptTemplateDevName
required
string

Developer name of the prompt template.

versionId
required
string

ID of the version.

Request Body schema: application/json
required
object (EinsteinPromptRecordInput)

Representation of the payload of the template to be created.

Responses

Request samples

Content type
application/json
{
  • "templateInput": {
    }
}

Response samples

Content type
application/json
{
  • "additionalData": {
    },
  • "errorMessages": [
    ],
  • "hasWarning": true,
  • "isSuccessful": true,
  • "statusCode": "string",
  • "templateId": "string",
  • "templateType": "string",
  • "versionId": "string",
  • "warningMessages": [
    ]
}

Prompt Template Versions (By Prompt Template Dev Name and Version ID)

Available in: v65.0

Alternate path for Prompt Template Versions. Variant: By Prompt Template Dev Name and Version ID. Canonical documentation path: /einstein/prompt-templates/{promptTemplateDevName}/versions.

path Parameters
promptTemplateDevName
required
string

Developer name of the prompt template.

versionId
required
string

ID of the version.

Request Body schema: application/json
required
object (EinsteinPromptRecordInput)

Representation of the payload of the template to be created.

Responses

Request samples

Content type
application/json
{
  • "templateInput": {
    }
}

Response samples

Content type
application/json
{
  • "additionalData": {
    },
  • "errorMessages": [
    ],
  • "hasWarning": true,
  • "isSuccessful": true,
  • "statusCode": "string",
  • "templateId": "string",
  • "templateType": "string",
  • "versionId": "string",
  • "warningMessages": [
    ]
}

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!