Today we're announcing a few updates for the current CMS Files API.

First, we're releasing new versions of the endpoints used to upload and replace files in the HubSpot Files tools. We're also sunsetting the use of the previous endpoint for uploading new files.

Second, we're releasing a new endpoint that will let you update the access setting of files previously uploaded to a HubSpot account.

Third, we're releasing a new endpoint that will let you get a signed URL for a private file, allowing your integration to get the content for these files.

What's changing with the updated endpoints?

The new version of the upload endpoint requires you to explicitly set the "access" property for the file being uploaded. The options for file privacy will be:

• PUBLIC_INDEXABLE - The file URL will be publicly accessible by anyone who has or guesses the file URL. Search engines will be able to index the file when published on a page or added to a sitemap.
• PUBLIC_NOT_INDEXABLE - The file URL will be publicly accessible by anyone who has or guesses the file URL. Search engines are instructed not to index the file using the X-Robots-Tag: noindex header.
• PRIVATE - The file URL will be private and requires a temporary signed URL to access. Search engines will not be able to index the file.

The new access setting must be included in the new JSON options field in the request. Any requests without this access field will return an error. This new JSON field replaces the hidden=true query parameter of the current endpoint.

The new access settings differ slightly from how the hidden=true parameter worked. With the old hidden parameter, the file would be marked as both private and hidden. When a file is hidden it means that it would not appear in the files tools. With the new settings, files can no longer be hidden from users in the Files tools through the API, only marked as inaccessible from outside the HubSpot account.

In addition to the access setting, the new endpoint requires that a folder path be set for the file.

To make it easier to manage the files created by your integration, we strongly recommend uploading all of your files to a dedicated folder created by your integration.

The rest of the format of the request remains the same, with the addition of new fields for some new features:

• A time to live (TTL) can now be set, which will automatically delete the file after the specified time, and
• You can check for duplicate files during the upload.

The new endpoint to replace an existing file works similarly to the new upload endpoint, with the same options field, and the same requirement to set the access setting and folder path in the request. 

What are the new endpoints?

The first new endpoint will let you update the access setting of your previously uploaded files to HubSpot. This endpoint allows you to update multiple files at a time, either by specifying specific files by their file ID, or by the ID of their containing folder. Multiple files and folders can be specified in a single request.

These updates are made asynchronously, so there's an additional endpoint used to check the status of the update task.

The last endpoint can be used to get a signed URL for a private file. Private files cannot be accessed by their URL alone. You can use this endpoint to get a signed URL that will allow temporary access to the file.

Note that for files that are both private and hidden (such as files uploaded as attachments to CRM records), you will need the new files.ui_hidden.read scope when accessing this endpoint using OAuth. See the documentation for more details about the new scope.

When is this happening?

All of these new endpoints are available today, and can be used immediately. See the documentation for more details:

• Upload a new file
• Replace an existing file
• Update the accessibility of existing files
• Check the status of a file accessibility update task
• Get a signed URL for a private file

Additionally, with this new release, the current version of the endpoint for uploading files will no longer be available. Any new integrations must use the new upload endpoint effective immediately. If you have an existing integration that is already uploading files, we'll be reaching out to you directly with more details.

Please let us know if you have any questions by joining the discussion in our community.