Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Repository APIs

Updated on May 6, 2021

Interact with any defined repository by using the default repository APIs that are included in Pega Platform.

For example, you can delete or retrieve a file in a repository. You can also add a new custom repository type so that your application can manage files in a remote file storage repository using the same API that you use for your default repository types. For more information about configuring custom repositories, see Creating a custom repository type.

Pega Cloud Services File Storage notes

For Pega Cloud services systems, the default storage repository is Pega Cloud services File Storage, which appears as pegacloudfilestorage in the list of repositories in Records SysAdminRepository.

To manage your files in a Pega Cloud File Storage repository from within a Pega Platform application, use the Repository API to interact with your files or configure a file listener to process your files. Direct access to files using any method other than the Repository API is not supported. For more information, see Configuring a file service and file listener to process data in files on Pega Community.

To manage your files in a Pega Cloud File Storage repository from an external application, you can use the optional SFTP service. For more information, see Configuring custom SFTP and FTPS implementations for Pega applications on Pega Community.


Implement repository APIs by creating an activity that an existing data page can call. You must delegate the data page API to custom extension points in the form of 'py' activities to be implemented in the custom class. For example, Embed-Repository-Type-S3 and Embed-Repository-Type-Azure each have different 'py' activities.

Refer to the pyNewFile activity in the Embed-Repository-Type-S3 class for an example of implementing the pyNewFile activity for the custom repository type. For usage documentation of these APIs, see the History tab of each API's data page implementation in Dev Studio.

Repository notes and considerations

Some limitations apply when you build custom repository types by using repository APIs.

  • Pega repository APIs cannot operate on artifacts created outside of Pega, such as S3 buckets, Azure containers, JFrog artifactories, or any files, blobs, or folders in them, that contain any of the following characters: "\", "?", "*", "<", ">", "|", and ":", Either only operate on artifacts created using the Pega repository APIs or avoid using these illegal characters when you create artifacts outside of Pega.
  • Unlike Amazon S3, Microsoft Azure does not support the creation of an empty folder. To support the new folder API, when you invoke D_pxNewFolder, the Repository Manager creates an empty BLOB named $.PEGA$ under that folder.
  • When you use the get file API, D_pxGetFile, the file content is loaded into memory as a base-64 encoded string. When the size of the file to be read is larger than 45 MB, an exception is thrown and the content is not loaded into memory. You can configure the maximum file size by using the repository/maxFileSizeInMemory dynamic system setting in the Pega-IntegrationEngine ruleset.
  • The Import/Export wizard does not support custom repositories.
  • The storage type referenced in your repository API follows the consistency model of the underlying storage provider. For example, Amazon S3 recently transitioned from an eventual consistency model to a strong consistency model, so any of your repository APIs that reference S3 buckets guarantees strong consistency. This includes the Pega Cloud services File Storage Repository in Pega Cloud environments.
  • If you switch from database storage to repository storage, you cannot switch back to database storage without losing access to case attachments stored in the repository.
  • Create folder API

    The create folder API is a savable data page, D_pxNewFolder. The API represents the new folder as a data page when the data page is loaded.

  • Create file API

    The create file API is a savable data page, D_pxNewFile. The API represents the new file as a data page when it is loaded. You can use this API to create a file or overwrite an existing file.

  • Get file API

    The get file API is a read-only data page, D_pxGetFile. This API loads content or a stream to a file when the data page is loaded.

  • List files API

    The list files API is a read-only data page, D_pxListFiles. This API lists files and folders in a specific a folder on a repository.

  • Exists API

    The exists API is a when rule, pxExists. This API returns a true Boolean value if the folder or file exists.

  • Delete API

    The delete API is a read-only data page, D_pxDelete. This API deletes a specific file or folder in a repository.

  • Is authenticated API

    The is authenticated API is a read-only data page, D_pxIsAuthenticated. This API returns a true Boolean value if a user or system is authenticated with a specific repository.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us