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 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
Custom Fields payload:
{
"data": {
"attributes": [
{
"key": "<custom_field_key>",
"value": "<custom_field_value>"
},
{
"key": "<custom_field_key_2>",
"value": "<custom_field_value_2>"
}
]
}
}
To add custom fields for an asset, send a request to:
POST https://brandfolder.com/api/v4/assets/<asset_id>/custom_fields
Tags payload:
{
"data": {
"attributes": [
{
"name": "<tag_name>"
},
{
"name": "<tag_name_2>"
}
]
}
}
To add tags an asset, send a request to:
POST https://brandfolder.com/api/v4/assets/<asset_id>/tags