Custom fields
/
Update a custom field

Brandfolder OpenAPI Reference (v4)

Welcome to the OpenAPI reference documentation for Brandfolder by Smartsheet!

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
https://brandfolder.com/api/v4/

Assets

Assets are the core resource of Brandfolder. They act like containers that hold all of your digital resources and files, which we call Attachments. They belong to a Section in a Brandfolder and can also exist within many Collections.

Operations

Attachments

Attachments are the representation of digital assets in Brandfolder. Generally speaking, they are actual files but can also be colors, fonts, links to embedded/external media, etc. They belong to an Asset and contain extra metadata related to the files they represent.

Note:

If you need to list all of an organization's attachments, follow these steps:

  1. List all Brandfolders: GET /brandfolders?include=organization
  2. List all sections for each Brandfolder within the target organization: GET /brandfolders/{brandfolder_id}/sections
  3. Iteratively list assets and their attachments for each Section: GET /sections/{section_id}/assets?include=attachments
Operations

Binary upload

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

Binary Upload is a multi-step process:

  1. Get an upload URL
  2. Upload the file to the storage bucket using one of the methods below :
  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.

Tip: 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.

Upload Request Flow

Operations

Brandfolders

Brandfolders are nested directly underneath an Organization in the overall heirarchy. They can have many Collections, Sections, and Assets.

Operations

Collections

Collections are nested under a Brandfolder and contain many Assets. They are mainly used as an additional way to organize, manage, share, and restrict access to a subset of Assets within your Brandfolder without having to upload Assets to multiple places.

Operations

Custom fields

Custom Fields can be assigned to Assets and are generally helpful for organizing and searching Assets within a Brandfolder, as well as for understanding more details about each Asset.

Each Custom Field is essentially a key/value pair associated with exactly one Asset. Keys and values are always a string type, so use "123" instead of 123.

For example, if you have several Assets that represent products you sell in different colors, you might create a Custom Field for each of those Assets with a key of "color" and a value of "blue" or "red", etc. If you modify or delete a "color":"blue" Custom Field for any particular Asset, it will not affect other Custom Fields on other Assets, even if they have the same key and/or value.

IMPORTANT: Think carefully about whether Tags or Custom Fields are better suited to meet the needs of your particular use case.

Operations

List custom field keys

Request

Lists custom field keys for the matching Brandfolder.

Path
brandfolder_idstringrequired

Unique identifier for the resource instance.

Example: oqgiju-21olts-ce9egi
Query
fieldsstring

Set it to value to return it as part of the asset's attributes in the response.

Allowed value: value

WARNING: This parameter can slow response times.

Example: fields=value
includestring

Set it to custom_field_values to return those records related to the asset you're fetching. Related records are returned in an included array in the response.

Allowed value: custom_field_values

WARNING: This parameter can slow response times.

Example: include=custom_field_values
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Acceptstringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
curl -i -X GET \
  'https://brandfolder.com/api/v4/brandfolders/oqgiju-21olts-ce9egi/custom_field_keys?fields=value&include=custom_field_values' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

All custom field keys for the matching Brandfolder.

Bodyapplication/json
dataArray of objects(Custom field key)required
data[].​idstringrequired

Unique identifier for the resource instance.

Example: "plqlkk-22rw6g-3dqgx0"
data[].​typestringrequired

The type of the resource.

Value"custom_field_keys"
data[].​attributesobject(Custom field key attributes)required
data[].​attributes.​namestringrequired

The key name.

Example: "color"
data[].​attributes.​allowed_valuesArray of strings

The value that can be used with this key when creating or updating any Custom Field on an Asset must be one of these strings. If not included or empty array [], the values are unrestricted.

Example: ["red","white","blue"]
data[].​attributes.​positioninteger(int32)>= 0

Sets the location of the custom field among other custom fields in the Brandfolder UI.

Example: 0
data[].​attributes.​prioritizedboolean

Set to true to display the custom field in asset previews. A Brandfolder can have up to five prioritized custom fields.

Example: false
data[].​attributes.​requiredboolean

If set to true, users uploading an asset must input the custom field before uploading the asset. Children of dependent custom fields can also be marked as required.

Example: false
data[].​attributes.​restrictedboolean

If set to true, the field value is restricted to a set of allowed values (see allowed_values); otherwise, the field value is unrestricted.

