List or Add Files to a Library

Resource

The libraryId is the 18 character library ID that has a prefix of 1JD.

HTTP Methods

GET, POST

GET

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

Request parameters for GET

Parameter	Type / Values	Description	Required	Available Version
pageSize	integer (1–200)	Number of file refs per page. Default 50.	No	67.0
offset	integer	Offset into the result set. Default 0.	No	67.0
sortBy	status, createdDate, fileName, fileSize	Sort field. Default status (errors first).	No	67.0
sortOrder	ASC, DESC	Sort direction.	No	67.0
name	string	Filter by file name (case-insensitive contains match).	No	67.0
status	UPLOADED, INDEXING, INDEXED, INDEX_FAILED, DELETING, DELETE_FAILED	Filter by file processing status.	No	67.0

Request body

None.

Response body

HTTP 200 — FileListOutputRepresentation

Property	Type	Description	Available Version
files	array	Current page of GroundingFileRefOutputRepresentation items.	67.0
totalSize	integer	Total number of file references for this library.	67.0
currentPageUrl	string	URL for the current page.	67.0
nextPageUrl	string	URL for the next page (null if last page).	67.0

HTTP 400—Invalid parameters or not an SFDRIVE library.

HTTP 404—Library not found.

POST

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.

Request body

Required. AddFilesInputRepresentation

Property	Type	Description	Required	Available Version
uploadedFiles	array	At least one UploadedFileInfoInputRepresentation.	Yes	66.0

UploadedFileInfoInputRepresentation has these fields.

Property	Type	Description	Required	Available Version
filePath	string	File path returned by /file-upload-urls: $agentforce_data_library$/<libraryId>/<filename>. Must reference the current library; cross-library file paths are rejected with 400. Example: $agentforce_data_library$/1JDSG000007IbWX4A0/user_manual.pdf.	Yes	66.0
fileSize	integer (int64)	Size in bytes.	Yes	66.0

Response body

HTTP 200 — AddFilesOutputRepresentation

Property	Type	Description	Available Version
libraryId	string	Library ID.	66.0
filesAccepted	integer	Number of files accepted.	66.0
groundingFileRefs	array	GroundingFileRefOutputRepresentation for the new files.	66.0

GroundingFileRefOutputRepresentation fields include: fileId, fileName, filePath (example: $agentforce_data_library$/1JDSG000007IbWX4A0/user_manual.pdf), fileSize, status (UPLOADED, INDEXING, INDEXED, INDEX_FAILED, DELETING, DELETE_FAILED), groundingSourceId, createdDate, createdBy, createdById.

HTTP 400—Invalid request (for example, no files, or not SFDRIVE).

HTTP 404—Library not found.