openapi: 3.2.0 info: title: Brandfolder OpenAPI Reference Custom Fields API version: v4 description: 'Welcome to the OpenAPI reference documentation for Brandfolder by Smartsheet! ' servers: - url: https://brandfolder.com/api/v4 security: - APIToken: [] tags: - 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. ' paths: /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: '#/components/schemas/CustomFieldKey' meta: $ref: '#/components/schemas/PaginationMetadataResponse' required: - data - meta default: description: Generic error payload content: application/json: schema: type: string /assets/{asset_id}/custom_field_values: parameters: - name: asset_id in: path schema: type: string required: true description: Unique identifier for the resource instance. example: oqgkkd-fr5iv4-443db - 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: opIdApiV4AssetsCustomFieldValuesByAssetIdGet summary: List custom fields description: 'Lists custom fields for the matching asset. ' parameters: - in: query name: include schema: type: string description: '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. ' tags: - custom_fields responses: '200': description: 'The custom fields for the asset. ' content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/CustomFieldValue' meta: $ref: '#/components/schemas/PaginationMetadataResponse' required: - data - meta default: description: Generic error payload content: application/json: schema: type: string /custom_field_keys/{custom_field_key_id}/custom_field_values: parameters: - name: custom_field_key_id in: path schema: type: string required: true description: Unique identifier for the resource instance. example: oqgkkd-fr5iv4-443db - 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' post: operationId: opIdApiV4CustomFieldKeysCustomFieldValuesByCustomFieldKeyIdPost summary: Create custom field values for an asset description: '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. ' tags: - custom_fields requestBody: content: application/json: schema: type: object properties: data: type: array description: A list of custom field associations. items: type: object properties: attributes: type: object properties: value: type: string description: Custom field key value. example: red required: - value relationships: type: object description: Specifies the object receiving the custom field. properties: asset: type: object properties: data: type: object properties: type: type: string description: The type of target object. enum: - assets id: type: string description: The ID of the asset. example: k5nj2bf5mc36j3ssm63359h required: - type - id required: - data required: - asset required: - attributes - relationships required: - data responses: '200': description: 'The new custom fields. ' content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string description: Unique identifier for the resource instance. example: r79p3j4gbcgtv33gbsqrxb type: type: string description: The type of the resource. enum: - custom_field_values attributes: type: object properties: key: type: string description: A key name. example: team value: type: string description: The value for the key. example: product required: - id - type - attributes required: - data default: description: Generic error payload content: application/json: schema: type: string /custom_field_keys/{custom_field_key_id}: parameters: - name: custom_field_key_id in: path schema: type: string required: true description: Unique identifier for the resource instance. example: plqlkk-22rw6g-3dqgx0 - in: header name: Content-Type required: true schema: type: string enum: - application/json example: application/json - $ref: '#/components/parameters/Authorization' put: operationId: opIdApiV4CustomFieldKeysByIdPut summary: Update a custom field key description: '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. ' tags: - custom_fields parameters: - in: header name: Accept required: true schema: type: string enum: - application/json example: application/json requestBody: content: application/json: schema: type: object properties: data: type: object properties: attributes: 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: - orange - gray - green required: - attributes required: - data responses: '200': description: 'The updated custom field key. ' content: application/json: schema: type: object properties: data: type: object properties: id: type: string description: Unique identifier for the resource instance. example: plqlkk-22rw6g-3dqgx0 type: type: string description: The type of the resource. enum: - custom_field_keys attributes: 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: - orange - gray - green 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: - id - type - attributes required: - data default: description: Generic error payload content: application/json: schema: type: string delete: operationId: opIdApiV4CustomFieldKeysByIdDelete summary: Delete a custom field key description: 'Deletes the matching custom field key. > **Warning:** Be very careful when using this endpoint as it also deletes all associated values for that key. ' tags: - custom_fields parameters: - in: header name: Content-Type required: true schema: type: string enum: - application/json example: application/json responses: '200': description: 'Successful response (always an empty object) ' content: application/json: schema: type: object properties: {} default: description: Generic error payload content: application/json: schema: type: string /custom_field_values/{custom_field_value_id}: parameters: - name: custom_field_value_id in: path schema: type: string required: true description: Unique identifier for the resource instance. example: 123456-22mpg8-dfmfi7 - in: header name: Content-Type required: true schema: type: string enum: - application/json example: application/json - $ref: '#/components/parameters/Authorization' put: operationId: opIdApiV4CustomFieldValuesByIdPut summary: Update a custom field description: 'Update the matching custom field. ' tags: - custom_fields parameters: - in: header name: Accept required: true schema: type: string enum: - application/json example: application/json requestBody: content: application/json: schema: type: object properties: data: type: object properties: attributes: type: object properties: value: type: string example: Fall required: - attributes required: - data responses: '200': description: 'The updated custom field. ' content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/CustomFieldValue' required: - data default: description: Generic error payload content: application/json: schema: type: string delete: operationId: opIdApiV4CustomFieldValuesByIdDelete summary: Delete a custom field description: 'Deletes the matching custom field. ' tags: - custom_fields parameters: - in: header name: Content-Type required: true schema: type: string enum: - application/json example: application/json responses: '200': description: 'Successful response (always an empty object) ' content: application/json: schema: type: object properties: {} default: description: Generic error payload content: application/json: schema: type: string components: schemas: PaginationMetadataResponse: title: Pagination metadata description: Page context information. type: object properties: current_page: type: integer format: int32 example: 1 minimum: 1 default: 1 next_page: type: - object - 'null' example: null default: null prev_page: type: - object - 'null' example: null default: null total_pages: example: 1 minimum: 1 default: 1 total_count: example: 1 minimum: 0 default: 0 required: - current_page - next_page - prev_page - total_pages - total_count CustomFieldKeyAttributes: title: Custom field key attributes 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 CustomFieldValue: title: Custom field value type: object properties: id: type: string description: Unique identifier for the resource instance. example: r79p3j4gbcgtv33gbsqrxb type: type: string description: The type of the resource. enum: - custom_field_values attributes: $ref: '#/components/schemas/CustomFieldValueAttributes' required: - id - type - attributes CustomFieldValueAttributes: title: Custom field value attributes type: object properties: key: type: string description: A key name. example: Campaign value: type: string description: The value for the key. example: Fall CustomFieldKey: title: Custom field key type: object properties: id: type: string description: Unique identifier for the resource instance. example: plqlkk-22rw6g-3dqgx0 type: type: string description: The type of the resource. enum: - custom_field_keys attributes: $ref: '#/components/schemas/CustomFieldKeyAttributes' required: - id - type - attributes parameters: Authorization: in: header name: Authorization required: true schema: type: string description: Bearer token for authentication securitySchemes: APIToken: scheme: bearer type: http description: API Token.