Skip to main content

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

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Repository APIs

Updated on April 5, 2022

To interact with any defined repository, use the default repository APIs that are included in Pega Platform. Other methods of interacting with files, such as using custom java, are not supported.

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.
  • Each type of storage follows the consistency model of the underlying storage. For example, Amazon S3 follows the eventual consistency model. If you create or delete a file and immediately use the Exists API, the result might be the opposite of what you expect. Pega Cloud Services File Storage guarantees only eventual consistency.
  • 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.
  • When you are using a cloud deployment, you cannot use a nodes local file system to reliably store data, even if it is used through a repository local file system option. This is because nodes in cloud can be taken down and restarted at any time.

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