# Brandfolder OpenAPI Reference Welcome to the OpenAPI reference documentation for Brandfolder by Smartsheet! Version: v4 ## Servers ``` https://brandfolder.com/api/v4 ``` ## Security ### APIToken API Token. Type: http Scheme: bearer ## Download OpenAPI description [Brandfolder OpenAPI Reference](https://developers.smartsheet.com/_bundle/api/brandfolder/openapi.yaml) ## 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. ### List assets in a collection - [GET /collections/{collection_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbycollectionidget.md): Lists assets in a collection. ### Create assets in a collection - [POST /collections/{collection_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbycollectionidpost.md): Creates assets in the matching collection. Any files you wish to use as an Attachment in Brandfolder must be hosted at a publicly available URL (until they have been successfully imported). If you need to upload file contents directly to a server, you can use do a binary file upload to our temporary storage bucket and then use that URL when creating Assets/Attachments. ### List assets in a section - [GET /sections/{section_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4sectionsassetsbysectionidget.md): Lists assets in the matching section. ### List assets in a Brandfolder - [GET /brandfolders/{brandfolder_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4brandfoldersassetsbybrandfolderidget.md): Lists assets in a Brandfolder. ### Create assets in a Brandfolder - [POST /brandfolders/{brandfolder_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost.md): Creates assets in the matching Brandfolder. Any files you wish to use as an Attachment in Brandfolder must be hosted at a publicly available URL (until they have been successfully imported). If you need to upload file contents directly to a server, you can use do a binary file upload to our temporary storage bucket and then use that URL when creating Assets/Attachments. > NOTE: To create an asset from a binary upload, copy the object_url value from the [Get an upload URL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget) response into your request body's attachments.url property. ### Fetch an asset - [GET /assets/{asset_id}](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4assetsbyidget.md): Fetches the matching asset. ### Update an asset - [PUT /assets/{asset_id}](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4assetsbyidput.md): Updates the matching asset. > Note: All attributes are optional when updating. Only include the ones you want to change. Any files you wish to use as an Attachment in Brandfolder must be hosted at a publicly available URL (until they have been successfully imported). If you need to upload file contents directly to a server, you can use do a binary file upload to our temporary storage bucket and then use that URL when creating Assets/Attachments. ### Delete an asset - [DELETE /assets/{asset_id}](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4assetsbyiddelete.md): Removes the matching asset. ### List tags for an asset - [GET /assets/{asset_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4assetstagsbyassetidget.md): Lists tags for the matching asset. ### List assets in a label - [GET /labels/{label_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4labelsassetsbylabelidget.md): Lists assets in a label. ### List assets in a Brandfolder - [GET /brandfolders/{brandfolder_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/brandfolders/opidapiv4brandfoldersassetsbybrandfolderidget.md): Lists assets in a Brandfolder. ### Create assets in a Brandfolder - [POST /brandfolders/{brandfolder_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/brandfolders/opidapiv4collectionsassetsbybrandfolderidpost.md): Creates assets in the matching Brandfolder. Any files you wish to use as an Attachment in Brandfolder must be hosted at a publicly available URL (until they have been successfully imported). If you need to upload file contents directly to a server, you can use do a binary file upload to our temporary storage bucket and then use that URL when creating Assets/Attachments. > NOTE: To create an asset from a binary upload, copy the object_url value from the [Get an upload URL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget) response into your request body's attachments.url property. ### List assets in a collection - [GET /collections/{collection_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4collectionsassetsbycollectionidget.md): Lists assets in a collection. ### Create assets in a collection - [POST /collections/{collection_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4collectionsassetsbycollectionidpost.md): Creates assets in the matching collection. Any files you wish to use as an Attachment in Brandfolder must be hosted at a publicly available URL (until they have been successfully imported). If you need to upload file contents directly to a server, you can use do a binary file upload to our temporary storage bucket and then use that URL when creating Assets/Attachments. ### List assets in a label - [GET /labels/{label_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/labels/opidapiv4labelsassetsbylabelidget.md): Lists assets in a label. ### List assets in a section - [GET /sections/{section_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/sections/opidapiv4sectionsassetsbysectionidget.md): Lists assets in the matching section. ### List tags for an asset - [GET /assets/{asset_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/tags/opidapiv4assetstagsbyassetidget.md): Lists tags for the matching asset. ## 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. ### List assets in a collection - [GET /collections/{collection_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbycollectionidget.md): Lists assets in a collection. ### Create assets in a collection - [POST /collections/{collection_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbycollectionidpost.md): Creates assets in the matching collection. Any files you wish to use as an Attachment in Brandfolder must be hosted at a publicly available URL (until they have been successfully imported). If you need to upload file contents directly to a server, you can use do a binary file upload to our temporary storage bucket and then use that URL when creating Assets/Attachments. ### List collections in a Brandfolder - [GET /brandfolders/{brandfolder_id}/collections](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4brandfolderscollectionsbybrandfolderidget.md): 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 ### Create a collection - [POST /brandfolders/{brandfolder_id}/collections](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4brandfolderscollectionsbybrandfolderidpost.md): Creates a collection in the matching Brandfolder. ### List collections - [GET /collections](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4collectionsget.md): List the collections accessible to the user. Unauthorized requests return an empty list. 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} ### Fetch a collection - [GET /collections/{collection_id}](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4collectionsbyidget.md): Returns the matching collection. ### Update a collection - [PUT /collections/{collection_id}](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4collectionsbyidput.md): Updates the matching collection. ### Delete a collection - [DELETE /collections/{collection_id}](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4collectionsbyiddelete.md): Removes the matching collection. ### List assets in a collection - [GET /collections/{collection_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4collectionsassetsbycollectionidget.md): Lists assets in a collection. ### Create assets in a collection - [POST /collections/{collection_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4collectionsassetsbycollectionidpost.md): Creates assets in the matching collection. Any files you wish to use as an Attachment in Brandfolder must be hosted at a publicly available URL (until they have been successfully imported). If you need to upload file contents directly to a server, you can use do a binary file upload to our temporary storage bucket and then use that URL when creating Assets/Attachments. ### List tags in a collection - [GET /collections/{collection_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4collectionstagsbycollectionidget.md): Lists tags in the matching collection. ### List tags in a collection - [GET /collections/{collection_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/tags/opidapiv4collectionstagsbycollectionidget.md): Lists tags in the matching collection. ## 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.). ### List assets in a section - [GET /sections/{section_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4sectionsassetsbysectionidget.md): Lists assets in the matching section. ### List sections - [GET /brandfolders/{brandfolder_id}/sections](https://developers.smartsheet.com/api/brandfolder/openapi/sections/opidapiv4sectionsget.md): Returns the Brandfolder's sections. ### Create a section - [POST /brandfolders/{brandfolder_id}/sections](https://developers.smartsheet.com/api/brandfolder/openapi/sections/opidapiv4brandfolderssectionsbybrandfolderidpost.md): Creates a section in the matching Brandfolder. ### Fetch a section. - [GET /sections/{section_id}](https://developers.smartsheet.com/api/brandfolder/openapi/sections/opidapiv4sectionsbyidget.md): Fetches the matching section. ### List assets in a section - [GET /sections/{section_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/sections/opidapiv4sectionsassetsbysectionidget.md): Lists assets in the matching section. ## Brandfolders Brandfolders are nested directly underneath an Organization in the overall heirarchy. They can have many Collections, Sections, and Assets. ### List assets in a Brandfolder - [GET /brandfolders/{brandfolder_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4brandfoldersassetsbybrandfolderidget.md): Lists assets in a Brandfolder. ### Create assets in a Brandfolder - [POST /brandfolders/{brandfolder_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost.md): Creates assets in the matching Brandfolder. Any files you wish to use as an Attachment in Brandfolder must be hosted at a publicly available URL (until they have been successfully imported). If you need to upload file contents directly to a server, you can use do a binary file upload to our temporary storage bucket and then use that URL when creating Assets/Attachments. > NOTE: To create an asset from a binary upload, copy the object_url value from the [Get an upload URL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget) response into your request body's attachments.url property. ### List Brandfolders - [GET /brandfolders](https://developers.smartsheet.com/api/brandfolder/openapi/brandfolders/list-brandfolders.md): 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} ### Fetch a Brandfolder - [GET /brandfolders/{brandfolder_id}](https://developers.smartsheet.com/api/brandfolder/openapi/brandfolders/opidapiv4brandfoldersbyidget.md): You can use the returned slug attribute to form a link to the desired Brandfolder like so: https://brandfolder.com/{slug} ### Update a Brandfolder - [PUT /brandfolders/{brandfolder_id}](https://developers.smartsheet.com/api/brandfolder/openapi/brandfolders/opidapiv4brandfoldersbyidput.md): Updates the matching Brandfolder. ### Create a Brandfolder - [POST /organizations/{organization_id}/brandfolders](https://developers.smartsheet.com/api/brandfolder/openapi/brandfolders/opidapiv4oganizationsbrandfoldersbyorganizationidpost.md): Creates a Brandfolder in the specified organization. ### List assets in a Brandfolder - [GET /brandfolders/{brandfolder_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/brandfolders/opidapiv4brandfoldersassetsbybrandfolderidget.md): Lists assets in a Brandfolder. ### Create assets in a Brandfolder - [POST /brandfolders/{brandfolder_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/brandfolders/opidapiv4collectionsassetsbybrandfolderidpost.md): Creates assets in the matching Brandfolder. Any files you wish to use as an Attachment in Brandfolder must be hosted at a publicly available URL (until they have been successfully imported). If you need to upload file contents directly to a server, you can use do a binary file upload to our temporary storage bucket and then use that URL when creating Assets/Attachments. > NOTE: To create an asset from a binary upload, copy the object_url value from the [Get an upload URL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget) response into your request body's attachments.url property. ### List tags in a Brandfolder - [GET /brandfolders/{brandfolder_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/brandfolders/opidapiv4brandfolderstagsbybrandfolderidget.md): Lists tags in the matching Brandfolder. ### List tags in a Brandfolder - [GET /brandfolders/{brandfolder_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/tags/opidapiv4brandfolderstagsbybrandfolderidget.md): Lists tags in the matching Brandfolder. ## 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. ### List tags for an asset - [GET /assets/{asset_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4assetstagsbyassetidget.md): Lists tags for the matching asset. ### List tags in a Brandfolder - [GET /brandfolders/{brandfolder_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/brandfolders/opidapiv4brandfolderstagsbybrandfolderidget.md): Lists tags in the matching Brandfolder. ### List tags in a collection - [GET /collections/{collection_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/collections/opidapiv4collectionstagsbycollectionidget.md): Lists tags in the matching collection. ### List tags in a collection - [GET /collections/{collection_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/tags/opidapiv4collectionstagsbycollectionidget.md): Lists tags in the matching collection. ### List tags for an asset - [GET /assets/{asset_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/tags/opidapiv4assetstagsbyassetidget.md): Lists tags for the matching asset. ### Create tags for an asset - [POST /assets/{asset_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/tags/opidapiv4assetstagsbyassetidpost.md): Creates tags for the matching asset. > Note: You can add multiple tags to the attributes array in the request body. ### List tags in a Brandfolder - [GET /brandfolders/{brandfolder_id}/tags](https://developers.smartsheet.com/api/brandfolder/openapi/tags/opidapiv4brandfolderstagsbybrandfolderidget.md): Lists tags in the matching Brandfolder. ### Update a tag - [PUT /tags/{tag_id}](https://developers.smartsheet.com/api/brandfolder/openapi/tags/opidapiv4tagsbyidput.md): Updates the matching tag. ### Delete tags - [DELETE /async/tags/assets/{asset_key}](https://developers.smartsheet.com/api/brandfolder/openapi/tags/opidapiv4asynctagsassetsbyassetkeydelete.md): Removes the matching tag(s) of the matching asset. Example Request Body: { "tags": ["A", "B"], "locale": "en" } > Important: This endpoint is asynchronous ## 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. ### List assets in a label - [GET /labels/{label_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/assets/opidapiv4labelsassetsbylabelidget.md): Lists assets in a label. ### List labels - [GET /brandfolders/{brandfolder_id}/labels](https://developers.smartsheet.com/api/brandfolder/openapi/labels/opidapiv4organizationslabelsbybrandfolderidget.md): Lists the labels in the matching Brandfolder. ### Create a label - [POST /brandfolders/{brandfolder_id}/labels](https://developers.smartsheet.com/api/brandfolder/openapi/labels/opidapiv4collectionslabelsbybrandfolderidpost.md): Creates a label in the matching Brandfolder. ### Fetch a label - [GET /labels/{label_id}](https://developers.smartsheet.com/api/brandfolder/openapi/labels/opidapiv4labelsbyidget.md): Fetches the label. ### Update a label - [PUT /labels/{label_id}](https://developers.smartsheet.com/api/brandfolder/openapi/labels/opidapiv4updatelabelput.md): Updates the name of the matching label. ### Delete a label - [DELETE /labels/{label_id}](https://developers.smartsheet.com/api/brandfolder/openapi/labels/opidapiv4labelsbyiddelete.md): Deletes the matching label. ### List assets in a label - [GET /labels/{label_id}/assets](https://developers.smartsheet.com/api/brandfolder/openapi/labels/opidapiv4labelsassetsbylabelidget.md): Lists assets in a label. ### Move the label - [PUT /labels/{label_id}/move](https://developers.smartsheet.com/api/brandfolder/openapi/labels/opidapiv4movelabelput.md): Assigns the label a new parent label. ## 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` ### Fetch an attachment - [GET /attachments/{attachment_id}](https://developers.smartsheet.com/api/brandfolder/openapi/attachments/opidapiv4attachmentsbyidget.md): Gets the matching attachment. ### Update an attachment - [PUT /attachments/{attachment_id}](https://developers.smartsheet.com/api/brandfolder/openapi/attachments/opidapiv4attachmentsbyidput.md): Updates a matching attachment. ### Delete an attachment - [DELETE /attachments/{attachment_id}](https://developers.smartsheet.com/api/brandfolder/openapi/attachments/opidapiv4attachmentsbyiddelete.md): Removes the matching attachment. ## 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](/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. ![Upload Request Flow](../images/bf-upload-request-interactions.png) ### Get an upload URL - [GET /upload_requests](https://developers.smartsheet.com/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget.md): Gets an upload URL. > NOTE: After uploading a file, you can add it as Brandfolder asset by copying the object_url value from the response into your request body's attachments.url property. See [Create assets in a Brandfolder](/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost) for details. ### Upload a file - [PUT /upload_url](https://developers.smartsheet.com/api/brandfolder/openapi/binary_upload/opidstorageservicebfuploadrequestbucketput.md): 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. > NOTE: Non-Resumable Uploads use the PUT method on initial creation. > NOTE: After uploading the file, you can add it as Brandfolder asset by copying the object_url value from the [Get an upload URL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget) response into your request body's attachments.url property. See [Create assets in a Brandfolder](/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost) for details. ### Resumable upload - [POST /resumable_upload_url](https://developers.smartsheet.com/api/brandfolder/openapi/binary_upload/opidstorageservicebfuploadrequestpost.md): 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). > NOTE: Resumable Uploads use the POST method on initialization and the PUT method after to resume upload. > NOTE: After uploading a file, you can add it as Brandfolder asset by copying the object_url value from the [Get an upload URL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget) response into your request body's attachments.url property. See [Create assets in a Brandfolder](/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost) for details. ### Resume upload - [PUT /resumable_upload_url](https://developers.smartsheet.com/api/brandfolder/openapi/binary_upload/opidstorageservicebfuploadrequestput.md): Resumes uploading a file to the same location. > NOTE: After uploading the file, you can add it as Brandfolder asset by copying the object_url value from the [Get an upload URL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget) response into your request body's attachments.url property. See [Create assets in a Brandfolder](/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost) for details. ## 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. ### List custom field keys - [GET /brandfolders/{brandfolder_id}/custom_field_keys](https://developers.smartsheet.com/api/brandfolder/openapi/custom_fields/opidapiv4brandfolderscustomfieldkeysbybrandfolderidget.md): Lists custom field keys for the matching Brandfolder. ### Create custom field keys - [POST /brandfolders/{brandfolder_id}/custom_field_keys](https://developers.smartsheet.com/api/brandfolder/openapi/custom_fields/opidapiv4brandfolderscustomfieldkeysbybrandfolderidpost.md): 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. ### List custom fields - [GET /assets/{asset_id}/custom_field_values](https://developers.smartsheet.com/api/brandfolder/openapi/custom_fields/opidapiv4assetscustomfieldvaluesbyassetidget.md): Lists custom fields for the matching asset. ### Create custom field values for an asset - [POST /custom_field_keys/{custom_field_key_id}/custom_field_values](https://developers.smartsheet.com/api/brandfolder/openapi/custom_fields/opidapiv4customfieldkeyscustomfieldvaluesbycustomfieldkeyidpost.md): 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](/api/brandfolder/openapi/custom_fields/opidapiv4brandfolderscustomfieldkeysbybrandfolderidget) 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. ### Update a custom field key - [PUT /custom_field_keys/{custom_field_key_id}](https://developers.smartsheet.com/api/brandfolder/openapi/custom_fields/opidapiv4customfieldkeysbyidput.md): 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. ### Delete a custom field key - [DELETE /custom_field_keys/{custom_field_key_id}](https://developers.smartsheet.com/api/brandfolder/openapi/custom_fields/opidapiv4customfieldkeysbyiddelete.md): Deletes the matching custom field key. > Warning: Be very careful when using this endpoint as it also deletes all associated values for that key. ### Update a custom field - [PUT /custom_field_values/{custom_field_value_id}](https://developers.smartsheet.com/api/brandfolder/openapi/custom_fields/opidapiv4customfieldvaluesbyidput.md): Update the matching custom field. ### Delete a custom field - [DELETE /custom_field_values/{custom_field_value_id}](https://developers.smartsheet.com/api/brandfolder/openapi/custom_fields/opidapiv4customfieldvaluesbyiddelete.md): Deletes the matching custom field. ## 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. ### List invitations to a Brandfolder - [GET /brandfolders/{brandfolder_id}/invitations](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4brandfoldersinvitationsbybrandfolderidget.md): Lists invitations to the matching Brandfolder. ### Create an invitation to a Brandfolder - [POST /brandfolders/{brandfolder_id}/invitations](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4brandfoldersinvitationsbybrandfolderidpost.md): Creates an invitation to the matching Brandfolder. ### List invitations to an organization - [GET /organizations/{organization_id}/invitations](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4organizationsinvitationsbyorganizationidget.md): Lists invitations to the matching organization. ### Create an invitation to an organization - [POST /organizations/{organization_id}/invitations](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4organizationsinvitationsbyorganizationidpost.md): Creates an invitation to the matching organization. ### List invitations to a collection - [GET /collections/{collection_id}/invitations](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4collectionsinvitationsbycollectionidget.md): Lists invitations to the matching collection. ### Create an invitation to a collection - [POST /collections/{collection_id}/invitations](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4collectionsinvitationsbycollectionidpost.md): Creates an invitation to the matching collection. ### List invitations to a portal - [GET /portals/{portal_id}/invitations](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4portalsinvitationsbyportalidget.md): Lists invitations to the matching portal. > Important: You can get the portal ID in the response from Fetch an organization. ### Create an invitation to a portal - [POST /portals/{portal_id}/invitations](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4portalsinvitationsbyportalidpost.md): Creates an invitation to the matching portal. ### List invitations to a Brandguide - [GET /brandguides/{brandguide_id}/invitations](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4brandguidesinvitationsbybrandguideidget.md): Lists invitations to the matching Brandguide. > Important: You can get the Brandguide ID in the response from Fetch an organization. ### Create an invitation to a Brandguide - [POST /brandguides/{brandguide_id}/invitations](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4brandguidesinvitationsbybrandguideidpost.md): Creates an invitation to the matching Brandguide. ### Fetch an invitation - [GET /invitations/{invitation_id}](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4invitationsbyidget.md): Gets a matching invitation. ### Delete an invitation - [DELETE /invitations/{invitation_id}](https://developers.smartsheet.com/api/brandfolder/openapi/invitations/opidapiv4invitationsbyiddelete.md): Deletes the matching invitation. ## Organizations An Organization is the top level resource of all objects in Brandfolder. It can have many Brandfolders nested beneath it. ### List organizations - [GET /organizations](https://developers.smartsheet.com/api/brandfolder/openapi/organizations/opidapiv4organizationsget.md): Lists all Organizations for a User. Unauthorized requests will return an empty list. You can use the returned slug attribute to form a link to the desired Organization like so: https://brandfolder.com/organizations/{slug} ### Get an organization - [GET /organizations/{organization_id}](https://developers.smartsheet.com/api/brandfolder/openapi/organizations/opidapiv4organizationsbyidget.md): You can use the returned slug attribute to form a link to the desired Organization like so: https://brandfolder.com/organizations/{slug} ## 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. ### List user permissions for an organization - [GET /organizations/{organization_id}/user_permissions](https://developers.smartsheet.com/api/brandfolder/openapi/user_permissions/opidapiv4organizationsuserpermissionsbyorganizationidget.md): Lists user permissions for the matching organization. ### List user permissions for a Brandfolder - [GET /brandfolders/{brandfolder_id}/user_permissions](https://developers.smartsheet.com/api/brandfolder/openapi/user_permissions/opidapiv4brandfoldersuserpermissionsbybrandfolderidget.md): Lists user permissions for the matching Brandfolder. ### List user permissions for a collection - [GET /collections/{collection_id}/user_permissions](https://developers.smartsheet.com/api/brandfolder/openapi/user_permissions/opidapiv4collectionsuserpermissionsbycollectionidget.md): Lists user permissions for the matching collection. ### Fetch a user permission - [GET /user_permissions/{user_permission_id}](https://developers.smartsheet.com/api/brandfolder/openapi/user_permissions/opidapiv4userpermissionsbyidget.md): Returns the matching user permission. ### Delete a user permission - [DELETE /user_permissions/{user_permission_id}](https://developers.smartsheet.com/api/brandfolder/openapi/user_permissions/opidapiv4userpermissionsbyiddelete.md): Deletes the matching user permission, revoking the user's access to that object. ## 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. - 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. There are two required headers in each request: `Content-Type: application/json`
`Authorization: Bearer ` 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: ```json { "data": { "attributes": { "key": "", "event_time": "", "event_type": "", "brandfolder_key": "", "organization_key": "" }, "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. ### Generate a test webhook - [POST /webhooks/send](https://developers.smartsheet.com/api/brandfolder/openapi/webhooks/opidapiv4webhookssendpost.md): Generates a test Webhook. > Important: This operation uses server https://brandfolder.com/api/v1 (notice the version is v1). > Important: Ensure that your code is able to receive a Brandfolder Webhook using this endpoint before creating a production Webhook subscription. If you receive a 202 response at this endpoint, then a fake Webhook notification will POST to your callback_url. If you don't receive anything at your callback_url within a few minutes, it is likely that callback_url is invalid. Please ensure the URL begins with https:// and that it is a public domain (not localhost, behind a firewall, or any other domain requiring authentication) which can receive HTTP POST requests and respond with a 2xx HTTP status code. ### List active webhooks - [GET /webhooks](https://developers.smartsheet.com/api/brandfolder/openapi/webhooks/opidapiv4webhooksget.md): List all active webhooks. > Important: This operation uses server https://brandfolder.com/api/v1 (notice the version is v1). ### Create a webhook subscription - [POST /webhooks](https://developers.smartsheet.com/api/brandfolder/openapi/webhooks/opidapiv4webhookspost.md): Subscribes to get Webhook notifications for the specified asset event type within the specified Brandfolder. > Important: This operation uses server https://brandfolder.com/api/v1 (notice the version is v1). ### Fetch an active webhook - [GET /webhooks/{webhook_id}](https://developers.smartsheet.com/api/brandfolder/openapi/webhooks/opidapiv4webhooksbyidget.md): Gets an active matching webhook. > Important: This operation uses server https://brandfolder.com/api/v1 (notice the version is v1). ### Delete a webhook - [DELETE /webhooks/{webhook_id}](https://developers.smartsheet.com/api/brandfolder/openapi/webhooks/opidapiv4webhooksbyiddelete.md): Deletes the matching webhook, so that data is no longer sent by it to its associated callback URL. > Important: This operation uses server https://brandfolder.com/api/v1 (notice the version is v1).