Example: true
metaobject(Pagination metadata)required

Page context information.

meta.​current_pageinteger(int32)>= 1required
Default 1
Example: 1
meta.​next_pageobject or nullrequired
Default null
Example: null
meta.​prev_pageobject or nullrequired
Default null
Example: null
meta.​total_pagesnumber>= 1required
Default 1
Example: 1
meta.​total_countnumber>= 0required
Default 0
Example: 1
Response
application/json
{
  "data": [
    { … }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

Create custom field keys

Request

Creates custom field keys for the matching brandfolder.

This endpoint is only needed for setting up controlled Custom Fields. If this is enabled for your Brandfolder, you can set the allowed keys and optionally restrict their allowed values for Custom Fields using this endpoint.

Path
brandfolder_idstringrequired

Unique identifier for the resource instance.

Example: oqgiju-21olts-ce9egi
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Acceptstringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Bodyapplication/json

Custom field keys for the matching brandfolder.

dataobjectrequired
data.​attributesArray of objectsrequired
data.​attributes[].​namestring

The key name.

Example: "color"
data.​attributes[].​allowed_valuesArray of strings

The value that can be used with this key when creating or updating any Custom Field on an Asset must be one of these strings. If not included or empty array [], the values are unrestricted.

Example: ["red","white","blue"]
data.​attributes[].​positioninteger(int32)>= 0

Sets the location of the custom field among other custom fields in the Brandfolder UI.

Example: 0
data.​attributes[].​prioritizedboolean

Set to true to display the custom field in asset previews. A Brandfolder can have up to five prioritized custom fields.

Example: false
data.​attributes[].​requiredboolean

If set to true, users uploading an asset must input the custom field before uploading the asset. Children of dependent custom fields can also be marked as required.

Example: false
data.​attributes[].​restrictedboolean

If set to true, the field value is restricted to a set of allowed values (see allowed_values); otherwise, the field value is unrestricted.

Example: true
curl -i -X POST \
  https://brandfolder.com/api/v4/brandfolders/oqgiju-21olts-ce9egi/custom_field_keys \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": [
        {
          "name": "color",
          "allowed_values": [
            "red",
            "white",
            "blue"
          ],
          "position": 0,
          "prioritized": false,
          "required": false,
          "restricted": true
        }
      ]
    }
  }'

Responses

The new custom field keys.

Bodyapplication/json
dataArray of objects(Custom field key)required
data[].​idstringrequired

Unique identifier for the resource instance.

Example: "plqlkk-22rw6g-3dqgx0"
data[].​typestringrequired

The type of the resource.

Value"custom_field_keys"
data[].​attributesobject(Custom field key attributes)required
data[].​attributes.​namestringrequired

The key name.

Example: "color"
data[].​attributes.​allowed_valuesArray of strings

The value that can be used with this key when creating or updating any Custom Field on an Asset must be one of these strings. If not included or empty array [], the values are unrestricted.

Example: ["red","white","blue"]
data[].​attributes.​positioninteger(int32)>= 0

Sets the location of the custom field among other custom fields in the Brandfolder UI.

Example: 0
data[].​attributes.​prioritizedboolean

Set to true to display the custom field in asset previews. A Brandfolder can have up to five prioritized custom fields.

Example: false
data[].​attributes.​requiredboolean

If set to true, users uploading an asset must input the custom field before uploading the asset. Children of dependent custom fields can also be marked as required.

Example: false
data[].​attributes.​restrictedboolean

If set to true, the field value is restricted to a set of allowed values (see allowed_values); otherwise, the field value is unrestricted.

Example: true
metaobject(Pagination metadata)required

Page context information.

