/ developers
For every single request, you will be required to pass an authorization header. That header looks as follows:
Headers: {“Authorization”: “Bearer <api_key>”}
How to find common keys and ids:
__Please note that the terms "keys" and "ids" tend to be use interchangibly across our docs and systems.
GET https://brandfolder.com/api/v4/brandfolders
This will return a list of Brandfolders accessible by the API key in the headers. Parse the returned list of data and
copy the corresponding id from the Brandfolder you are looking for.
GET https://brandfolder.com/api/v4/brandfolders/<brandfolder_key>/sections.
The response will be a list of sections. Find the one with data[“attributes”][“name”] that matches. The key
will live in data[“id”]
Payload:
{
"data": {
"attributes": [
{
"name": "Example Name",
"description": "optional",
"attachments": [
{
"url": "public url",
"filename": "optional"
}
]
}
]
}
}
Brandfolder can load media from any direct public url. This often works well when you are initially migrating content into your Brandfolder. In the case of an initial migration, clients will generally create a “migration” section inside their Brandfolder to contain all migrated material and then will organize according to the internal business rules they have.
Prior to the request, ensure that the public url you provide will remain alive for at least a couple of hours (especially for large files).
POST: https://brandfolder.com/api/v4/brandfolders/<brandfolder_key>/assets
In the case that you want to upload a file from local storage and do not have access to a public URL, you can use our
Upload Requests to successfully upload your content. This is a three step process.
GET https://brandfolder.com/api/v4/upload_requests
From the data sent back grab data[“upload_ur’] and data[“object_url”] ← that is the public url to use in the last stepCURL upload request:
curl -x PUT --data-binary @/path/to/content <data[“upload_url”]>`
data[“object_url”] in place of
public url.Searching in Brandfolder is an incredibly powerful tool and works the same via the API as it does in the Brandfolder UI. One of the more frequently used searches is custom fields.
Custom fields provide a controlled taxonomy tool by adding key/value pairs to your assets. With controlled custom fields that support both single and multi-values, Brandfolder users have what they need to ensure that their asset data is maintained so that it works with the ecosystem of tools and data that you use every day. Better control means better health and accuracy of your digital asset management taxonomy.
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 custom_fields.
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.
These are the steps you will need to take to search custom fields via the API.
1. The first is building the Base URL
2. Second is determining the Brandfolder ID
3. Third is adding the Custom field syntax
4. Fourth is creating the syntax for searching multiple custom fields
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 with a certain custom field in this specific Brandfolder.
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.
Response:
{
"data": [
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Social Desert Oasis Background",
"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": "Scenic Train Rides",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Ocean Background",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
],
"meta": {
"current_page": 1,
"next_page": null,
"prev_page": null,
"total_pages": 1,
"total_count": 25
}
}
2. Since you are wanting to locate all of the assets with a certain custom field in the Sonata Brandfolder. The second step is determining the Brandfolder ID.
When using examples in your code, you will need to GET /brandfolders/{brandfolder_id}
And use the returned slug to link to the Brandfolder you desire to search in.
https://brandfolder.com/api/v4/brandfolders/{brandfolder_id}
Once we have our brandfolder, we’ll need to include assets as well. You can do this by adding the assets endpoint to the end of the call.
https://brandfolder.com/api/v4/brandfolders/{brandfolder_id}/assets
A correct response will look like this - note that the pagination is returning a limited number of results
Response:
{
"data": [
{
"id": "<asset-id>",
"type": "generic_files",
"attributes": {
"name": "Social Desert Oasis Background",
"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": "Scenic Train Rides",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
],
"meta": {
"current_page": 1,
"next_page": null,
"prev_page": null,
"total_pages": 1,
"total_count": 3
}
}
3. Next, add the Custom Field syntax as a parameter.
Brandfolder allows filtering of assets based on certain custom field values. The syntax you will want to use is
?search=custom_fields.{custom_field_key_name}:"{custom_field_value}"
In our example we want to search for all assets that we include in our E-Mail campaigns. Therefore the custom field key, “Channel”, and the custom field value “E-Mail” is what we will want to search on.
?search=custom_fields.Channel:"E-Mail"
The final search call will then be: https://brandfolder.com/api/v4/brandfolders/{brandfolder_id}/assets?search=custom_fields.Channel:"E-Mail"
Response:
{
"data": [
{
"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": "Scenic Train Rides",
"description": null,
"thumbnail_url": "<url>",
"approved": true
}
},
],
"meta": {
"current_page": 1,
"next_page": null,
"prev_page": null,
"total_pages": 1,
"total_count": 2
}
}
4. Let’s say that we want to search not only for our assets associated with E-Mail campaigns but also those assets that are specific to a vacation destination.
We would repeat the steps above but also add on the custom field key “Destination” and the custom field value “Banff”.
https://brandfolder.com/api/v4/brandfolders/{brandfolder_id}/assets?search=custom_fields.Channel:"E-Mail"%20AND%20custom_fields.Destination:"Banff"
Note the URL encoding between the two custom fields. Brandfolder search syntax supports multiple methods of joining queries, just ensure that the query is URL encoded so it functions correctly in our API call.
That concludes the specific steps you would take to search on custom fields through the API.
Errors sometimes may occur while searching custom fields 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 the custom field key or value 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.
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.
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 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.
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}
Response:
{
"data": {
"id": "<collection_id>",
"type": "collections",
"attributes": {
"name": "Ad Agency",
"slug": "ad-agency-0",
"tagline": "",
"public": false,
"stealth": false,
"is_workspace": false
}
}
}
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:
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
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
}
}
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
The final search call will then be:
https://brandfolder.com/api/v4/collections/{collection}/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
}
}
Here is an example a response using the Ad Agency Collection and the Photography section to filter for assets in the Sonata Brandfolder:
That concludes the specific steps you would take to locate all of the assets in a section within a certain collection through the API.
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.
Searching in Brandfolder is incredibly powerful and works the same via the API as it does in the Brandfolder UI. The only distinction between the two is some formatting requirements. Including a search parameter in an API call will require a properly formatted URL. You can find the parameters available to search on in this Knowledge Base article. You can type them as you would in the UI and use a URL formatter like this one to get the desired format.
To search within a Brandfolder, send a request to:
GET https://brandfolder.com/api/v4/brandfolders/<brandfolder_key>/assets?search=<search_query>
GET https://brandfolder.com/api/v4/sections/<section_key>/assets?search=<search_query>
GET https://brandfolder.com/api/v4/collections/<collection_key>/assets?search=<search_query>
?search=label:"<label name"
Note: you can also append additional search parameters here, assuming they have the proper url formatting.
To sync media/content that resides in Brandfolder to an external system, the most effective way to do this is to make use of the Brandfolder webhooks service. At the current time, webhooks are at the Brandfolder level for actions taken on assets. Ultimately this means that, when you create a webhook in a Brandfolder you will get a webhook for any asset action taken in that Brandfolder (depending on the specific subscription).
Available subscriptions:
asset.create → when a new asset is added to a Brandfolderasset.update → certain update actions on an asset (such as name changes, moving between sections, etc)asset.delete → when an asset is deleted in a BrandfolderEach type of subscription can be subscribed to individually. When you are creating your application, you can create an
endpoint to receive Brandfolder webhooks. From there you can make a request to the Brandfolder API to get data about
the asset beyond the asset_key and webhook type. As we will go into, this can be data like which section or collection
the asset belongs to.
In this use case, we want to add an asset from only one specific section to our external system. So for this we will
subscribe to asset.create events in the brandfolder. Upon receipt of a webhook, we parse the payload for key and
make a call to the Brandfolder API for more data on the asset and we will add section to the include parameter.
GET https://brandfolder.com/api/v4/assets/<asset_key>?include=section
To validate, you will need to either store the name of the section or the id of the section you wish to sync in your system.
Grab the payload provided as a response to your GET request and parse the ”included” values and
match against what you have stored.
If your validation returns True we can sync the asset with your external system. To do this, you will need to
fetch the attachments associated with the asset, as these are the actual files. For each asset returned you will grab
the corresponding file url and send that to your external system based on their API. Our recommendation is to always
use the cdn_url since it provides much more flexibility. Advanced users can even manipulate the cdn_url before
sending the file along to resize or change the file type.
To get the attachments:
GET https://brandfolder.com/api/v4/assets/<asset_key>/attachments?fields=cdn_url
If you do not have the CDN included in your plan, you can omit ?fields=cdn_url from your request.
From here, parse the JSON response to grab the appropriate url.
In this use case, we want to add an asset from only one specific section to our external system. So for this we will
subscribe to asset.create events in the brandfolder. Upon receipt of a webhook, we parse the payload for key and
make a call to the Brandfolder API for more data on the asset and we will add section to the include parameter.
GET https://brandfolder.com/api/v4/assets/<asset_key>?include=collections
To validate, you will need to either store the name of the collection or the id of the collection you wish to sync in your system.
Grab the payload provided as a response to your GET request and parse the ”included” key for the id or name and
match against what you have stored.
If your validation returns True we can sync the asset with your external system. To do this, you will need to
fetch the attachments associated with the asset, as these are the actual files. For each asset returned you will grab
the corresponding file url and send that to your external system based on their API. Our recommendation is to always
use the cdn_url since it provides much more flexibility. Advanced users can even manipulate the cdn_url before
sending the file along to resize or change the file type.
To get the attachments:
GET https://brandfolder.com/api/v4/assets/<asset_key>/attachments?fields=cdn_url
If you do not have the CDN included in your plan, you can omit ?fields=cdn_url from your request.
From here, parse the JSON response to grab the appropriate url.
Response:
{
"data": {
"id": "<user-id>",
"type": "users",
"attributes": {
"email": "",
"first_name": "",
"last_name": ""
}
}
}
GET: https/brandfolder.com/api/v4/users/whoami