Brandfolder Assets API

openapi: 3.2.0
info:
  title: Brandfolder OpenAPI Reference Assets 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: 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.

    '
paths:
  /collections/{collection_id}/assets:
    parameters:
    - name: collection_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: opIdApiV4CollectionsAssetsByCollectionIdGet
      summary: List assets in a collection
      description: Lists assets in a collection.
      tags:
      - assets
      parameters:
      - in: query
        name: page
        description: 'Set this to a positive, non-zero integer representing the page number of

          the results you want.

          '
        schema:
          type: integer
          format: int32
          minimum: 1
      - in: query
        name: per
        description: 'Set this pagination parameter to the maximum number of results you want

          to receive back from your request. More records may exist (as denoted by

          the `meta.total_count` value).

          '
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 3000
          default: 100
      - in: query
        name: search
        description: 'Set it to any URL-encoded query to fetch only assets that match your

          criteria.


          WARNING: This parameter can slow response times.

          '
        schema:
          type: string
        example: extension:png
      - in: query
        name: fields
        description: "Set it to a comma-separated list (no spaces) of any of the following\nattributes of the asset to return as part of the asset's attributes in\nthe response.\n\nAllowed values: \n\n- `created_at`\n- `updated_at`\n- `cdn_url`\n- `availability`\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: cdn_url
      - in: query
        name: include
        description: "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the asset you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values: \n\n- `attachments`\n- `brandfolder`\n- `collections`\n- `custom_fields`\n- `section`\n- `tags`\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: tags
      responses:
        '200':
          description: 'The matching collection assets.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        '404':
          description: "This occurs for CDN URLs of assets that are pending approval or\nunpublished. \n"
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: opIdApiV4CollectionsAssetsByCollectionIdPost
      summary: Create assets in a collection
      description: '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.

        '
      tags:
      - assets
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      type: array
                      items:
                        $ref: '#/components/schemas/AssetAttributesRequest'
                  required:
                  - attributes
                section_key:
                  type: string
                  description: 'ID of the Section in which you want the newly created Asset(s)

                    to live.

                    '
                  example: oqgol8-dslwxs-58b2z3
              required:
              - data
              - section_key
      responses:
        '200':
          description: 'The new assets.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /sections/{section_id}/assets:
    parameters:
    - name: section_id
      in: path
      schema:
        type: string
      required: true
      description: Unique identifier for the resource instance.
      example: oqgol8-dslwxs-58b2z3
    - 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: opIdApiV4SectionsAssetsBySectionIdGet
      summary: List assets in a section
      description: Lists assets in the matching section.
      tags:
      - assets
      parameters:
      - in: query
        name: page
        description: 'Set this to a positive, non-zero integer representing the page number of

          the results you want.

          '
        schema:
          type: integer
          format: int32
          minimum: 1
      - in: query
        name: per
        description: 'Set this pagination parameter to the maximum number of results you want

          to receive back from your request. More records may exist (as denoted by

          the `meta.total_count` value).

          '
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 3000
          default: 100
      - in: query
        name: search
        description: 'Set it to any URL-encoded query to fetch only assets that match your

          criteria.


          WARNING: This parameter can slow response times.

          '
        schema:
          type: string
        example: extension:png
      - in: query
        name: fields
        description: "Set it to a comma-separated list (no spaces) of any of the following\nattributes of the asset to return as part of the asset's attributes in\nthe response.\n\nAllowed values: \n\n- `created_at`\n- `updated_at`\n- `cdn_url`\n- `availability`\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: cdn_url
      responses:
        '200':
          description: 'The matching section assets.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        '404':
          description: "This occurs for CDN URLs of assets that are pending approval or\nunpublished. \n"
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /brandfolders/{brandfolder_id}/assets:
    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: opIdApiV4BrandfoldersAssetsByBrandfolderIdGet
      summary: List assets in a Brandfolder
      description: Lists assets in a Brandfolder.
      tags:
      - assets
      parameters:
      - in: query
        name: page
        description: 'Set this to a positive, non-zero integer representing the page number of

          the results you want.

          '
        schema:
          type: integer
          format: int32
          minimum: 1
      - in: query
        name: per
        description: 'Set this pagination parameter to the maximum number of results you want

          to receive back from your request. More records may exist (as denoted by

          the `meta.total_count` value).

          '
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 3000
          default: 100
      - in: query
        name: search
        description: 'Set it to any URL-encoded query to fetch only assets that match your

          criteria.


          WARNING: This parameter can slow response times.

          '
        schema:
          type: string
        example: extension:png
      - in: query
        name: fields
        description: "Set it to a comma-separated list (no spaces) of any of the following\nattributes of the asset to return as part of the asset's attributes in\nthe response.\n\nAllowed values: \n\n- `created_at`\n- `updated_at`\n- `cdn_url`\n- `availability`\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: cdn_url
      - in: query
        name: include
        description: "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the asset you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values: \n\n- `attachments`\n- `brandfolder`\n- `collections`\n- `custom_fields`\n- `section`\n- `tags`\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: tags
      responses:
        '200':
          description: 'The matching Brandfolder assets.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        '404':
          description: "This occurs for CDN URLs of assets that are pending approval or\nunpublished. \n"
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    post:
      operationId: opIdApiV4CollectionsAssetsByBrandfolderIdPost
      summary: Create assets in a Brandfolder
      description: '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.

        '
      tags:
      - assets
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      type: array
                      items:
                        $ref: '#/components/schemas/AssetAttributesRequest'
                  required:
                  - attributes
                section_key:
                  type: string
                  description: 'ID of the Section in which you want the newly created Asset(s)

                    to live.

                    '
                  example: oqgol8-dslwxs-58b2z3
              required:
              - data
              - section_key
      responses:
        '200':
          description: 'The new assets.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /assets/{asset_id}:
    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
    - $ref: '#/components/parameters/Authorization'
    get:
      operationId: opIdApiV4AssetsByIdGet
      summary: Fetch an asset
      description: Fetches the matching asset.
      tags:
      - assets
      parameters:
      - in: query
        name: fields
        description: "Set it to a comma-separated list (no spaces) of any of the following\nattributes of the asset to return as part of the asset's attributes in\nthe response.\n\nAllowed values: \n\n- `created_at`\n- `updated_at`\n- `cdn_url`\n- `availability`\n- `availability_start`\n- `availability_end`\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: cdn_url
      - in: query
        name: include
        description: "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the asset you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values: \n\n- `attachments`\n- `brandfolder`\n- `collections`\n- `custom_fields`\n- `section`\n- `tags`\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: tags
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
          - application/json
        example: application/json
      responses:
        '200':
          description: 'The matching asset.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Asset'
                required:
                - data
        '403':
          description: "This occurs for CDN URLs of assets that are pending approval or\nunpublished. \n"
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: opIdApiV4AssetsByIdPut
      summary: Update an asset
      description: '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.

        '
      tags:
      - assets
      requestBody:
        description: 'Attribute updates for an asset.

          '
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      $ref: '#/components/schemas/AssetAttributesRequest'
                  required:
                  - attributes
              required:
              - data
      responses:
        '200':
          description: 'The updated asset.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Asset'
                required:
                - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: opIdApiV4AssetsByIdDelete
      summary: Delete an asset
      description: Removes the matching asset.
      tags:
      - assets
      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
  /assets/{asset_id}/tags:
    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: opIdApiV4AssetsTagsByAssetIdGet
      summary: List tags for an asset
      description: 'Lists tags for the matching asset.

        '
      tags:
      - assets
      parameters:
      - in: query
        name: include
        description: 'Set it to `asset` to return those asset records related to the tag

          you''re fetching. Related records are returned in an `included` array in

          the response.


          Allowed value:  `asset`


          WARNING: This parameter can slow response times.

          '
        schema:
          type: string
        example: asset
      responses:
        '200':
          description: 'Tags for the matching asset.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tag'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /labels/{label_id}/assets:
    parameters:
    - name: label_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: opIdApiV4LabelsAssetsByLabelIdGet
      summary: List assets in a label
      description: Lists assets in a label.
      tags:
      - assets
      parameters:
      - in: query
        name: page
        description: 'Set this to a positive, non-zero integer representing the page number of

          the results you want.

          '
        schema:
          type: integer
          format: int32
          minimum: 1
      - in: query
        name: per
        description: 'Set this pagination parameter to the maximum number of results you want

          to receive back from your request. More records may exist (as denoted by

          the `meta.total_count` value).

          '
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 3000
          default: 100
      - in: query
        name: search
        description: 'Set it to any URL-encoded query to fetch only assets that match your

          criteria.


          WARNING: This parameter can slow response times.

          '
        schema:
          type: string
        example: extension:png
      - in: query
        name: fields
        description: "Set it to a comma-separated list (no spaces) of any of the following\nattributes of the asset to return as part of the asset's attributes in\nthe response.\n\nAllowed values: \n\n- `created_at`\n- `updated_at`\n- `cdn_url`\n- `availability`\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: cdn_url
      - in: query
        name: include
        description: "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the asset you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values: \n\n- `attachments`\n- `brandfolder`\n- `collections`\n- `custom_fields`\n- `section`\n- `tags`\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: tags
      responses:
        '200':
          description: 'The matching label assets.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        '404':
          description: "This occurs for CDN URLs of assets that are pending approval or\nunpublished. \n"
        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
    Tag:
      title: Tag
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource instance.
          example: a3dlao-hd6so4-7d91d2
        type:
          type: string
          description: The type of the resource.
          enum:
          - tags
        attributes:
          $ref: '#/components/schemas/TagAttributes'
      required:
      - id
      - type
      - attributes
    Asset:
      title: Asset
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource instance.
          example: oqgkkd-fr5iv4-443db
        type:
          type: string
          description: The type of the resource.
          enum:
          - generic_files
        attributes:
          $ref: '#/components/schemas/AssetAttributes'
      required:
      - id
      - type
      - attributes
    AssetAttributes:
      title: Asset attributes
      type: object
      properties:
        name:
          type: string
          description: The name of the asset.
          example: Brandfolder Logo
        description:
          type: string
          description: The description of the asset.
          example: Brandfolder's logo in print ready format
        thumbnail_url:
          type: string
          description: The online location of the asset.
          example: https://example.com/example.jpg?Expires=1624742369
        approved:
          type: boolean
          description: If `true`, this asset is approved; otherwise, it's not.
          example: true
    TagAttributes:
      title: Tag attributes
      type: object
      properties:
        name:
          type: string
          description: '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 doesn''t affect other tags with the same value on other assets.

            '
          example: product
        auto_generated:
          type: boolean
          description: If `true`, this tag was generated automatically by our smart analysis of file attachments; otherwise, a user created it.
          example: true
        source:
          type:
          - string
          - 'null'
          description: The tag author.
          example: google_vision
          default: null
      required:
      - name
    AssetAttributesRequest:
      title: Asset attributes request body
      type: object
      properties:
        name:
          type: string
          description: The name of the asset.
          example: Brandfolder Logo
        description:
          type: string
          description: The description of the asset.
          example: Brandfolder's logo in print ready format
        thumbnail_url:
          type: string
          description: The online location of the asset.
          example: https://example.com/example.jpg?Expires=1624742369
        approved:
          type: boolean
          description: If `true`, this asset is approved; otherwise, it's not.
          example: true
        availability_start:
          type: string
          format: date-time
          description: 'This represents the publish/availability date in Brandfolder, the label `draft` will show.

            '
          example: '2024-02-23T18:22:49.771Z'
        availability_end:
          type: string
          format: date-time
          description: 'This represents the expiration date in brandfolder, the label `expired` will show.

            '
          example: '2025-02-23T18:22:49.771Z'
        attachments:
          description: 'An array of Attachment objects to add to the Asset (these do not overwrite exisiting Attachments).

            '
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                description: 'A fully-formed URL of the file to upload (required for each new Attachment).

                  '
                example: https://example.com/new-attachment.jpg
              filename:
                type: string
                description: A complete file name, with extension.
                example: new-attachment.jpg
            required:
            - url
      required:
      - name
  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.