meta.​current_pageinteger(int32)>= 1required
Default 1
Example: 1
meta.​next_pageobject or nullrequired
Default null
Example: null
meta.​prev_pageobject or nullrequired
Default null
Example: null
meta.​total_pagesnumber>= 1required
Default 1
Example: 1
meta.​total_countnumber>= 0required
Default 0
Example: 1
Response
application/json
{
  "data": [
    { … }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

List custom fields

Request

Lists custom fields for the matching asset.

Path
asset_idstringrequired

Unique identifier for the resource instance.

Example: oqgkkd-fr5iv4-443db
Query
includestring

Set it to custom_field_key to return those custom field keys related to the asset you're fetching. Related records are returned in an included array in the response.

Allowed value: custom_field_key

WARNING: This parameter can slow response times.

Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Acceptstringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
curl -i -X GET \
  'https://brandfolder.com/api/v4/assets/oqgkkd-fr5iv4-443db/custom_field_values?include=string' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

The custom fields for the asset.

Bodyapplication/json
dataArray of objects(Custom field value)required
data[].​idstringrequired

Unique identifier for the resource instance.

Example: "r79p3j4gbcgtv33gbsqrxb"
data[].​typestringrequired

The type of the resource.

Value"custom_field_values"
data[].​attributesobject(Custom field value attributes)required
data[].​attributes.​keystring

A key name.

Example: "Campaign"
data[].​attributes.​valuestring

The value for the key.

Example: "Fall"
metaobject(Pagination metadata)required

Page context information.

meta.​current_pageinteger(int32)>= 1required
Default 1
Example: 1
meta.​next_pageobject or nullrequired
Default null
Example: null
meta.​prev_pageobject or nullrequired
Default null
Example: null
meta.​total_pagesnumber>= 1required
Default 1
Example: 1
meta.​total_countnumber>= 0required
Default 0
Example: 1
Response
application/json
{
  "data": [
    { … }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

Create custom fields

Request

Creates custom fields for the matching asset.

In order to use this endpoint, you will need to have the Custom Field Key ID for the Custom Field you wish to create. Please see List Custom Field Keys for a Brandfolder to get a list of the Custom Field Key IDs.

Want to learn more about Custom Fields? Check out out our Knowledge Base article on Custom Fields.

Path
custom_field_key_idstringrequired

Unique identifier for the resource instance.

Example: oqgkkd-fr5iv4-443db
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Acceptstringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Bodyapplication/json
dataArray of objectsrequired

A list of custom field associations.

data[].​attributesobjectrequired
data[].​attributes.​valuestringrequired

Custom field key value.

Example: "red"
data[].​relationshipsobjectrequired

Specifies the object receiving the custom field.

data[].​relationships.​assetobjectrequired
data[].​relationships.​asset.​dataobjectrequired
data[].​relationships.​asset.​data.​typestringrequired

The type of target object.

Value"assets"
data[].​relationships.​asset.​data.​idstringrequired

The ID of the asset.

Example: "k5nj2bf5mc36j3ssm63359h"
curl -i -X POST \
  https://brandfolder.com/api/v4/custom_field_keys/oqgkkd-fr5iv4-443db/custom_field_values \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": [
      {
        "attributes": {
          "value": "red"
        },
        "relationships": {
          "asset": {
            "data": {
              "type": "assets",
              "id": "k5nj2bf5mc36j3ssm63359h"
            }
          }
        }
      }
    ]
  }'

Responses

The new custom fields.

Bodyapplication/json
dataArray of objectsrequired
data[].​idstringrequired

Unique identifier for the resource instance.

Example: "r79p3j4gbcgtv33gbsqrxb"
data[].​typestringrequired

The type of the resource.

Value"custom_field_values"
data[].​attributesobjectrequired
data[].​attributes.​keystring

A key name.

Example: "team"
data[].​attributes.​valuestring

The value for the key.

Example: "product"
Response
application/json
{
  "data": [
    { … }
  ]
}

Update a custom field key

Request

Update the matching custom field key.

Warning: It is NOT recommended to update keys that are currently in use. Changing allowed values or whether they are restricted after other values have already been used can lead to undesirable results.

Path
custom_field_key_idstringrequired

Unique identifier for the resource instance.

Example: plqlkk-22rw6g-3dqgx0
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Acceptstringrequired
Value"application/json"
Example: application/json
Bodyapplication/json
dataobjectrequired
data.​attributesobjectrequired
data.​attributes.​namestring

The key name.

Example: "color"
data.​attributes.​allowed_valuesArray of strings

The value that can be used with this key when creating or updating any Custom Field on an Asset must be one of these strings. If not included or empty array [], the values are unrestricted.

Example: ["orange","gray","green"]
curl -i -X PUT \
  https://brandfolder.com/api/v4/custom_field_keys/plqlkk-22rw6g-3dqgx0 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": {
        "name": "color",
        "allowed_values": [
          "orange",
          "gray",
          "green"
        ]
      }
    }
  }'

