openapi: 3.2.0
info:
  title: Brandfolder OpenAPI Reference Brandfolders 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: brandfolders
  x-displayName: Brandfolders
  description: 'Brandfolders are nested directly underneath an Organization in the overall heirarchy. They can have many Collections, Sections, and Assets.

    '
paths:
  /brandfolders:
    parameters:
    - in: header
      name: Content-Type
      required: true
      schema:
        type: string
        enum:
        - application/json
      example: application/json
    - in: header
      name: Accept
      required: true
      schema:
        type: string
        enum:
        - application/json
      example: application/json
    - $ref: '#/components/parameters/Authorization'
    get:
      operationId: list-brandfolders
      summary: List Brandfolders
      description: 'Lists all Brandfolders for a User. Unauthorized requests will return an

        empty list.


        You can use the returned `slug` attribute to form a link to the desired

        Brandfolder like so:


        ````

        https://brandfolder.com/{slug}

        ````

        '
      tags:
      - brandfolders
      parameters:
      - in: query
        name: fields
        description: "Set it to a comma-separated list (no spaces) of any of the following attributes of the Brandfolders\nto return as part of the Brandfolders' attributes in the response.\n\nAllowed values: \n\n- asset_count\n- attachment_count\n- storage\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: asset_count,attachment_count,storage
      - in: query
        name: include
        description: "Set it to a comma-separated list (no spaces) of any of the following record names to return those records related to the Brandfolders you're fetching. Related records are returned in an `included` array in the response.\n\nAllowed values: \n\n- organization\n- collections\n- assets\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: organizations
      - in: query
        name: search
        description: 'Set it to any URL-encoded query to fetch only Brandfolders that match your criteria.


          WARNING: This parameter can slow response times.

          '
        schema:
          type: string
        example: extension:png
      responses:
        '200':
          description: 'References to all the user''s Brandfolders.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Brandfolder'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /brandfolders/{brandfolder_id}:
    parameters:
    - name: brandfolder_id
      in: path
      schema:
        type: string
      required: true
      description: Unique identifier for the resource instance.
      example: oqgiju-21olts-ce9egi
    - in: header
      name: Content-Type
      required: true
      schema:
        type: string
        enum:
        - application/json
      example: application/json
    - in: header
      name: Accept
      required: true
      schema:
        type: string
        enum:
        - application/json
      example: application/json
    - $ref: '#/components/parameters/Authorization'
    get:
      operationId: opIdApiV4BrandfoldersByIdGet
      tags:
      - brandfolders
      summary: Fetch a Brandfolder
      description: 'You can use the returned `slug` attribute to form a link to the desired

        Brandfolder like so:


        ````

        https://brandfolder.com/{slug}

        ````

        '
      parameters:
      - in: query
        name: fields
        description: "Set it to a comma-separated list (no spaces) of any of the following attributes of the Brandfolder\nto return as part of the Brandfolder's attributes in the response.\n\nAllowed values: \n\n- asset_count\n- attachment_count\n- section_count\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: asset_count,attachment_count,section_count
      - in: query
        name: include
        description: "Set it to a comma-separated list (no spaces) of any of the following record names to return those records related to the Brandfolder you're fetching. Related records are returned in an `included` array in the response.\n\nAllowed values: \n\n- organization\n- collections\n- search_filters\n- sections\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: organizations
      responses:
        '200':
          description: 'A reference to the Brandfolder.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Brandfolder'
                required:
                - data
    put:
      operationId: opIdApiV4BrandfoldersByIdPut
      summary: Update a Brandfolder
      description: Updates the matching Brandfolder.
      tags:
      - brandfolders
      parameters:
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
          - application/json
        example: application/json
      requestBody:
        description: 'Attribute updates for the Brandfolder.

          '
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      type: object
                      properties:
                        name:
                          type: string
                          description: A new name for the Brandfolder.
                          example: Updated Brandfolder
                        privacy:
                          type: string
                          description: A new privacy setting for the Brandfolder.
                          example: public
                        slug:
                          type: string
                          description: A new URL-friendly slug for the Brandfolder.
                          example: updated-brandfolder
                        tagline:
                          type: string
                          description: A new tagline for the brandfolder.
                          example: Updated Brandfolder tagline!
                  required:
                  - attributes
              required:
              - data
      responses:
        '200':
          description: 'The updated Brandfolder.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique identifier for the resource instance.
                        example: oqgkkd-fr5iv4-hh142d
                      type:
                        type: string
                        description: The type of the resource.
                        enum:
                        - brandfolders
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            description: The name of the Brandfolder.
                            example: Updated Brandfolder
                          privacy:
                            type: string
                            description: The privacy setting of the Brandfolder.
                            example: public
                          slug:
                            type: string
                            description: The URL-friendly slug of the Brandfolder.
                            example: updated-brandfolder
                          tagline:
                            type: string
                            description: The tagline for the brandfolder.
                            example: Updated Brandfolder tagline!
                        required:
                        - name
                        - privacy
                        - slug
                        - tagline
                    required:
                    - attributes
                required:
                - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /organizations/{organization_id}/brandfolders:
    parameters:
    - name: organization_id
      in: path
      schema:
        type: string
      required: true
      description: Unique identifier for the resource instance.
      example: oqgkkd-fr5iv4-cocc75
    - 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: opIdApiV4OganizationsBrandfoldersByOrganizationIdPost
      summary: Create a Brandfolder
      description: 'Creates a Brandfolder in the specified organization.

        '
      tags:
      - brandfolders
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
          default: application/json
          example: application/json
      requestBody:
        description: 'Attributes for the new Brandfolder.

          '
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The name of the brandfolder.
                          example: Brandfolder
                        privacy:
                          type: string
                          description: The privacy setting of the brandfolder.
                          example: private
                        slug:
                          type: string
                          description: The URL-friendly slug of the brandfolder.
                          example: brandfolder
                        tagline:
                          type: string
                          description: The tagline of the brandfolder.
                          example: You expected this - Brandfolder's Brandfolder!
                          default: ''
                      required:
                      - name
                  required:
                  - attributes
              required:
              - data
      responses:
        '200':
          description: 'The new Brandfolder.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Brandfolder'
                required:
                - data
        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:
      - brandfolders
      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:
      - brandfolders
      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
  /brandfolders/{brandfolder_id}/tags:
    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: opIdApiV4BrandfoldersTagsByBrandfolderIdGet
      summary: List tags in a Brandfolder
      description: 'Lists tags in the matching Brandfolder.

        '
      tags:
      - brandfolders
      responses:
        '200':
          description: 'Tags in the matching Brandfolder.

            '
          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
    BrandfolderAttributes:
      title: Brandfolder attributes
      type: object
      properties:
        name:
          type: string
          description: The name of the brandfolder.
          example: Brandfolder
        privacy:
          type: string
          description: The privacy setting of the brandfolder.
          example: private
        slug:
          type: string
          description: The URL-friendly slug of the brandfolder.
          example: brandfolder
        tagline:
          type: string
          description: The tagline of the brandfolder.
          example: You expected this - Brandfolder's Brandfolder!
          default: ''
      required:
      - name
      - privacy
      - slug
      - tagline
    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
    Brandfolder:
      title: Brandfolder
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource instance.
          example: oqgiju-21olts-ce9egi
        type:
          type: string
          description: The type of the resource.
          enum:
          - brandfolders
        attributes:
          $ref: '#/components/schemas/BrandfolderAttributes'
      required:
      - id
      - type
      - attributes
    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.