Brandfolder Collections API

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

    '
paths:
  /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
  /collections:
    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: opIdApiV4CollectionsGet
      summary: List collections
      description: "List the collections accessible to the user. \n\nUnauthorized requests return an empty list.\n\nYou can use the returned `slug` parameter (in conjunction with the slug of\nthe parent Brandfolder) to form a link to the desired Collection like so:\n\n```\nhttps://brandfolder.com/{brandfolder_slug}/{collection_slug}\n```\n"
      tags:
      - collections
      parameters:
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
          - application/json
        example: application/json
      security:
      - APIToken: []
      responses:
        '200':
          description: 'A list of collections accessible to the user.

            '
          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
  /collections/{collection_id}:
    parameters:
    - name: collection_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
    - $ref: '#/components/parameters/Authorization'
    get:
      operationId: opIdApiV4CollectionsByIdGet
      summary: Fetch a collection
      description: 'Returns the matching collection.

        '
      tags:
      - collections
      parameters:
      - in: query
        name: fields
        description: 'Set it to `asset_count` to return the collection''s asset count as part

          of the collection''s attributes in the response.



          WARNING: This parameter can slow response times.

          '
        schema:
          type: string
          enum:
          - asset_count
        example: asset_count
      - 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 collection you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values: \n\n- brandfolder\n- assets\n- search_filters\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: brandfolder
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
          - application/json
        example: application/json
      responses:
        '200':
          description: 'The matching collection.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Collection'
                required:
                - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: opIdApiV4CollectionsByIdPut
      summary: Update a collection
      description: Updates the matching collection.
      tags:
      - collections
      parameters:
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
          - application/json
        example: application/json
      requestBody:
        description: 'Attribute updates for the collection.

          '
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      type: object
                      properties:
                        name:
                          type: string
                          description: A new name.
                          example: New name
                        slug:
                          type: string
                          description: 'A new 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: new-name
                        tagline:
                          type: string
                          description: A new tag line.
                          example: New tag line
                  required:
                  - attibutes
              required:
              - data
      responses:
        '200':
          description: 'The updated collection.

            '
          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:
                        - collections
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            description: A new name.
                            example: New name
                          slug:
                            type: string
                            description: 'A new URL-friendly slug.

                              '
                            example: new-name
                          tagline:
                            type: string
                            description: A new tag line.
                            example: New tag line
                          public:
                            type: boolean
                            description: Set to `true` for hassle-free sharing, allowing search engines to index your brand assets. Otherwise, set to `false` to share only with the users you specify.
                            example: false
                          stealth:
                            type: boolean
                            description: Set to `true` to remove the collection from appearing in web searches.
                            example: false
                          is_workspace:
                            type: boolean
                            description: Set to `true` if the collection is a Brandfolder workspace.
                            example: false
                required:
                - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: opIdApiV4CollectionsByIdDelete
      summary: Delete a collection
      description: Removes the matching collection.
      tags:
      - collections
      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
  /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:
      - collections
      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:
      - collections
      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
  /collections/{collection_id}/tags:
    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: opIdApiV4CollectionsTagsByCollectionIdGet
      summary: List tags in a collection
      description: 'Lists tags in the matching collection.

        '
      tags:
      - collections
      responses:
        '200':
          description: 'Tags in the matching collection.

            '
          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
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
    Collection:
      title: Collection
      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:
          - collections
        attributes:
          $ref: '#/components/schemas/CollectionAttributes'
      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
    CollectionAttributes:
      title: Collection attributes
      type: object
      properties:
        name:
          type: string
          description: The name of the collection.
          example: My collection
        tagline:
          type: string
          description: The tagline of the collection.
          example: My collection tag line
        slug:
          type: string
          description: The URL-friendly slug of the collection.
          example: my-collection
        public:
          type: boolean
          description: Set to `true` for hassle-free sharing, allowing search engines to index your brand assets. Otherwise, set to `false` to share only with the users you specify.
          example: false
          default: false
        stealth:
          type: boolean
          description: Set to `true` to remove the collection from appearing in web searches.
          example: false
          default: false
        is_workspace:
          type: boolean
          description: Set to `true` if the collection is a Brandfolder workspace.
          example: false
          default: false
    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.