openapi: 3.2.0
info:
  title: Brandfolder OpenAPI Reference Organizations 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: organizations
  x-displayName: Organizations
  description: 'An Organization is the top level resource of all objects in Brandfolder. It can have many Brandfolders nested beneath it.

    '
paths:
  /organizations:
    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: opIdApiV4OrganizationsGet
      summary: List organizations
      description: 'Lists all Organizations for a User. Unauthorized requests will return an empty list.


        You can use the returned `slug` attribute to form a link to the desired Organization like so:


        ````

        https://brandfolder.com/organizations/{slug}

        ````

        '
      tags:
      - organizations
      parameters:
      - in: query
        name: fields
        description: 'Set it to `asset_count` to return each organization''s asset count as part of each organization''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 record names to return those records related to the organizations you're fetching. Related records are returned in an `included` array in the response.\n\nAllowed values: \n\n- brandfolders\n- brandguides\n- collections\n- portals\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: brandfolders
      responses:
        '200':
          description: 'All the user''s organizations.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        default:
          description: Generic error payload.
          content:
            application/json:
              schema:
                type: string
  /organizations/{organization_id}:
    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'
    get:
      operationId: opIdApiV4OrganizationsByIdGet
      summary: Get an organization
      description: 'You can use the returned `slug` attribute to form a link to the desired Organization like so:


        ````

        https://brandfolder.com/organizations/{slug}

        ````

        '
      tags:
      - organizations
      parameters:
      - in: query
        name: fields
        description: "Set it to a comma-separated list (no spaces) of any of the following attributes of the organization to return as part of the organization's attributes in the response.\n\nAllowed values: \n\n- `asset_count` returns the organization's asset count.\n- `cname` returns the organization's Canonical Name (CNAME), or `null` if the organization doesn't have one.\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
          enum:
          - asset_count
          - cname
        example: asset_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 organization you're fetching. Related records are returned in an `included` array in the response.\n\nAllowed values: \n\n- assets\n- brandfolders\n- brandguides\n- collections\n\nWARNING: This parameter can slow response times.\n"
        schema:
          type: string
        example: collections
      responses:
        '200':
          description: 'The matching organization.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Organization'
                required:
                - data
        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
    Organization:
      title: Organization
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource instance.
          example: oqgkkd-fr5iv4-cocc75
        type:
          type: string
          description: The type of the resource.
          enum:
          - organizations
        attributes:
          $ref: '#/components/schemas/OrganizationAttributes'
      required:
      - id
      - type
      - attributes
    OrganizationAttributes:
      title: Organization attributes
      type: object
      properties:
        name:
          type: string
          description: The name of the brandfolder.
          example: Brandfolder's Organization
        tagline:
          type: string
          description: The tagline of the brandfolder.
          example: An example tagline for the Organization
        slug:
          type: string
          description: The URL-friendly slug of the brandfolder.
          example: brandfolder-organization
  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.