Responses

The updated custom field key.

Bodyapplication/json
dataobjectrequired
data.​idstringrequired

Unique identifier for the resource instance.

Example: "plqlkk-22rw6g-3dqgx0"
data.​typestringrequired

The type of the resource.

Value"custom_field_keys"
data.​attributesobjectrequired
data.​attributes.​namestring

The key name.

Example: "color"
data.​attributes.​allowed_valuesArray of strings

The value that can be used with this key when creating or updating any Custom Field on an Asset must be one of these strings. If not included or empty array [], the values are unrestricted.

Example: ["orange","gray","green"]
data.​attributes.​positioninteger(int32)>= 0

Sets the location of the custom field among other custom fields in the Brandfolder UI.

Example: 0
data.​attributes.​prioritizedboolean

Set to true to display the custom field in asset previews. A Brandfolder can have up to five prioritized custom fields.

Example: false
data.​attributes.​requiredboolean

If set to true, users uploading an asset must input the custom field before uploading the asset. Children of dependent custom fields can also be marked as required.

Example: false
data.​attributes.​restrictedboolean

If set to true, the field value is restricted to a set of allowed values (see allowed_values); otherwise, the field value is unrestricted.

Example: true
Response
application/json
{
  "data": {
    "id": "plqlkk-22rw6g-3dqgx0",
    "type": "custom_field_keys",
    "attributes": { … }
  }
}

Delete a custom field key

Request

Deletes the matching custom field key.

Warning: Be very careful when using this endpoint as it also deletes all associated values for that key.

Path
custom_field_key_idstringrequired

Unique identifier for the resource instance.

Example: plqlkk-22rw6g-3dqgx0
Headers
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Content-Typestringrequired
Value"application/json"
Example: application/json
curl -i -X DELETE \
  https://brandfolder.com/api/v4/custom_field_keys/plqlkk-22rw6g-3dqgx0 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

Successful response (always an empty object)

Bodyapplication/json
object
Response
application/json
{}

Update a custom field

Request

Update the matching custom field.

Path
custom_field_value_idstringrequired

Unique identifier for the resource instance.

Example: 123456-22mpg8-dfmfi7
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Acceptstringrequired
Value"application/json"
Example: application/json
Bodyapplication/json
dataobjectrequired
data.​attributesobjectrequired
data.​attributes.​valuestring
Example: "Fall"
curl -i -X PUT \
  https://brandfolder.com/api/v4/custom_field_values/123456-22mpg8-dfmfi7 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": {
        "value": "Fall"
      }
    }
  }'

Responses

The updated custom field.

Bodyapplication/json
dataArray of objects(Custom field value)required
data[].​idstringrequired

Unique identifier for the resource instance.

Example: "r79p3j4gbcgtv33gbsqrxb"
data[].​typestringrequired

The type of the resource.

Value"custom_field_values"
data[].​attributesobject(Custom field value attributes)required
data[].​attributes.​keystring

A key name.

Example: "Campaign"
data[].​attributes.​valuestring

The value for the key.

Example: "Fall"
Response
application/json
{
  "data": [
    { … }
  ]
}

Delete a custom field

Request

Deletes the matching custom field.

Path
custom_field_value_idstringrequired

Unique identifier for the resource instance.

Example: 123456-22mpg8-dfmfi7
Headers
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Content-Typestringrequired
Value"application/json"
Example: application/json
curl -i -X DELETE \
  https://brandfolder.com/api/v4/custom_field_values/123456-22mpg8-dfmfi7 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

Successful response (always an empty object)

Bodyapplication/json
object
Response
application/json
{}

Invitations

Invitations are exactly what they sound like and can be created to invite Users to join your Organization, Brandfolder, or Collection as a guest, collaborator, admin, or (when inviting someone to an Organization) owner.

Learn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.

Operations

Labels

Brandfolder's Labels are an enhanced organization and findability feature meant to provide the peace of mind that comes with an organization's existing folder structure. Think of Labels like your music playlists--any asset can be assigned to a label or multiple labels.

Labels are not turned on for every account. If you are unsure whether you have or need Labels, please contact brandfoldersupport@smartsheet.com.

Operations

Organizations

An Organization is the top level resource of all objects in Brandfolder. It can have many Brandfolders nested beneath it.

Operations

Sections

