Guides
/
Recipes
/
Search via collections and sections
Last updated

Search via Collections and Sections

Use Case

Searching in Brandfolder is an incredibly powerful tool and works the same via the API as it does in the Brandfolder UI. Some of the more frequently used searches include sections and collections.

Sections are the broadest way of organizing assets in Brandfolder and are commonly used to separate assets by their category, type, or purpose. For example, a single Files section might be too broad, making it harder to find specific types of images. Instead, you might create one section called Product Shots and one called Event Images to keep these types of assets separate and easier to find.

A Collection is a group of related assets from a Brandfolder. Collections allow you to custom select the most important assets for a certain group of users to see. For example you may have a sales collection for your sales team to access collateral.

Assets are pushed from sections at the Brandfolder level into sections at the Collection level. If assets are not shared from a section at the Brandfolder level into a Collection, then that section will not appear at the Collection level.

Before you Begin

When making requests through the Brandfolder API there are a few items or requirements to keep in mind.

1. The first is authorization headers. For every single request you will need to pass an authorization header in the following format:

Headers: {‘Authorization”: Bearer <api_key>’}

2. The second item is your API key. In the authorization header you will notice that you will also need your API key. To obtain the API key visit: https://brandfolder.com/profile#integrations

3. Finally when using search via the API it’s important to keep formatting requirements in mind. Including a search parameter in an API call will require a properly formatted URL. You can find specific search parameters in the Searching Knowledge Base article. For our example we will be using collection_id. You can also input the search the same way as you would in the UI and use a URL formatter to make sure you get the desired format.

API Workflow

Now let's take a look at the steps you will need to take to search sections and collections via the API.

1. The first step is building the Base URL

2. Second is determining the Collection ID

3. Third is determining the Section ID

We will now go through each of these steps in detail.

We will be using the Sonata travel companies Brandfolder as our example while navigating each of the API Workflow steps. Our goal is to locate all of the assets in a section within a certain collection.

The API key used to make these calls must be from a user that is a member of the collection being used.

1. The first step is locating and using the Brandfolder Base URL

All V4 requests are made through the following Base URL:

https://brandfolder.com/api/v4 + resource endpoint.

2. Since you are wanting to locate all of the assets within a section in a certain collection. The second step is determining the Collection ID.

You can locate all Collection IDs you have access to with:

GET /collections

In this example we will need the collection_id from the collection you want to filter the assets from. You will need:

GET /collections/{collection_id}

And use the returned slug to link to the collection you desire to search in.

https://brandfolder.com/api/v4/collections/{collection_id}

Here is an example a response using the Ad Agency Collection in the Sonata Brandfolder:

Response:

{
   "data": {
       "id": "<collection_id>",
       "type": "collections",
       "attributes": {
           "name": "Ad Agency",
           "slug": "ad-agency-0",
           "tagline": "",
           "public": false,
           "stealth": false,
           "is_workspace": false
       }
   }
}

3. Once we have our collection, we’ll need to include the section as well. You can do this by the taking these steps

You can locate all Section IDs within the collections you have access to with

GET /collections/{collection_id}/sections

When using examples in your code, you will need to add this to the end of your slug to get assets associated with the specific section.

GET /sections/{section_id}/assets

Response:

{
   "data": [
       {
           "id": "<asset_id>",
           "type": "generic_files",
           "attributes": {
               "name": "Countryside Bike Tours",
               "description": null,
               "thumbnail_url": "<url>",
               "approved": true
           }
       },
       {
           "id": "<asset_id>",
           "type": "generic_files",
           "attributes": {
               "name": "Road Trip in Italy",
               "description": null,
               "thumbnail_url": "<url>",
               "approved": true
           }
       },
       {
           "id": "<asset_id>",
           "type": "generic_files",
           "attributes": {
                "name": "Beachside Relaxation",
               "description": null,
               "thumbnail_url": "<url>",
               "approved": true
           }
       },
       {
           "id": "<asset_id>",
           "type": "generic_files",
           "attributes": {
                "name": "Family Vacations",
               "description": null,
               "thumbnail_url": "<url>",
               "approved": true
           }
       }
   ],
   "meta": {
       "current_page": 1,
       "next_page": null,
       "prev_page": null,
       "total_pages": 1,
       "total_count": 4
   }
}

The final search call will then be: https://brandfolder.com/api/v4/collections/{collection}/sections/{section_id}/assets

Here is an example a response using the Ad Agency Collection and the Photography section to filter for assets in the Sonata Brandfolder:

Response:

{
   "data": [
       {
           "id": "<asset_id>",
           "type": "generic_files",
           "attributes": {
               "name": "Countryside Bike Tours",
               "description": null,
               "thumbnail_url": "<url>",
               "approved": true
           }
       },
       {
           "id": "<asset_id>",
           "type": "generic_files",
           "attributes": {
               "name": "Road Trip in Italy",
               "description": null,
               "thumbnail_url": "<url>",
               "approved": true
           }
       },
   ],
   "meta": {
       "current_page": 1,
       "next_page": null,
       "prev_page": null,
       "total_pages": 1,
       "total_count": 2
   }
}

That concludes the specific steps you would take to locate all of the assets in a section within a certain collection through the API.

Part 5: Handling errors

One final thing to note is that errors sometimes may occur while searching via the API. Common ones include:

403: This likely means that your API key does not have access to the assets.

404: This typically occurs when something was misspelled.

429: This occurs when the API key associated with the calls has reached our rate limit threshold.

If your search call succeeds with a 200 but returns no results, verify that the query syntax is correct and compound queries are encoded properly.

Previous page
Next page