# Brand Management API

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 documentation](https://doc.sitecore.com/).

# 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'
  ```


Version: v1.0
License: Apache 2.0

Metadata:
  - product: AI skills

## Servers

Production server
```
https://edge-platform.sitecorecloud.io/stream/ai-brands-api
```

Production server
```
https://edge-platform.sitecorecloud.io/ai/ai-brands-api
```

## Security

### HTTPBearer

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

 - [Brand Management API](https://api-docs.sitecore.com/_bundle/ai-skills/ai-brand-management-rest-api/index.yaml)

## Brand kit

 - [GET /api/brands/v1/organizations/{organizationId}/brandkits](https://api-docs.sitecore.com/ai-skills/ai-brand-management-rest-api/brand-kit/list_brand_kits.md): 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
 - [POST /api/brands/v1/organizations/{organizationId}/brandkits](https://api-docs.sitecore.com/ai-skills/ai-brand-management-rest-api/brand-kit/create_brand_kit.md): 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 resp
 - [GET /api/brands/v1/organizations/{organizationId}/brandkits/{brandkitId}](https://api-docs.sitecore.com/ai-skills/ai-brand-management-rest-api/brand-kit/get_brand_kit.md): 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 con
 - [GET /api/brands/v1/organizations/{organizationId}/brandkits/{brandkitId}/sections](https://api-docs.sitecore.com/ai-skills/ai-brand-management-rest-api/brand-kit/list_brand_kit_sections.md): 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
 - [POST /api/brands/v2/organizations/{organizationId}/brandkits/{brandkitId}/sections/{sectionId}/fields](https://api-docs.sitecore.com/ai-skills/ai-brand-management-rest-api/brand-kit/create_brand_kit_section_field.md): Creates a custom brand kit subsection (field). Each brand kit section contains predefined subsections. If a relevant guideline isn’t included by default, you can create a custom subsection to define i
 - [GET /api/brands/v2/organizations/{organizationId}/brandkits/{brandkitId}/sections/{sectionId}/fields](https://api-docs.sitecore.com/ai-skills/ai-brand-management-rest-api/brand-kit/list_brand_kit_section_fields.md): Retrieves a list of subsections (fields) in a specific brand kit section. Each subsection contains guidelines that define that section's content. For example, the *Brand Context* section has subsectio
 - [GET /api/brands/v3/organizations/{organizationId}/brandkits/{brandkitId}/sections/{sectionId}/fields](https://api-docs.sitecore.com/ai-skills/ai-brand-management-rest-api/brand-kit/list_brand_kit_section_fields_v3.md): Retrieves a paginated list of subsections (fields) in a specific brand kit section, including any associated reference data linked to those fields.
 - [PATCH /api/brands/v2/organizations/{organizationId}/brandkits/{brandkitId}/sections/{sectionId}/fields/{fieldId}](https://api-docs.sitecore.com/ai-skills/ai-brand-management-rest-api/brand-kit/update_brand_kit_section_field.md): Partially updates a specific subsection (field) in a brand kit. A brand kit includes default sections such as *Brand Context*, *Global Goals*, and *Tone of Voice*. Each section contains predefined sub