openapi: 3.1.0
info:
  title: Brand Management API
  version: 0.1.0
  description: >
    Use the Brand Management REST API to create a [brand
    kit](https://doc.sitecore.com/stream/en/users/sitecore-stream/brand-kits.html),
    retrieve all brand kits or a specific one including sections and
    subsections, and create or update the content of individual subsections.

     This REST API lets you interect with:

     - The brand kit object. A [brand kit](https://doc.sitecore.com/stream/en/users/sitecore-stream/brand-kits.html) is a structured resource that enables organizations to manage their brand across various channels, teams, and content types. It defines the brand's identity through guidelines, tone, messaging rules, and other defining traits.

     After creating a brand kit using the Brand Management REST API, you can use the [Documents REST API](https://api-docs.sitecore.com/ai-skills/ai-document-management-rest-api) to upload brand documents and the [Pipeline REST API](https://api-docs.sitecore.com/ai-skills/ai-pipeline-rest-api) to initiate the brand ingestion process. 

    Note the following:

     - To use this REST API, you must authenticate your API requests.

     - All API requests are made in your production environment.

    For more information, see the [official Sitecore Stream
    documentation](https://doc.sitecore.com/stream/en/users/sitecore-stream/sitecore-stream.html).


    # Authorization

    The Brand Management REST API uses the OAuth 2.0 standard with [JSON web
    tokens](https://doc.sitecore.com/stream/en/users/sitecore-stream/generate-a-json-web-token--jwt-.html)
    to authorize REST API requests.

    ### Create Client ID and Client Secret
      1. In the Sitecore Cloud Portal, open Stream.
      2. Click **Admin** > **AI APIs keys** > **Create credential**.
      3. In the **​Create New Client​​** dialog, enter a name and description for the client. Then click **Create**. The ​Client ID and Client Secret​​ display.
      4. Copy the Client ID and Client Secret because you won't be able to view them again in Stream. You'll use them to request an access token.

    ### Request an access token

    Run the following cURL command to request an access token. Replace the
    placeholder values with your Client ID and Client Secret.

    ```curl
      curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'client_id={YOUR_API_KEY}' \
      --data-urlencode 'client_secret={YOUR_API_SECRET}' \
      --data-urlencode 'grant_type=client_credentials' \
      --data-urlencode 'audience=https://api.sitecorecloud.io'
    ```

    In the response, the `access_token` key contains the access token:

    ```json
      {
        "access_token": "{YOUR_ACCESS_TOKEN}",
        "scope": "ai.org.brd:w ai.org.brd:r ai.org.docs:w ai.org.docs:r ai.org:admin",
        "expires_in": 86400,
        "token_type": "Bearer"
      }
    ```

    Access tokens expire in 24 hours. If your requests unexpectedly return a
    response with status `401 Unauthorized`, request a new access token by
    repeating this `POST` request.


    We recommend that you cache the access token for 24 hours to avoid repeating
    this `POST` request while the access token is still valid.

    ### Include the access token in the request header

    You can now start making REST API requests. You must include the access
    token in the request header of every request. For example:

      ```curl
      curl -X GET '{YOUR_BASE_URL}/v2/...' \
      -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
      -H 'Accept: application/json'
      ```
  contact:
    name: Sitecore Corporation A/S
  license:
    name: Closed source
  x-metadata:
    product: AI skills
servers:
  - url: https://edge-platform.sitecorecloud.io/stream/ai-brands-api
    description: Production server
  - url: https://edge-platform.sitecorecloud.io/ai/ai-brands-api
    description: Production server
paths:
  /api/brands/v1/organizations/{organizationId}/brandkits:
    post:
      tags:
        - Brand kit
      summary: Create a brand kit
      description: >-
        Creates a new brand kit for an organization. The created brand kit
        includes predefined sections like *Brand Context*, *Global Goals*, *Tone
        of Voice*, and more, which are empty by default.
         
         In the response, the `id` key contains the created brand kit's unique identifier.
      operationId: >-
        create_brand_kit_api_brands_v1_organizations__organizationId__brandkits_post
      parameters:
        - name: organizationId
          in: path
          required: true
          description: |-
            The unique identifier of your organization.

             To get this value, in the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL, the `organizationId` comes after `organization=` . 
          schema:
            type: string
            example: org_ABCDef123456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBrandKitModelRequest'
      responses:
        '201':
          description: Brand kit created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBrandKitModelResponse'
        '400':
          description: Duplicate brand kit name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DuplicateHTTPError'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Brand kit operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
      security:
        - HTTPBearer: []
    get:
      tags:
        - Brand kit
      summary: List brand kits
      description: >+
        Retrieves a list of brand kits in an organization. The response includes
        basic information about each brand kit, such as its name, description,
        industry, and status. The response does not include the actual content
        of the brand kit sections or subsections.

      operationId: >-
        list_brand_kits_api_brands_v1_organizations__organizationId__brandkits_get
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            type: string
            description: |-
              The unique identifier of your organization.

               To get this value, in the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL, the `organizationId` comes after `organization=` . 
            example: org_ABCDef123456
        - name: pageNumber
          in: query
          required: false
          schema:
            type: integer
            default: 1
            description: The page number of the brand kits list to retrieve.
            example: 1
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            default: 50
            description: The number of brand kits to retrieve per page.
            example: 50
        - name: parentId
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
            description: >-
              The parent brand kit ID. Used when AI creates a new version of the
              brand kit during brand ingestion to indicate the original brand
              kit it's based on.
            example: a1234bcd-efg5-678h-910i-abcdefghijklmn
        - name: status
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
            description: >-
              The current status of the brand kit, such as `draft`, `inprocess`,
              `published`, or `failed`.
            example: draft
        - name: search
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
            description: A search term to filter brand kits by name or description.
            example: Powerful
        - name: referenceType
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
            description: The type of reference to filter brand kits by.
            example: document
        - name: referenceId
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
            description: >-
              The unique identifier of the brand kit reference to filter brand
              kits by.
            example: rdd1ea98d-92c1-41e3-8179-9417f255e673
        - name: includeDeleted
          in: query
          required: false
          schema:
            type:
              - boolean
              - 'null'
            description: Whether to include deleted brand kits in the response.
            default: false
            example: 'false'
      responses:
        '200':
          description: Brand kits retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBrandKitsModelResponse'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
  /api/brands/v1/organizations/{organizationId}/brandkits/{brandkitId}:
    get:
      tags:
        - Brand kit
      summary: Retrieve a brand kit
      description: >+
        Retrieves a specific brand kit by its ID. The response includes basic
        information about the brand kit, such as its name, description,
        industry, and status. The response does not include the actual content
        of the brand kit sections or subsections.

         If you don't know the brand kit ID, you can use the [List brand kits](#operation/list_brand_kits_api_brands_v1_organizations__organizationId__brandkits_get) endpoint to retrieve the list of brand kits in your organization.

      operationId: >-
        get_brand_kit_api_brands_v1_organizations__organizationId__brandkits__brandkitId__get
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            type: string
            description: |-
              The unique identifier of your organization.

               To get this value, in the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL, the `organizationId` comes after `organization=` . 
            example: org_ABCDef123456
        - name: brandkitId
          in: path
          required: true
          schema:
            type: string
            description: |-
              The unique identifier of your brand kit.

               To get this value, use the [List brand kits](#operation/list_brand_kits_api_brands_v1_organizations__organizationId__brandkits_get) endpoint  to return the `id` of each brand kit in your organization. This is the same `id` returned when you create a brand kit using the [Create a brand kit](#operation/create_brand_kit_api_brands_v1_organizations__organizationId__brandkits_post) endpoint.

               Alternatively, you can open your brand kit in Stream. In the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL,  `brandkitId` comes after `brandkits/`.
            example: a1234bcd-efg5-678h-910i-jklmnopqrstu
        - name: includeDeleted
          in: query
          required: false
          schema:
            type:
              - boolean
              - 'null'
            description: Whether to include deleted brand kits in the response.
            default: false
            example: 'false'
      responses:
        '200':
          description: Brand kit retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBrandKitModelResponse'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
  /api/brands/v1/organizations/{organizationId}/brandkits/{brandkitId}/sections:
    get:
      tags:
        - Brand kit
      summary: List brand kit sections
      description: >+
        Retrieves a list of sections in a brand kit. Each section contains
        information that define the brand's identity and guidelines, such as
        *Brand Context*, *Global Goals*, and *Tone of Voice*.

         To return actual content in the sections, the [Documents REST API](https://api-docs.sitecore.com/ai-skills/ai-document-management-rest-api) and [Pipeline REST API](https://api-docs.sitecore.com/ai-skills/ai-pipeline-rest-api) must have already been used to upload and process brand documents for the brand kit.

      operationId: >-
        list_brand_kit_sections_api_brands_v1_organizations__organizationId__brandkits__brandkitId__sections_get
      parameters:
        - name: organizationId
          description: |-
            The unique identifier of your organization.

             To get this value, in the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL, the `organizationId` comes after `organization=` . 
          in: path
          required: true
          schema:
            type: string
            example: org_ABCDef123456
        - name: brandkitId
          description: |-
            The unique identifier of your brand kit.

             To get this value, use the [List brand kits](#operation/list_brand_kits_api_brands_v1_organizations__organizationId__brandkits_get) endpoint  to return the `id` of each brand kit in your organization. This is the same `id` returned when you create a brand kit using the [Create a brand kit](#operation/create_brand_kit_api_brands_v1_organizations__organizationId__brandkits_post) endpoint.

             Alternatively, you can open your brand kit in Stream. In the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL,  `brandkitId` comes after `brandkits/`.
          in: path
          required: true
          schema:
            type: string
            example: a1234bcd-efg5-678h-910i-jklmnopqrstu
        - name: sectionIds
          description: >-
            An array of section IDs to filter the results. If not provided, all
            sections in the brand kit are returned.
          in: query
          required: false
          schema:
            example:
              - sectionId1
              - sectionId2
            type:
              - array
              - 'null'
            items:
              type: string
        - name: includeDeleted
          description: Whether to include deleted sections in the response.
          in: query
          required: false
          schema:
            default: false
            example: true
            type:
              - boolean
              - 'null'
      responses:
        '200':
          description: Brand kit sections retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ListBrandKitSectionsModelResponse'
                title: >-
                  Response List Brand Kit Sections Api Brands V1 Organizations 
                  Organizationid  Brandkits  Brandkitid  Sections Get
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Brand kit operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
      security:
        - HTTPBearer: []
  /api/brands/v2/organizations/{organizationId}/brandkits/{brandkitId}/sections/{sectionId}/fields:
    post:
      tags:
        - Brand kit
      summary: Create a brand kit subsection
      description: >-
        Creates a custom brand kit subsection. Each brand kit section contains
        predefined subsections. If a relevant guideline isn’t included by
        default, you can create a custom subsection to define it.

         For example, the *Brand Context* section has default subsections has subsections to define the brand's purpose, history, and more. To add a new subsection for *Brand Values*, you can use this endpoint to create it.
      operationId: >-
        create_brand_kit_section_field_api_brands_v2_organizations__organizationId__brandkits__brandkitId__sections__sectionId__fields_post
      parameters:
        - name: organizationId
          description: |-
            The unique identifier of your organization.

             To get this value, in the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL, the `organizationId` comes after `organization=` . 
          in: path
          required: true
          schema:
            type: string
            example: org_ABCDef123456
        - name: brandkitId
          description: |-
            The unique identifier of your brand kit.

             To get this value, use the [List brand kits](#operation/list_brand_kits_api_brands_v1_organizations__organizationId__brandkits_get) endpoint  to return the `id` of each brand kit in your organization. This is the same `id` returned when you create a brand kit using the [Create a brand kit](#operation/create_brand_kit_api_brands_v1_organizations__organizationId__brandkits_post) endpoint.

             Alternatively, you can open your brand kit in Stream. In the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL,  `brandkitId` comes after `brandkits/`.
          in: path
          required: true
          schema:
            type: string
            example: a1234bcd-efg5-678h-910i-jklmnopqrstu
        - name: sectionId
          description: |-
            The unique identifier of your brand kit section.

             To get this value, use the [List brand kit sections](#operation/list_brand_kit_sections_api_brands_v1_organizations__organizationId__brandkits__brandkitId__sections_get) endpoint. The `id` in the response is the section ID.
          in: path
          required: true
          schema:
            type: string
            example: 37a49437-e1c8-4697-b1c2-914e2382ea75
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBrandKitSectionFieldModelRequest_v2'
      responses:
        '201':
          description: Brand kit subsection created successfully
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/CreateBrandKitSectionFieldModelResponse_v2
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
    get:
      tags:
        - Brand kit
      summary: List brand kit subsections
      description: >-
        Retrieves a list of subsections in a specific brand kit section. Each
        subsection contains guidelines that define that section's content. For
        example, the *Brand Context* section has subsections to define the
        brand's purpose, history, and more. 

         To return actual content in the subsections, the [Documents REST API](https://api-docs.sitecore.com/ai-skills/ai-document-management-rest-api) and [Pipeline REST API](https://api-docs.sitecore.com/ai-skills/ai-pipeline-rest-api) must have already been used to upload and process brand documents for the brand kit.
      operationId: >-
        list_brand_kit_section_fields_api_brands_v2_organizations__organizationId__brandkits__brandkitId__sections__sectionId__fields_get
      parameters:
        - name: organizationId
          description: |-
            The unique identifier of your organization.

             To get this value, in the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL, the `organizationId` comes after `organization=` . 
          in: path
          required: true
          schema:
            type: string
            example: org_ABCDef123456
        - name: brandkitId
          description: |-
            The unique identifier of your brand kit.

             To get this value, use the [List brand kits](#operation/list_brand_kits_api_brands_v1_organizations__organizationId__brandkits_get) endpoint  to return the `id` of each brand kit in your organization. This is the same `id` returned when you create a brand kit using the [Create a brand kit](#operation/create_brand_kit_api_brands_v1_organizations__organizationId__brandkits_post) endpoint.

             Alternatively, you can open your brand kit in Stream. In the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL,  `brandkitId` comes after `brandkits/`.
          in: path
          required: true
          schema:
            type: string
            example: a1234bcd-efg5-678h-910i-jklmnopqrstu
        - name: sectionId
          description: |-
            The unique identifier of your brand kit section.

             To get this value, use the [List brand kit sections](#operation/list_brand_kit_sections_api_brands_v1_organizations__organizationId__brandkits__brandkitId__sections_get) endpoint. The `id` in the response is the section ID.
          in: path
          required: true
          schema:
            type: string
            example: 37a49437-e1c8-4697-b1c2-914e2382ea75
      responses:
        '200':
          description: Brand kit subsections retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: >-
                    #/components/schemas/ListBrandKitSectionFieldsModelResponse_v2
                title: >-
                  Response List Brand Kit Section Fields Api Brands V2
                  Organizations  Organizationid  Brandkits  Brandkitid 
                  Sections  Sectionid  Fields Get
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
  /api/brands/v2/organizations/{organizationId}/brandkits/{brandkitId}/sections/{sectionId}/fields/{fieldId}:
    patch:
      tags:
        - Brand kit
      summary: Partially update a brand kit subsection
      description: |-
        Partially updates a specific subsection in a brand kit.

         A brand kit includes default sections such as *Brand Context*, *Global Goals*, and *Tone of Voice*. Each section contains predefined subsections that reflect your brand guidelines.

         Use this endpoint to update a subsection’s properties, such as intent, content, and AI editability.
      operationId: >-
        update_brand_kit_section_field_api_brands_v2_organizations__organizationId__brandkits__brandkitId__sections__sectionId__fields__fieldId__patch
      parameters:
        - name: organizationId
          in: path
          required: true
          description: |-
            The unique identifier of your organization.

             To get this value, in the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL, the `organizationId` comes after `organization=` . 
          schema:
            type: string
            example: org_ABCDef123456​
        - name: brandkitId
          in: path
          required: true
          description: |-
            The unique identifier of your brand kit.

             To get this value, use the [List brand kits](#operation/list_brand_kits_api_brands_v1_organizations__organizationId__brandkits_get) endpoint  to return the `id` of each brand kit in your organization. This is the same `id` returned when you create a brand kit using the [Create a brand kit](#operation/create_brand_kit_api_brands_v1_organizations__organizationId__brandkits_post) endpoint.

             Alternatively, you can open your brand kit in Stream. In the [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) URL,  `brandkitId` comes after `brandkits/`.
          schema:
            type: string
            example: a1234bcd-efg5-678h-910i-jklmnopqrstu​
        - name: sectionId
          in: path
          required: true
          description: |-
            The unique identifier of your brand kit section.

             To get this value, use the [List brand kit sections](#operation/list_brand_kit_sections_api_brands_v1_organizations__organizationId__brandkits__brandkitId__sections_get) endpoint. The `id` in the response is the section ID.
          schema:
            type: string
            example: 37a49437-e1c8-4697-b1c2-914e2382ea75
        - name: fieldId
          in: path
          required: true
          description: >-
            The unique identifier of the brand kit subsection you want to
            update. 

             To get this value, use the [List brand kit subsections](#operation/list_brand_kit_section_fields_api_brands_v2_organizations__organizationId__brandkits__brandkitId__sections__sectionId__fields_get) endpoint. The `id` in the response is the subsection ID.
          schema:
            type: string
            example: b2f2e1a1-295d-4d40-88f2-93bf545bb878
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBrandKitSectionFieldModelRequest_v2'
      responses:
        '200':
          description: Brand kit subsection updated successfully
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/UpdateBrandKitSectionFieldModelResponse_v2
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
        '409':
          description: Brand kit is locked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Brand kit operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
      security:
        - HTTPBearer: []
components:
  schemas:
    BrandKitSectionFieldReferenceType:
      type: string
      enum:
        - documentChunk
        - webpage
      title: BrandKitSectionFieldReferenceType
    BrandKitSectionFieldType:
      type: string
      enum:
        - text
        - array
        - richArray
      description: The type of brand kit subsection.
      example: text
    BrandKitStatus:
      type: string
      enum:
        - draft
        - inprocess
        - published
        - failed
      example: draft
      description: The current status of the brand kit.
    CreateBrandKitModelRequest:
      properties:
        name:
          type: string
          description: The name of the brand kit.
          example: Powerful EU brand kit
        description:
          description: A brief description of the brand kit.
          example: Brand kit for the Powerful energy bars EU market.
          type:
            - string
            - 'null'
        industry:
          description: The industry this brand kit is associated with.
          example: retail
          type:
            - string
            - 'null'
        brandName:
          description: The name of the brand associated with this brand kit.
          example: Powerful
          type:
            - string
            - 'null'
        companyName:
          description: The name of the company if different from the brand name.
          example: Powerful Europe Ltd.
          type:
            - string
            - 'null'
        logo:
          description: The URL of the PNG image used as the brand kit logo.
          example: https://example.com/logo.png
          type:
            - string
            - 'null'
      type: object
      required:
        - name
    CreateBrandKitModelResponse:
      properties:
        organizationId:
          type: string
          description: The unique identifier of your organization.
          example: org_ABCDef123456
        id:
          type: string
          description: The unique identifier of the brand kit.
          example: a1234bcd-efg5-678h-910i-jklmnopqrstu
        description:
          description: A brief description of the brand kit.
          example: Brand kit for the Powerful energy bars EU market.
          type:
            - string
            - 'null'
        name:
          type: string
          description: The name of the brand kit.
          example: Powerful EU brand kit
        brandName:
          description: The name of the brand associated with this brand kit.
          example: Powerful
          type:
            - string
            - 'null'
        companyName:
          description: The name of the company if different from the brand name.
          example: Powerful Europe Ltd.
          type:
            - string
            - 'null'
        logo:
          description: The URL of the PNG image used as the brand kit logo.
          example: https://example.com/logo.png
          type:
            - string
            - 'null'
        status:
          default: draft
          type:
            - string
            - 'null'
          $ref: '#/components/schemas/BrandKitStatus'
        parentId:
          description: >-
            The parent brand kit ID. Used when AI creates a new version of the
            brand kit during brand ingestion to indicate the original brand kit
            it's based on.
          example: a1234bcd-efg5-678h-910i-abcdefghijklmn
          type:
            - string
            - 'null'
        parentType:
          default: ''
          description: The type of parent this brand kit belongs to.
          example: brandkit
          type:
            - string
            - 'null'
          $ref: '#/components/schemas/ParentTypeEnum'
        industry:
          description: The industry this brand kit is associated with.
          example: retail
          type:
            - string
            - 'null'
        tags:
          description: >-
            An array of tags associated with the brand kit to categorize its
            documents.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TagList'
        references:
          description: An array of references associated with the brand kit.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CreateReferenceModelResponse'
        createdOn:
          description: >-
            The date and time when the brand kit was created, formatted in ISO
            8601.
          format: date-time
          example: '2025-06-18T12:46:12.718310'
          type:
            - string
            - 'null'
        createdBy:
          description: The user who created the brand kit.
          example: mman
          type:
            - string
            - 'null'
        updatedOn:
          description: >-
            The date and time when the brand kit was last updated, formatted in
            ISO 8601.
          format: date-time
          example: '2025-06-18T12:46:12.718310'
          type:
            - string
            - 'null'
        updatedBy:
          description: The user who last updated the brand kit, formatted in ISO 8601.
          example: mman
          type:
            - string
            - 'null'
      type: object
      required:
        - organizationId
        - id
        - name
      title: CreateBrandKitModelResponse
    CreateBrandKitSectionFieldModelRequest_v2:
      properties:
        name:
          description: The name of the subsection to be created.
          example: Localization and cultural sensitivity
          type: string
        type:
          $ref: '#/components/schemas/BrandKitSectionFieldType'
        order:
          description: >-
            The position of the subsection within the brand kit section. For
            example, in the *Global Goals* section, the `order` is `1` for the
            *Digital mandatories* subsection.
          example: 1
          type:
            - integer
            - 'null'
        value:
          description: The value or content of the created subsection.
          example: >-
            Essential requirements for adapting digital content to diverse
            linguistic, cultural, and regional contexts.
          type:
            - string
            - object
            - array
            - 'null'
          items: {}
        intent:
          description: >-
            The intent or prompt that instructs the AI in populating this
            subsection and retrieving information from existing brand knowledge
            based on uploaded brand documents.
          example: The core reason for the brand existence.
          type:
            - string
            - 'null'
        references:
          description: >-
            The brand documents the AI referenced to generate content for this
            subsection.
          type:
            - array
            - 'null'
          items:
            $ref: >-
              #/components/schemas/CreateBrandKitSectionFieldReferenceModelRequest
        deletable:
          description: Whether the subsection can be deleted.
          example: true
          type:
            - boolean
            - 'null'
          default: false
        verified:
          description: Whether the subsection's content has been verified by the user.
          example: true
          type:
            - boolean
            - 'null'
        aiEditable:
          description: >-
            Whether the subsection can be edited by AI. If set to `true`, the AI
            will overwrite the subsection's content value when brand documents
            are reprocessed.
          example: true
          type:
            - boolean
            - 'null'
      type: object
      required:
        - name
        - type
      title: CreateBrandKitSectionFieldModelRequest_v2
    CreateBrandKitSectionFieldModelResponse_v2:
      properties:
        id:
          type: string
          description: ' The unique identifier for the created brand kit subsection.'
          example: b2f2e1a1-295d-4d40-88f2-93bf545bb879
        name:
          type: string
          description: The name of the subsection.
          example: Localization and cultural sensitivity
        type:
          $ref: '#/components/schemas/BrandKitSectionFieldType'
        order:
          description: >-
            The order the subsection appears in the brand kit section. For
            example, if it is the first subsection,  `order` is `1`.
          example: 1
          type:
            - integer
            - 'null'
        value:
          description: The value or content of the created subsection.
          example: >-
            Essential requirements for adapting digital content to diverse
            linguistic, cultural, and regional contexts.
          type:
            - string
            - object
            - array
            - 'null'
          items: {}
        intent:
          description: >-
            The intent or prompt that instructs the AI in populating this
            subsection and retrieving information from existing brand knowledge
            based on uploaded brand documents.
          example: The core reason for the brand existence.
          type:
            - string
            - 'null'
        references:
          description: >-
            The brand documents the AI referenced to generate content for this
            subsection.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CreateReferenceModelResponse'
        deletable:
          description: Whether the subsection can be deleted.
          example: true
          type:
            - boolean
            - 'null'
          default: false
        verified:
          description: Whether the subsection's content has been verified by the user.
          example: true
          type:
            - boolean
            - 'null'
        createdOn:
          description: >-
            The date and time when the subsection was created, formatted in ISO
            8601.
          format: date-time
          example: '2025-06-06T09:33:13.486417'
          type:
            - string
            - 'null'
        createdBy:
          description: The user who created the subsection
          example: mman
          type:
            - string
            - 'null'
        updatedOn:
          description: >-
            The date and time when the subsection was updated, formatted in ISO
            8601.
          format: date-time
          example: '2025-06-06T09:33:13.486417'
          type:
            - string
            - 'null'
        updatedBy:
          description: The user who last updated the subsection.
          example: mman
          type:
            - string
            - 'null'
        aiEditable:
          description: >-
            Whether the subsection can be edited by AI. If set to `true`, the AI
            will overwrite the subsection's content value when brand documents
            are reprocessed.
          example: true
          type:
            - boolean
            - 'null'
      type: object
      required:
        - id
        - name
        - type
      title: CreateBrandKitSectionFieldModelResponse_v2
    CreateBrandKitSectionFieldReferenceModelRequest:
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the document used in the brand kit
            subsection.
          example: 2ad5c154-6404-49ed-9ffc-0603c360a5af
        path:
          type: string
          description: The location of the reference used in the brand kit subsection.
          pattern: >-
            ^\/?(?:[A-Za-z0-9\-._~!$&'()*+,;=:@]|%[0-9A-Fa-f]{2})*(?:\/(?:[A-Za-z0-9\-._~!$&'()*+,;=:@|]|%[0-9A-Fa-f]{2})*)*$
          example: /path
        type:
          $ref: '#/components/schemas/BrandKitSectionFieldReferenceType'
      type: object
      required:
        - id
        - path
        - type
      title: CreateBrandKitSectionFieldReferenceModelRequest
    CreateReferenceModelResponse:
      properties:
        id:
          type: string
          description: The unique identifier of the document used in the brand kit.
          example: 2ad5c154-6404-49ed-9ffc-0603c360a5af
        path:
          type: string
          description: The location of the reference used in the brand kit.
          example: /path
        type:
          type: string
          description: The type of reference used in the brand kit.
          example: document
      type: object
      required:
        - id
        - path
        - type
    DataList:
      properties:
        organizationId:
          type: string
          description: 'The unique identifier of your organization. '
          example: org_ABCDef123456
        id:
          type: string
          description: The unique identifier of the brand kit.
          example: a1234bcd-efg5-678h-910i-jklmnopqrstu
        description:
          type:
            - string
            - 'null'
          description: A brief description of the brand kit.
          example: Brand kit for the Powerful energy bars EU market.
        name:
          type: string
          description: The name of the brand kit.
          example: Powerful EU brand kit
        brandName:
          type:
            - string
            - 'null'
          description: The name of the brand associated with this brand kit.
          example: Powerful
        companyName:
          type:
            - string
            - 'null'
          description: The name of the company if different from the brand name.
          example: Powerful Europe Ltd.
        logo:
          type:
            - string
            - 'null'
          description: The URL of the PNG image used as the brand kit logo.
          example: https://example.com/logo.png
        status:
          type:
            - string
            - 'null'
          description: The current status of the brand kit.
          example: Draft
        parentId:
          type:
            - string
            - 'null'
          description: >-
            The parent brand kit ID. Used when AI creates a new version of the
            brand kit during brand ingestion to indicate the original brand kit
            it's based on.
          example: a1234bcd-efg5-678h-910i-abcdefghijklmn
        parentType:
          type:
            - string
            - 'null'
          description: The type of parent this brand kit belongs to.
          example: brandkit
        industry:
          type:
            - string
            - 'null'
          description: The industry this brand kit is associated with.
          example: retail
        createdOn:
          description: >-
            The date and time when the brand kit was created, formatted in ISO
            8601.
          format: date-time
          example: '2025-06-18T12:46:12.718310'
          type:
            - string
            - 'null'
        createdBy:
          description: The user who created the brand kit.
          example: mman
          type:
            - string
            - 'null'
        updatedOn:
          description: >-
            The date and time when the brand kit was last updated, formatted in
            ISO 8601.
          format: date-time
          example: '2025-06-18T12:46:12.718310'
          type:
            - string
            - 'null'
        updatedBy:
          description: The user who last updated the brand kit, formatted in ISO 8601.
          example: mman
          type:
            - string
            - 'null'
        tags:
          description: >-
            An array of tags associated with the brand kit to categorize its
            documents.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TagList'
          default: []
        references:
          description: An array of references associated with the brand kit.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ListReferencesModelResponseData'
          default: []
        deletedAt:
          description: >-
            The date and time when the brand kit was deleted, formatted in ISO
            8601.
          format: date-time
          example: '2025-06-18T12:46:12.718310'
          type:
            - string
            - 'null'
      type: object
      required:
        - organizationId
        - id
        - name
      title: DataList
    DuplicateError:
      properties:
        detail:
          type: string
          title: Detail
        loc:
          items:
            type: string
          type: array
          title: Loc
          default:
            - body
            - name
        msg:
          type: string
          title: Msg
          default: Brand name already exists.
        type:
          type: string
          title: Type
          default: value_error.duplicate
      additionalProperties: false
      type: object
      required:
        - detail
      title: DuplicateError
    DuplicateHTTPError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/DuplicateError'
          type: array
          title: Detail
      additionalProperties: false
      type: object
      required:
        - detail
      title: DuplicateHTTPError
    GetBrandKitModelResponse:
      properties:
        organizationId:
          type: string
          description: The unique identifier of your organization.
          example: org_ABCDef123456
        id:
          type: string
          description: The unique identifier of the brand kit.
          example: a1234bcd-efg5-678h-910i-jklmnopqrstu
        description:
          type:
            - string
            - 'null'
          description: A brief description of the brand kit.
          example: Brand kit for the Powerful energy bars EU market.
        name:
          type: string
          description: The name of the brand kit.
          example: Powerful EU brand kit
        brandName:
          type:
            - string
            - 'null'
          description: The name of the brand associated with this brand kit.
          example: Powerful
        companyName:
          type:
            - string
            - 'null'
          description: The name of the company if different from the brand name.
        logo:
          type:
            - string
            - 'null'
          description: The URL of the PNG image used as the brand kit logo.
          example: https://example.com/logo.png
        status:
          type:
            - string
            - 'null'
          description: The current status of the brand kit.
          example: Draft
        parentId:
          type:
            - string
            - 'null'
          description: >-
            The parent brand kit ID. Used when AI creates a new version of the
            brand kit during brand ingestion to indicate the original brand kit
            it's based on.
          example: a1234bcd-efg5-678h-910i-abcdefghijklmn
        parentType:
          type:
            - string
            - 'null'
          description: The type of parent this brand kit belongs to.
          example: brandkit
        industry:
          type:
            - string
            - 'null'
          description: The industry this brand kit is associated with.
          example: retail
        createdOn:
          description: >-
            The date and time when the brand kit was created, formatted in ISO
            8601.
          format: date-time
          example: '2025-06-18T12:46:12.718310'
          type:
            - string
            - 'null'
        createdBy:
          description: The user who created the brand kit.
          example: mman
          type:
            - string
            - 'null'
        updatedOn:
          description: >-
            The date and time when the brand kit was last updated, formatted in
            ISO 8601.
          format: date-time
          example: '2025-06-18T12:46:12.718310'
          type:
            - string
            - 'null'
        updatedBy:
          description: The user who last updated the brand kit, formatted in ISO 8601.
          example: mman
          type:
            - string
            - 'null'
        tags:
          description: >-
            An array of tags associated with the brand kit to categorize its
            documents.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TagList'
        references:
          description: An array of references associated with the brand kit.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/GetReferenceModelResponse'
          example: brandkit
        deletedAt:
          type:
            - string
            - 'null'
          description: >-
            The date and time when the brand kit was deleted, if applicable,
            formatted in ISO 8601.
          format: date-time
          example: '2025-06-18T12:46:12.718'
        locked:
          type:
            - boolean
            - 'null'
          description: >-
            Whether the brand kit is locked. A locked brand kit cannot be
            modified or deleted.
          example: 'false'
          default: false
      type: object
      required:
        - organizationId
        - id
        - name
        - tags
        - references
      title: GetBrandKitModelResponse
    GetReferenceModelResponse:
      properties:
        id:
          type: string
          description: The unique identifier of the reference document.
          example: 2ad5c154-6404-49ed-9ffc-0603c360a5af
        path:
          type: string
          description: The location of the reference.
          example: /path
        type:
          type: string
          example: document
          description: The type of reference used.
      type: object
      required:
        - id
        - path
        - type
    HTTPError:
      properties:
        detail:
          type: string
          title: Detail
      additionalProperties: false
      type: object
      required:
        - detail
      title: HTTPError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ListBrandKitSectionFieldsModelResponse_v2:
      properties:
        id:
          type: string
          description: The unique identifier of the brand kit subsection.
          example: b2f2e1a1-295d-4d40-88f2-93bf545bb878
        name:
          type: string
          description: The name of the subsection in the brand kit.
          example: Brand purpose
        type:
          $ref: '#/components/schemas/BrandKitSectionFieldType'
        order:
          description: >-
            The position of the subsection within the brand kit section. For
            example, in the *Global Goals* section, the `order` is `1` for the
            *Digital mandatories* subsection.
          example: 1
          type:
            - integer
            - 'null'
        value:
          description: >-
            The content of the subsection in the brand kit section. This can be
            a string, an array, or a rich text object.
          example: >-
            The core reason for the brand existence is to fuel the potential of
            active individuals with clean, nutrient-dense energy solutions.
          type:
            - string
            - object
            - array
            - 'null'
          items: {}
        intent:
          description: >-
            The intent or prompt that instructs the AI in populating this
            subsection and retrieving information from existing brand knowledge
            based on uploaded brand documents.
          example: The core reason for the brand existence.
          type:
            - string
            - 'null'
        references:
          description: >-
            An array of references used in this subsection. Each reference
            points to a brand document that provides context or content for the
            subsection.
          example: {}
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ListReferencesModelResponseData'
        deletable:
          description: Whether the subsection can be deleted.
          example: true
          type:
            - boolean
            - 'null'
        verified:
          description: Whether the subsection's content has been verified by the user.
          example: true
          type:
            - boolean
            - 'null'
        createdOn:
          description: >-
            The date and time when the subsection was created, formatted in ISO
            8601.
          format: date-time
          example: '2025-06-18T12:46:12.718310'
          type:
            - string
            - 'null'
        createdBy:
          description: The user who created the subsection.
          example: mman
          type:
            - string
            - 'null'
        updatedOn:
          description: >-
            The date and time when the subsection was last updated, formatted in
            ISO 8601.
          format: date-time
          example: 22025-06-18T12:46:12.718310
          type:
            - string
            - 'null'
        updatedBy:
          description: The user who last updated the subsection, formatted in ISO 8601.
          example: mman
          type:
            - string
            - 'null'
        aiEditable:
          description: >-
            Whether the subsection can be edited by AI. If set to `true`, the AI
            will overwrite the subsection's content when brand documents are
            reprocessed.
          example: true
          type:
            - boolean
            - 'null'
      type: object
      required:
        - id
        - name
        - type
      title: ListBrandKitSectionFieldsModelResponse_v2
    ListBrandKitSectionsModelResponse:
      properties:
        deletable:
          description: Whether the section can be deleted.
          example: true
          type:
            - boolean
            - 'null'
        id:
          type: string
          description: The unique identifier of the brand kit section.
          example: 37a49437-e1c8-4697-b1c2-914e2382ea75
        name:
          type: string
          description: The name of the brand kit section.
          example: Brand Context
        order:
          description: >-
            The position of the section within the brand kit. For example, if
            *Global Goals* is the first section, its `order` is `1`. If *Brand
            Context* is second, `order` is `2`, and so on.
          example: 2
          type:
            - integer
            - 'null'
        createdOn:
          description: >-
            The date and time when the section was created, formatted in ISO
            8601.
          format: date-time
          example: '2025-06-18T12:46:12.718310'
          type:
            - string
            - 'null'
        createdBy:
          description: The user who created the section.
          example: mman
          type:
            - string
            - 'null'
        updatedOn:
          description: >-
            The date and time when the section was last updated, formatted in
            ISO 8601.
          format: date-time
          example: '2025-06-18T12:46:12.718310'
          type:
            - string
            - 'null'
        updatedBy:
          description: The user who last updated the section.
          example: mman
          type:
            - string
            - 'null'
        deletedAt:
          description: >-
            The date and time when the section was deleted, if applicable,
            formatted in ISO 8601.
          format: date-time
          example: '2025-06-18T12:46:12.718310'
          type:
            - string
            - 'null'
      type: object
      required:
        - id
        - name
      title: ListBrandKitSectionsModelResponse
    ListBrandKitsModelResponse:
      properties:
        totalCount:
          type: integer
          description: The total number of brand kits available in the organization.
          example: '10'
        pageSize:
          type: integer
          description: The number of brand kits returned per page.
          example: '5'
        pageNumber:
          type: integer
          description: The current page number of the brand kits list.
          example: '1'
        data:
          description: An array of brand kits available in the organization.
          items:
            $ref: '#/components/schemas/DataList'
          type: array
      type: object
      required:
        - totalCount
        - pageSize
        - pageNumber
        - data
      title: ListBrandKitsModelResponse
    ListReferencesModelResponseData:
      properties:
        id:
          type: string
          description: The unique identifier of the reference document.
          example: 2ad5c154-6404-49ed-9ffc-0603c360a5af
        path:
          type: string
          description: The location of the reference.
          example: /path
        type:
          type: string
          example: document
          description: The type of reference used.
      type: object
      required:
        - id
        - path
        - type
    ParentTypeEnum:
      type: string
      enum:
        - brandkit
        - ''
    TagList:
      properties:
        category:
          type: string
          description: The main grouping or classification applied to the brand kit.
          example: audience
        values:
          items:
            type: string
            description: The individual tags used to organize the brand kit.
            example: EU
          type: array
      type: object
      required:
        - category
        - values
    UpdateBrandKitSectionFieldModelRequest_v2:
      properties:
        deletable:
          description: Whether the subsection can be deleted.
          example: false
          type:
            - boolean
            - 'null'
          default: false
        name:
          description: The name of the subsection to be updated.
          example: Brand purpose
          type:
            - string
            - 'null'
        verified:
          description: Whether the subsection's content has been verified by the user.
          example: true
          type:
            - boolean
            - 'null'
        order:
          description: >-
            The position of the subsection within the brand kit section. For
            example, in the *Global Goals* section, the `order` is `1` for the
            *Digital mandatories* subsection.
          example: 1
          type:
            - integer
            - 'null'
        value:
          description: The new content of the subsection in the brand kit section.
          example: >-
            The core purpose is to fuel the potential of active individuals with
            clean, nutrient-dense energy solutions.
          type:
            - string
            - object
            - array
            - 'null'
          items: {}
        intent:
          description: >-
            The intent or prompt that instructs the AI in populating this
            subsection and retrieving information from existing brand knowledge
            based on uploaded brand documents.
          example: The core reason for the brand existence.
          type:
            - string
            - 'null'
        sources:
          description: >-
            The brand documents the AI referenced to generate content for this
            subsection.
          type:
            - array
            - 'null'
          items:
            type: string
        aiEditable:
          description: >-
            Whether the subsection can be edited by AI. If set to `true`, the AI
            will overwrite the subsection's content value when brand documents
            are reprocessed.
          example: true
          type:
            - boolean
            - 'null'
      type: object
      title: UpdateBrandKitSectionFieldModelRequest_v2
    UpdateBrandKitSectionFieldModelResponse_v2:
      properties:
        id:
          type: string
          description: The unique identifier of the updated brand kit subsection.
          example: b2f2e1a1-295d-4d40-88f2-93bf545bb878
        name:
          type: string
          description: The name of the subsection.
          example: Brand purpose
        type:
          $ref: '#/components/schemas/BrandKitSectionFieldType'
        order:
          description: >-
            The order the subsection appears in the brand kit section. For
            example, if it is the first subsection,  `order` is `1`.
          example: 1
          type:
            - integer
            - 'null'
        value:
          description: The new value or content of the updated subsection.
          example: Example brand guideline update.
          type:
            - string
            - object
            - array
            - 'null'
          items: {}
        intent:
          description: >-
            The intent or prompt that instructs the AI in populating this
            subsection and retrieving information from existing brand knowledge
            based on uploaded brand documents.
          example: The core reason for the brand existence.
          type:
            - string
            - 'null'
        deletable:
          description: Whether the subsection can be deleted.
          example: true
          type:
            - boolean
            - 'null'
          default: false
        verified:
          description: Whether the subsection's content has been verified by the user.
          example: true
          type:
            - boolean
            - 'null'
        createdOn:
          description: >-
            The date and time when the subsection was created, formatted in ISO
            8601.
          format: date-time
          example: '2025-06-06T09:33:13.486417'
          type:
            - string
            - 'null'
        createdBy:
          description: The user who created the subsection
          example: mman
          type:
            - string
            - 'null'
        updatedOn:
          description: >-
            The date and time when the subsection was updated, formatted in ISO
            8601.
          format: date-time
          example: '2025-06-06T09:33:13.486417'
          type:
            - string
            - 'null'
        updatedBy:
          description: The user who last updated the subsection.
          example: mman
          type:
            - string
            - 'null'
        aiEditable:
          description: >-
            Whether the subsection can be edited by AI. If set to `true`, the AI
            will overwrite the subsection's content value when brand documents
            are reprocessed.
          example: true
          type:
            - boolean
            - 'null'
        references:
          description: >-
            The brand documents the AI referenced to generate content for this
            subsection.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/GetReferenceModelResponse'
      type: object
      required:
        - id
        - name
        - type
        - references
    ValidationError:
      properties:
        loc:
          items:
            type:
              - string
              - integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
tags:
  - name: Brand kit
    description: >-
      The Brand kit API lets you create and retrieve brand kits within your
      organization. You can also retrieve or update sections—such as *Brand
      Context*, *Global Goals*, and *Tone of Voice*—and retrieve or create
      subsections within those sections.
security:
  - HTTPBearer: []
