Media Bridge — Does `folderPath` support multiple folder levels or only single-level folders?

[AbhayHayaran]

Hi HubSpot team,

I’m building a custom Media Bridge provider to embed assets from a third-party app and facing an issu

e with the folder browsing panel inside the HubSpot asset selector.

I provide folderPath values for each media object as described in the documentation. For example:

"folderPath": "Brand/Assets/Videos/Promo"

Search works correctly, and all the media objects appear as expected.
However, the Browse folders panel always shows an empty tree — even though HubSpot internally returns a list of folder paths such as:

[ "brand/assets/videos/promo", "brand/assets/images/product" ]

After some testing, it seems HubSpot may not support multi-level folder paths and treats the entire string as a single flat folder name. Because of that, the UI fails to build a nested folder structure and Browse appears empty.

Before I finalize the implementation, can you please confirm:

Does the Media Bridge folderPath field support hierarchical folder structures (multiple levels separated by /), or is only a single-level folder name supported?

And if only one level is supported, is the recommended approach to:

• send only the last folder segment, or

• concatenate multiple levels using hyphens or another separator?

Any clarification would be very helpful so we can align the integration with HubSpot’s expected behavior.

Thank you!

[BérangèreL]

Hi @AbhayHayaran and welcome, it's a pleasure to have you here!

Thanks for asking the HubSpot Community!

I'd love to put you in touch with our Top Experts: Hi @sylvain_tirreau, @Anton and @tmcginnis do you have suggestions to help @AbhayHayaran, please?

Thanks so much and have a great day!
Bérangère

Please note that our forum is a peer-to-peer support forum and all of our members are volunteers.

[AbhayHayaran]

Hi @BérangèreL, thanks for tagging the experts! Really appreciate the help.

Just adding a clearer summary so it’s easier for the right expert to weigh in:

Issue:
folderPath on Media Bridge objects appears to show correctly in search results, but the Browse folders view stays empty.

Observation:
HubSpot internally transforms folderPath → lowercase.
Example:

My object stores: Monobrand - Technical Solutions/Monobrand Media Library/After Effects/Adobe Link Demo

HubSpot’s folder API returns:
monobrand - technical solutions/monobrand media library/after effects/adobe link demo

Question:
👉 Does Media Bridge actually support multi-level folder paths (with / slashes) in folderPath, or is only a single-level folder supported?

Since there is no clear info available in your documentation, nor there is any example, this will help us finalize the correct implementation behavior.

Thanks again for your time!

[BérangèreL]

Hi @AbhayHayaran and thanks for the additional details!

Based on the Media Bridge API documentation, yes, folderPath does support multi-level folder paths with forward slashes (/).
 

According to the API guide, the hs_folder_path property is described as: "A provider-supplied path to the object, intended to represent the object's location in the third party's folder system (if any).

HubSpot will attempt to represent this directory structure when displaying these objects to the user."
 

The documentation confirms that HubSpot attempts to represent the directory structure you provide. However, note that HubSpot may transform the path to lowercase and may nest your provider's objects within a top-level folder named after your provider.
 

If the Browse folders view is empty despite correct search results, this may be a display issue rather than a path support limitation.

I'd recommend checking if the lowercase transformation is affecting folder matching.

And here is the documentation for reference: "CMS API | Media Bridge".

I'd love to put you in touch with our Top Experts: Hi @SteveHTM, @Christensen and @zach_threadint do you have other suggestions to help @AbhayHayaran, please?

Thanks so much and have a brilliant day!
Bérangère

This post was created with the assistance of AI tools.

[AbhayHayaran]

Thanks for the response. I’d like to add a key finding that narrows this down further. I confirmed that Browse Folders works correctly when folderPath contains only a single segment, for example:

folderPath: "approved-assets"

In this case, the folder is immediately visible when clicking Browse folders.

However, when I use multi-level folder paths, for example:

folderPath: "brand/assets/videos"

the following behavior occurs:

• Assets are indexed correctly

• Search returns results as expected

• /api/media-bridge/v1/folders/... returns the folder paths

• Browse folders view is empty

This behavior is consistent regardless of:

• casing (original vs forced lowercase),

• enforcing a single constant root,

• or provider configuration.

Based on this, it appears that while the Media Bridge API accepts and indexes multi-level hs_folder_path values, the Browse Folders UI only renders single-level folder paths.

Could someone from the Media Bridge / CMS engineering team confirm whether:

• Browse folders currently supports only one folder depth for Media Bridge providers, or

• this is a known limitation or bug in the folder tree rendering?

This would help clarify whether multi-level folder hierarchies are officially supported in the Browse UI or if a flat structure is currently required.