Brandfolder Binary Upload

Overview

Brandfolder's Binary Upload service allows for authenticated users to upload locally stored files into Brandfolder via our API.

Authentication

Authentication is performed with every API call by sending a header with your unique Brandfolder API key.

• Find your API key at https://brandfolder.com/profile#integrations.

• Click the icon to the right of your key to copy it to your clipboard.

• Use the key in your code when making requests to our API.

The required header in each request is:

Authorization: Bearer {BF_API_KEY}

Each response to your API calls will only include the resources that you (or the User whose API key your application is using) can access based on your permissions.

Service Details

We recommend that you use the Resumable Upload flow if you have poor internet connection, you're uploading local files that are larger than 200MB or if you're uploading files from a server that are larger than 500MB.

Binary Upload is a multi-step process:

1. Request an Upload URL
2. Upload the file to the storage bucket using one of the methods below :
   • Upload the file to that Upload URL
   • Upload the file using a Reusable Upload URL
3. Create an Asset, telling the Brandfolder API the attachment is at that URL

The Brandfolder Upload Request endpoint will return a response body with a signed upload_url, resumable_upload_url, storage service_type and object_url.

Each Binary Upload request_url and object_url are designed to be used one time for a singular Asset. Both the upload_url and resumable_upload_url will expire 24 hours after they're issued. Assets uploaded to the object_url will be stored for 7 days before being purged. Should any of these URLs expire, you will simply need to restart the workflow to obtain active URLs.

Request an Upload URL

Example Request

curl -X GET 'https://brandfolder.com/api/v4/upload_requests' \
--header 'Authorization: Bearer {BF_API_KEY}' \

GET https://brandfolder.com/api/v4/upload_requests

JSON Response from GET /upload_requests:

{
  "upload_url": "a signed upload_url that allows a user to PUT a file",
  "resumable_upload_url": "a signed URL that allows a user to resume PUT operations for a file",
  "service": "storage service type",
  "object_url": "attachment URL to provide to the Brandfolder create asset API call"
}

Upload a File

NOTE: Non-Resumable Uploads use the PUT method on initial creation

PUT <upload_url>

To upload file data to the storage bucket, copy the upload_url provided from the upload_request response body. Create a PUT request with a path to the file binary.

Example PUT request for the <upload_url>

curl -X PUT \
   --data-binary @/path/to/my-file \
   https://storageservice.com/bf-upload-request-bucket/signed-upload-url

Resumable Upload

NOTE: Resumable Uploads use the POST method on initialization and the PUT method after to resume upload.

POST <resumable_upload_url>

Users uploading larger files and/or with poor connectivity can initiate a resumable upload session with the resumable_upload_url from the upload_request body.

Google provides some great documentation on resumable uploads (as the content will be uploaded to Google Cloud Storage).

Example POST Request to initiate resumable_upload_url session

$ curl -v -X POST \
    -H'x-goog-resumable: start' \
    -H'Content-Type: image/png' \
    https://stoageservice.com/bf-upload-request/signed-resumable-upload-url

Example Response

< HTTP/2 201
< content-type: text/plain; charset=utf-8
< location: https://storageservice.com/bf-upload-request/signed-resumable-upload-url

Example PUT to upload to the resumable_upload_url. Upload data using the URL provided in location

$ curl -X PUT \
    -H'Content-Type: image/png' \
    --data-binary @/path/to/my-file \
    https://storageservice.com/bf-upload-request/signed-resumable_upload_url

Create an Asset

POST https://brandfolder.com/api/v4//brandfolders/{brandfolder_id}/assets

Refer to the API documentation for Creating an Asset in Brandfolder. You'll need to specify the object_url that you received from the /upload_request response body in the URL field when creating the Asset.

Example POST Request Body

{
"data": {
  "attributes": [
    {
      "name": "Brandfolder Logo",
      "description": "Brandfolder's logo in print ready format",
      "attachments": [
        {
          "url": "https://storageservice.com/bf-upload-request-bucket/signed-upload-url",
          "filename": "brandfolder_logo.pdf"
        }
      ]
    }
  ]
},
"section_key": "oqgol8-dslwxs-58b2z3"
}