Sitecore Stream - Manage brand kits and brand documents and ingest using REST API

    

Hello Sitecore Enthusiastic,

Today i will be sharing one of the recent rollouts from Sitecore Stream which is the developer APIs using which one can directly manage their brand kit, upload documents to it and also start ingestion process and that all using APIs.

As recent as June, Sitecore announced REST APIs for Sitecore Partners using which Sitecore partners can now use Stream REST APIs to integrate with their existing systems and support brand governance.

List of APIs for Sitecore Stream

https://api-docs.sitecore.com/?product=AI+capabilities

1) Brand Management API

    As we know Brand kit is the major building block of how Stream gets its brand awareness from, So using this brand management API, You can create new brand kit, you can get specific brand kit or list of brand kits and also can get specific section of brand kit like brand context, tone of voice etc and also can update them.

2) Document Management API

    Each brand document can represent brand's history, context, tone of voice or what not, So once the brand kit is created, One can now use this document management API to create brand document and upload it to brand kit from where it can be ingested, Use case could be a healthcare client want to have approval workflow before AI starts grounding it, so you can hook this API after certain workflow or approved file is dropped to certain location and use this API to then upload it to brand kit, so the process can be automated before AI starts grounding it, it will be one more additional intelligent step to from compliance or governance point of view.

3) Pipeline API

    During the brand ingestion process, the system analyzes each uploaded document page by page, extracts brand information, and breaks it down into smaller pieces called knowledge chunks. These chunks are then organized, vectorized, and stored as your brand knowledge.

The AI uses this brand knowledge to generate content for each section of the brand kit. After the sections are populated, both the comprehensive brand knowledge and the completed brand kit sections are ready for use by Sitecore copilots and other AI tools.

Prerequisites

Before even using the APIs, you will need to generate JWT token, and to generate the token you will first need to create the Brand kit keys (formerly known as "partner keys") which is typically a client id and secret so that using which you can generate the token and use that token to make subsequent calls.

Sitecore has amazing postman like functionality available right into Sitecore Stream documentation which you can find here Try Now

  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'

If you copy above and just import into postman as a raw text and then just given client id and secret, and you can generate the partner client id and client secret using partner keys.

NOTE: Make sure to copy generated ClientId and Secret and keep it somewhere safe, As once generated and dialog box is closed, You can not get those same things back (Though you can generate new)

HINT : Do you know what is the difference between xp/xm keys and brand kit keys? Both have different scopes, XP/XM keys does not give you access to brand kit APIs, so if you want to play around with brand kit APIs, Make sure you generate brand kit keys.

I have my sample created and imported into postman and it generated token like below 

Now, subsequent calls you can try out from Sitecore portal itself, Some of the calls are below, where i am trying to get list of brand kits i have 

Similarly you can try other calls and make an application of your own which could communicate with Sitecore Stream and get the things done, I have defined use cases which you can do.

It is important to know which region your stream app is operating because while making a call you will need to determine the server url or endpoint which will be validated against your actual region, If not done correctly you might get into errors (Explained below)

Errors

When playing around with APIs, you might get below exceptions 

1) 'str' object has no attribute 'HTTP_400_BAD_REQUEST'

This happens typically when server URL is wrong against which you are making a request, Your stream app will be hosted on SaaS and it will have its region, As of now there four types of server avaialble

a) Production West Europe Server which has "https://ai-brands-api-euw.sitecorecloud.io" URL.

b) Production East US API Server which has "https://ai-brands-api-use.sitecorecloud.io" URL

c) Production Australia East API Server which has "https://ai-brands-api-aue.sitecorecloud.io" URL

d) Production Japan East API Server which has "https://ai-brands-api-jpe.sitecorecloud.io" URL

2) The request failed with status code: 403 - Invalid organizationId

This happens where organizationId is wrong, Typically when you are using Sitecore's UI or "Try now" button, it gives you sample data for region specific env variables, you will need to change those variables to match with your org id etc. else this error will come. 

Use Cases

1) Brand Governance - Where organization wants to have control over which document or information should go to brand guidelines, With this APIs you can automate your item workflows and call these APIs when someone approves the items etc. or in general an automation can be placed to as and when brand guideline updates quarterly or annually, these automation can keep updating brand kits as per updated guidelines.

2) Marketing Automation - Where a company with global brand and regional brands would like to set up tone of voice or campaign specific to region and they would like automate the process of updating the section or sub section of brand kits with regional tone or localize campaigns.

3) External Integration - When scenarios like you would like to read a tone of voice of the brand and use that tone of voice to send email with that tone or generate and email from some system by passing tone of voice so brand feels the same, at that time these APIs can also be used.

4) Ease of brand management - It becomes difficult for a company with so many brand to keep updating the brand specific document or sections as and when brand refreshes or rebranding happens, in those scenarios automation will help sync brands and keep updating them with latest and greatest.

I will be sharing some example and code snippets on GITHUB of above use cases in next blogs

Thanks for reading