Sections are nested under a Brandfolder and contain many Assets. They exist to help keep Assets organized within a Brandfolder. They also determine which type of digital assets can be uploaded within them (files, external media, fonts, etc.).

Operations

Tags

Tags can be assigned to Assets and are generally helpful for organizing and searching Assets within a Brandfolder.

Each Tag is essentially a keyword associated with exactly one Asset.

For example, if you have several Assets that represent products you sell, you might create a "product" Tag for each one. If you modify or delete the "product" Tag for any particular Asset, it will not affect other Tags with the same value on other Assets.

Tags have a read-only attribute called auto_generated which indicates if the Tag was created automatically by our smart analysis of the file Attachment(s) (true) or if a User created the Tag (false).

IMPORTANT: Think carefully about whether Tags or Custom Fields are better suited to meet the needs of your particular use case.

Operations

User permissions

User permissions describe relationships between Organizations, Brandfolders, Collections, Portals or Brandguides and the users that have access to them.

Learn more about permissioning in our Knowledge Base article on User Permissions.

Operations

Webhooks

The Brandfolder Webhooks service allows you to subscribe to event-based notifications (callbacks) when a qualifying event is triggered within Brandfolder. Asset data will then be sent to the user-provided callback_url at the time the subscribed event occurs within the specified Brandfolder.

NOTE: The callback_url must be accessible from the public internet, meaning any localhost, private network domains, or domains that require authentication will all fail.

Authentication

Utilizing Webhooks requires authentication with the resource (Brandfolder) being subscribed to. A user's unique API Key is required in a header for actions on all endpoints related to the Webhooks service.

There are two required headers in each request:

Content-Type: application/json
Authorization: Bearer <api_key>

The provided API Key is checked against any provided resource (where applicable) to confirm the appropriate permissions.

Service Details

The Brandfolder Webhooks service allows for subscriptions to events within individual Brandfolders.

NOTE: Asset data updates made at the Collection level will trigger a Brandfolder Webhook subscription. Since assets live at the Brandfolder level, any updates made at the Collection level would be reflected on the Brandfolder level as well, thus triggering a Webhook.

Due to the way Brandfolder manages assets, you will see both an "asset.create" event and an "asset.update" event upon creation of a new asset. A create event is triggered when Brandfolder recognizes the new asset and begins to process it for use. An update event is triggered when the asset is ready for use.

The following event types trigger webhooks:

  • asset.create - Asset creation. A new asset has been added to a subscribed Brandfolder.
  • asset.update - Asset update. Asset data has been updated within a subscribed Brandfolder. One or more of the following asset attributes has been updated:
    • Name
    • Description
    • Section
    • Approval status
    • Expiration status
    • Comments & Annotations
      • Adding / Updating
      • Deleting
    • Tags
      • Adding / Updating
      • Deleting
    • Custom Fields
      • Adding / Updating
      • Deleting
  • asset.delete - Asset deletion. An asset has been removed from within a subscribed Brandfolder.

Once a Webhook subscription as been created, the payload that will be sent to the user-provided callback_url after an event has been triggered will have the following structure:

{
    "data": {
        "attributes": {
            "key": "<unique_asset_identifier>",
            "event_time": "<event occurance timestamp in format YYYY-MM-DD HH:MM:SS.000000 with six decimal place microsecond precision>",
            "event_type": "<the event type that triggered the webhook>",
            "brandfolder_key": "<unique_brandfolder_identifier>",
            "organization_key": "<unique_organization_identifier>"
        },
        "webhook_id": "<webhook_id>"
    }
}

NOTE: The callback payload is a "skinny" payload -- it indicates which assets changed and the type of event that occurred, but does not contain any data from the assets themselves.

The Brandfolder Webhook service requires your application to immediately acknowledge receipt of any Webhooks by returning a 2xx HTTP status code. If Brandfolder does not receive an acknowledgement or any non 2xx HTTP status code is returned, Brandfolder will retry the Webhook up to 15 times with exponentially increasing wait times in between.

Any Webhook subscriptions that continue to fail without remedy will be made inactive.

Messages may be sent out of order to the callback_url associated with a Webhook subscription. The event_time provided in the payload can be used to order events.

If the API Key associated with a Webhook subscription loses access to the associated resource, the subscription will be deactivated within 30 minutes.

Operations

Schemas