openapi: 3.0.3
servers:
- url: https://brandfolder.com/api/v4
info:
title: Brandfolder OpenAPI Reference
version: v4
description: >
Welcome to the OpenAPI reference documentation for Brandfolder by
Smartsheet!
tags:
- name: assets
x-displayName: Assets
description: >
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.
- name: attachments
x-displayName: Attachments
description: >
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`
- name: binary_upload
x-displayName: Binary upload
description: >
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](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget)
2. Upload the file to the storage bucket using one of the methods below
:
- [Upload a file](/api/brandfolder/openapi/binary_upload/opidstorageservicebfuploadrequestbucketput)
- [Resumable upload](/api/brandfolder/openapi/binary_upload/opidstorageservicebfuploadrequestpost)
3. [Create an
asset](/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost),
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.
- name: brandfolders
x-displayName: Brandfolders
description: >
Brandfolders are nested directly underneath an Organization in the overall
heirarchy. They can have many Collections, Sections, and Assets.
- name: collections
x-displayName: Collections
description: >
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.
- name: custom_fields
x-displayName: Custom fields
description: >
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.
- name: invitations
x-displayName: Invitations
description: >
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 <a
href="https://help.smartsheet.com/115002602273-User-Permissions"
target="_blank">User Permissions</a>.
- name: labels
x-displayName: Labels
description: >
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.
- name: organizations
x-displayName: Organizations
description: >
An Organization is the top level resource of all objects in Brandfolder.
It can have many Brandfolders nested beneath it.
- name: sections
x-displayName: Sections
description: >
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.).
- name: tags
x-displayName: Tags
description: >
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.
- name: user_permissions
x-displayName: User permissions
description: >
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 <a
href="https://help.smartsheet.com/115002602273-User-Permissions"
target="_blank">User Permissions</a>.
- name: webhooks
x-displayName: Webhooks
description: >
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.
<h2>Authentication</h2>
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.
- Find your API key at <a
href="https://brandfolder.com/profile#integrations"
target="_blank">https://brandfolder.com/profile#integrations</a>.
- Click the icon to the right of your key to copy it to your clipboard.
There are two required headers in each request:
`Content-Type: application/json` <br>
`Authorization: Bearer <api_key>`
The provided API Key is checked against any provided resource (where
applicable) to confirm the appropriate permissions.
___
<h2>Service Details</h2>
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:
```json
{
"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.
paths:
/brandfolders:
parameters:
- in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/json
example: application/json
- in: header
name: Accept
required: true
schema:
type: string
enum:
- application/json
example: application/json
- $ref: '#/components/parameters/Authorization'
get:
operationId: list-brandfolders
summary: List Brandfolders
description: |
Lists all Brandfolders for a User. Unauthorized requests will return an
empty list.
You can use the returned `slug` attribute to form a link to the desired
Brandfolder like so:
````
https://brandfolder.com/{slug}
````
tags:
- brandfolders
parameters:
- in: query
name: fields
description: >
Set it to a comma-separated list (no spaces) of any of the following
attributes of the Brandfolders
to return as part of the Brandfolders' attributes in the response.
Allowed values:
- asset_count
- attachment_count
- storage
WARNING: This parameter can slow response times.
schema:
type: string
example: asset_count,attachment_count,storage
- in: query
name: include
description: >
Set it to a comma-separated list (no spaces) of any of the following
record names to return those records related to the Brandfolders
you're fetching. Related records are returned in an `included` array
in the response.
Allowed values:
- organization
- collections
- assets
WARNING: This parameter can slow response times.
schema:
type: string
example: organizations
- in: query
name: search
description: >
Set it to any URL-encoded query to fetch only Brandfolders that
match your criteria.
WARNING: This parameter can slow response times.
schema:
type: string
example: extension:png
responses:
'200':
description: |
References to all the user's Brandfolders.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Brandfolder'
meta:
$ref: '#/components/schemas/PaginationMetadataResponse'
required:
- data
- meta
default:
description: Generic error payload
content:
application/json:
schema:
type: string
/brandfolders/{brandfolder_id}:
parameters:
- name: brandfolder_id
in: path
schema:
type: string
required: true
description: Unique identifier for the resource instance.
example: oqgiju-21olts-ce9egi
- in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/json
example: application/json
- in: header
name: Accept
required: true
schema:
type: string
enum:
- application/json
example: application/json
- $ref: '#/components/parameters/Authorization'
get:
operationId: opIdApiV4BrandfoldersByIdGet
tags:
- brandfolders
summary: Fetch a Brandfolder
description: |
You can use the returned `slug` attribute to form a link to the desired
Brandfolder like so:
````
https://brandfolder.com/{slug}
````
parameters:
- in: query
name: fields
description: >
Set it to a comma-separated list (no spaces) of any of the following
attributes of the Brandfolder
to return as part of the Brandfolder's attributes in the response.
Allowed values:
- asset_count
- attachment_count
- section_count
WARNING: This parameter can slow response times.
schema:
type: string
example: asset_count,attachment_count,section_count
- in: query
name: include
description: >
Set it to a comma-separated list (no spaces) of any of the following
record names to return those records related to the Brandfolder
you're fetching. Related records are returned in an `included` array
in the response.
Allowed values:
- organization
- collections
- search_filters
- sections
WARNING: This parameter can slow response times.
schema:
type: string
example: organizations
responses:
'200':
description: |
A reference to the Brandfolder.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Brandfolder'
required:
- data
put:
operationId: opIdApiV4BrandfoldersByIdPut
summary: Update a Brandfolder
description: Updates the matching Brandfolder.
tags:
- brandfolders
parameters:
- in: header
name: Accept
required: true
schema:
type: string
enum:
- application/json
example: application/json
requestBody:
description: |
Attribute updates for the Brandfolder.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
name:
type: string
description: A new name for the Brandfolder.
example: Updated Brandfolder
privacy:
type: string
description: A new privacy setting for the Brandfolder.
example: public
slug:
type: string
description: A new URL-friendly slug for the Brandfolder.
example: updated-brandfolder
tagline:
type: string
description: A new tagline for the brandfolder.
example: Updated Brandfolder tagline!
required:
- attributes
required:
- data
responses:
'200':
description: |
The updated Brandfolder.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: Unique identifier for the resource instance.
example: oqgkkd-fr5iv4-hh142d
type:
type: string
description: The type of the resource.
enum:
- brandfolders
attributes:
type: object
properties:
name:
type: string
description: The name of the Brandfolder.
example: Updated Brandfolder
privacy:
type: string
description: The privacy setting of the Brandfolder.
example: public
slug:
type: string
description: The URL-friendly slug of the Brandfolder.
example: updated-brandfolder
tagline:
type: string
description: The tagline for the brandfolder.
example: Updated Brandfolder tagline!
required:
- name
- privacy
- slug
- tagline
required:
- attributes
required:
- data
default:
description: Generic error payload
content:
application/json:
schema:
type: string
/brandfolders/{brandfolder_id}/collections:
parameters:
- name: brandfolder_id
in: path
schema:
type: string
required: true
description: Unique identifier for the resource instance.
example: oqgiju-21olts-ce9egi
- in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/json
example: application/json
- in: header
name: Accept
required: true
schema:
type: string
enum:
- application/json
example: application/json
- $ref: '#/components/parameters/Authorization'
get:
operationId: opIdApiV4BrandfoldersCollectionsByBrandfolderIdGet
summary: List collections in a Brandfolder
description: >
List all collections in the Brandfolder.
You can use the returned `slug` parameter (in conjunction with the slug
of
the parent Brandfolder) to form a link to the desired Collection like
so:
```
https://brandfolder.com/{brandfolder_slug}/{collection_slug
```
tags:
- collections
responses:
'200':
description: |
All the collections in the Brandfolder.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Collection'
meta:
$ref: '#/components/schemas/PaginationMetadataResponse'
required:
- data
- meta
default:
description: Generic error payload
content:
application/json:
schema:
type: string
post:
operationId: opIdApiV4BrandfoldersCollectionsByBrandfolderIdPost
summary: Create a collection
description: Creates a collection in the matching Brandfolder.
tags:
- collections
requestBody:
description: |
Attribute values for the collection.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
name:
type: string
description: A name.
example: My collection
slug:
type: string
description: >
A URL-friendly slug. Use only letters, numbers,
hyphens, and
underscores.
NOTE: We recommend **not** to invent your own slug.
If it is
not unique and valid, the request fails with a `422`
error.
Default is to automatically assign a slug based on
`name` (a
name of \"My Collection\" would make a slug of
\"my-collection\").
example: my-collection
tagline:
type: string
description: A tag line.
example: My collection tag line
required:
- name
required:
- attributes
required:
- data
responses:
'200':
description: |
The new collection.
content:
application/json:
schema:
$ref: '#/components/schemas/Collection'
default:
description: Generic error payload
content:
application/json:
schema:
type: string
/brandfolders/{brandfolder_id}/custom_field_keys:
parameters:
- name: brandfolder_id
in: path
schema:
type: string
required: true
description: Unique identifier for the resource instance.
example: oqgiju-21olts-ce9egi
- in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/json
example: application/json
- in: header
name: Accept
required: true
schema:
type: string
enum:
- application/json
example: application/json
- $ref: '#/components/parameters/Authorization'
get:
operationId: opIdApiV4BrandfoldersCustomFieldKeysByBrandfolderIdGet
summary: List custom field keys
description: |
Lists custom field keys for the matching Brandfolder.
tags:
- custom_fields
parameters:
- in: query
name: fields
description: >
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.
schema:
type: string
example: value
- in: query
name: include
description: >
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.
schema:
type: string
example: custom_field_values
responses:
'200':
description: |
All custom field keys for the matching Brandfolder.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomFieldKey'
meta:
$ref: '#/components/schemas/PaginationMetadataResponse'
required:
- data
- meta
default:
description: Generic error payload
content:
application/json:
schema:
type: string
post:
operationId: opIdApiV4BrandfoldersCustomFieldKeysByBrandfolderIdPost
summary: Create custom field keys
description: >
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.
tags:
- custom_fields
requestBody:
description: Custom field keys for the matching brandfolder.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: array
items:
type: object
properties:
name:
type: string
description: The key name.
example: color
allowed_values:
type: array
description: >-
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.
items:
type: string
example:
- red
- white
- blue
position:
type: integer
format: int32
description: >-
Sets the location of the custom field among other
custom fields in the Brandfolder UI.
minimum: 0
example: 0
prioritized:
type: boolean
description: >-
Set to `true` to display the custom field in asset
previews. A Brandfolder can have up to five
prioritized custom fields.
example: false
required:
type: boolean
description: >-
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
restricted:
type: boolean
description: >-
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
required:
- name
required:
- attributes
required:
- data
responses:
'200':
description: |
The new custom field keys.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/co
# --- truncated at 32 KB (206 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brandfolder/refs/heads/main/openapi/brandfolder-openapi-original.yml