Brandfolder API Recipes

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.

• Brandfolder id: to find a Brandfolder key, make a request to

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.

• Section key: to find a section key, first you will need the Brandfolder key of the associated Brandfolder. Once obtained, make a request to

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”]

• User API key: This can be found at https://brandfolder.com/profile#integrations

Uploading Media to Brandfolder

Payload:

{
"data": {
    "attributes": [
    { 
        "name": "Example Name", 
        "description": "optional", 
        "attachments": [
             {
              "url": "public url",
              "filename": "optional"
             }
          ]
        } 
    ]
  }
}

Use Case: Uploading from public cloud system

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

Use Case: Uploading from private system

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.

1. You need to request an upload url that Brandfolder can use for the file. 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 step

CURL upload request:

curl -x PUT --data-binary @/path/to/content <data[“upload_url”]>`

1. Upload the file.
2. Create the asset in Brandfolder following the normal upload media recipe and utilize data[“object_url”] in place of public url.

Search via API

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.

Use Case: Searching for specific content in a Brandfolder

To search within a Brandfolder, send a request to:

GET https://brandfolder.com/api/v4/brandfolders/<brandfolder_key>/assets?search=<search_query>

Use Case: Searching for specific content in a section:

GET https://brandfolder.com/api/v4/sections/<section_key>/assets?search=<search_query>

Use Case: Searching for specific content in a collection:

GET https://brandfolder.com/api/v4/collections/<collection_key>/assets?search=<search_query>

Use Case: Searching for specific content in a label

?search=label:"<label name"

Note: you can also append additional search parameters here, assuming they have the proper url formatting.

Sync Media from Brandfolder

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 Brandfolder
• asset.update → certain update actions on an asset (such as name changes, moving between sections, etc)
• asset.delete → when an asset is deleted in a Brandfolder

Each 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.

Use Case: Syncing a specific section with an external system

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.

Use Case: Syncing a specific collection with an external system

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.

Get User Account Information

Response:

{
"data": {
    "id": "<user-id>", 
    "type": "users",
    "attributes":  { 
        "email": "", 
        "first_name": "", 
        "last_name": ""
        } 
    }
}

Use Case: Determine the account owner for the user associated with your integration

GET: https/brandfolder.com/api/v4/users/whoami

Organizing a Brandfolder

Custom Fields payload:

{
  "data": {
    "attributes": [
      {
        "key": "<custom_field_key>",
        "value": "<custom_field_value>"
        },
      {
        "key": "<custom_field_key_2>",
        "value": "<custom_field_value_2>"
        }
      ]
  }
}

Use Case: Applying custom fields

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>"
        }
      ]
  }
}

Use Case: Applying tags

To add tags an asset, send a request to: POST https://brandfolder.com/api/v4/assets/<asset_id>/tags