update (#74)

Co-authored-by: jianli_mstr <jianli@strategy.com>

Author: JianWater

docs/common-workflows/administration/distribution-services/manage-subscriptions/mobile-subscriptions.md

@@ -12,24 +12,17 @@ This workflow sample demonstrates how to create and update a mobile subscription
 
 :::tip
 
-This workflow follows the general steps described in
-[Create and get a subscription](create-and-get-a-subscription.md). You can try out this workflow at
-[REST API Playground](https://www.postman.com/microstrategysdk/workspace/microstrategy-rest-api/folder/16131298-da43d1b1-a332-4452-829f-e07a041abc8f?ctx=documentation).
+This workflow follows the general steps described in [Create and get a subscription](create-and-get-a-subscription.md). You can try out this workflow at [REST API Playground](https://www.postman.com/microstrategysdk/workspace/microstrategy-rest-api/folder/16131298-da43d1b1-a332-4452-829f-e07a041abc8f?ctx=documentation).
 
 Learn more about Strategy REST API Playground [here](/docs/getting-started/playground.md).
 
 :::
 
 ## Create a new mobile subscription
 
-Endpoint:
-[POST /api/subscriptions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Subscriptions/createSubscription)
+Endpoint: [POST /api/subscriptions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Subscriptions/createSubscription)
 
-This endpoint allows you to create a new subscription for a given project. Obtain the authorization
-token needed to execute the request using `POST /api/auth/login`. Obtain the project ID using
-`GET /api/projects`. Provide the information used to create a subscription in the body parameter of
-the request. If the call is successful, the resulting HTTP response returns an HTTP status code of
-201 and a response body containing all the information on the newly created subscription.
+This endpoint allows you to create a new subscription for a given project. Obtain the authorization token needed to execute the request using `POST /api/auth/login`. Obtain the project ID using `GET /api/projects`. Provide the information used to create a subscription in the body parameter of the request. If the call is successful, the resulting HTTP response returns an HTTP status code of 201 and a response body containing all the information on the newly created subscription.
 
 Sample Request
 
@@ -211,15 +204,9 @@ Sample Response
 
 ## Update an existing mobile subscription
 
-Endpoint:
-[PUT /api/subscriptions/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Subscriptions/updateSubscription)
+Endpoint: [PUT /api/subscriptions/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Subscriptions/updateSubscription)
 
-This endpoint allows you to update all of the information for a specific subscription. Obtain the
-authorization token needed to execute the request using `POST /api/auth/login`. Obtain the project
-ID using `GET /api/projects`. Provide the information used to update a subscription in the body
-parameter of the request and provide the subscription ID in the request path. If the call is
-successful, the resulting HTTP response returns an HTTP status code of 200 and a response body
-containing all the information on the updated subscription.
+This endpoint allows you to update all of the information for a specific subscription. Obtain the authorization token needed to execute the request using `POST /api/auth/login`. Obtain the project ID using `GET /api/projects`. Provide the information used to update a subscription in the body parameter of the request and provide the subscription ID in the request path. If the call is successful, the resulting HTTP response returns an HTTP status code of 200 and a response body containing all the information on the updated subscription.
 
 Sample Request
 

docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md

@@ -10,20 +10,20 @@ This workflow sample demonstrates how to get a question's answer by the question
 
 :::info
 
-Obtain the authorization token needed to execute the request using
-[POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin).
+Obtain the authorization token needed to execute the request using [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin).
 
 :::
 
 ## Get a question with question ID
 
-Endpoint:
-[GET /api/questions/\{questionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/queryMessage_1)
+Endpoint: [GET /api/questions/\{questionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/queryMessage_1)
 
-:::note Replace `{questionId}` in `GET /api/questions/{questionId}` with your question ID from
-`POST /api/questions`. :::
+:::note
+Replace `{questionId}` in `GET /api/questions/{questionId}` with your question ID from `POST /api/questions`.
+:::
 
-Sample Request Body: No request body.
+Sample Request Body:
+No request body.
 
 Sample Curl:
 
@@ -49,8 +49,7 @@ The response is the question and answer with the specific ID.
 
 ### Response when the question is still being processed
 
-If the response code is 202, indicating that the question is still being processed, continue calling
-this API to check the status of the question.
+If the response code is 202, indicating that the question is still being processed, continue calling this API to check the status of the question.
 
 If the question is being processed, the response is:
 

docs/common-workflows/analytics/auto-bot-api/get-questions-by-bot.md

@@ -6,20 +6,17 @@ description: This workflow sample demonstrates how to get the historical chat me
 
 <Available since="Strategy ONE (March 2025)" />
 
-This API is used to get the historical questions from a specific agent for the current user, which
-can be used as the `history` parameter in the `Ask a question to a specific agent` API.
+This API is used to get the historical questions from a specific agent for the current user, which can be used as the `history` parameter in the `Ask a question to a specific agent` API.
 
 :::info
 
-Obtain the authorization token needed to execute the request using
-[POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin).
+Obtain the authorization token needed to execute the request using [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin).
 
 :::
 
 ## Get Questions by Agent
 
-Endpoint:
-[GET /api/questions/](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/getChats_1)
+Endpoint: [GET /api/questions/](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/getChats_1)
 
 Sample Request Headers:
 
@@ -100,5 +97,6 @@ The response is a list of questions and answers from the specific agent.
 }
 ```
 
-:::note Questions with `type` as `snapshots` should not be used as history in the
-`Ask a Specific Bot a Question` API. :::
+:::note
+Questions with `type` as `snapshots` should not be used as history in the `Ask a Specific Bot a Question` API.
+:::

docs/common-workflows/analytics/unstructured-data-api/get-unstructured-data-categories.md

@@ -0,0 +1,88 @@
+---
+title: Get categories for an unstructured data
+description: This page explains how to retrieve categories (tags) for a specific unstructured data item that helps agents better understand and use the data.
+---
+
+<Available since="Strategy ONE (March 2026)" />
+
+This API is used to retrieve the categories for unstructured data. Categories are tags that describe the data within the unstructured data, helping agents better understand the context and content of the data source. By retrieving the categories, you can see which descriptive tags have been assigned to the data and use this information to understand how agents will interpret and utilize the data source when answering questions.
+
+:::info
+
+Obtain the authorization token needed to execute the request using [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin).
+
+:::
+
+## Get categories for an unstructured data
+
+Endpoint: [GET /api/nuggets/\{id}/categories](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots/getCategories)
+
+Request Parameters:
+
+| Name             | Located in | Description                 | Required | Type   |
+| ---------------- | ---------- | --------------------------- | -------- | ------ |
+| id               | path       | ID of the unstructured data | Yes      | string |
+| X-MSTR-AuthToken | header     | Authentication token        | Yes      | string |
+| X-MSTR-ProjectID | header     | Project ID                  | Yes      | string |
+
+Sample Curl:
+
+```bash
+# Replace with your actual values
+curl -X GET 'https://demo.microstrategy.com/MicroStrategyLibrary/api/nuggets/4B7EF8B549D2D32E941C3E9B7E0CD754/categories' \
+-H 'X-MSTR-AuthToken: pqu5mkrcbv4461hh5qprr9j5ve' \
+-H 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \
+-H 'Content-Type: application/json'
+```
+
+Sample Response:
+
+HTTP Status: 200 OK
+
+```json
+{
+  "key1": ["v11", "v12", "v13"],
+  "key2": ["v2", "v22"]
+}
+```
+
+Response Structure:
+
+The response is a JSON object where:
+
+- Each key represents a category name (tag type)
+- Each value is an array of strings representing the category values (tags) for that category
+
+Notes:
+
+- This API returns a 200 OK response with the categories as a JSON object.
+- Categories are key-value pairs where the key is the category name (tag type) and the value is an array of strings (tags).
+- If no categories are defined for the unstructured data, an empty object `{}` will be returned.
+- Categories serve as descriptive tags that help agents understand the nature and context of the data, enabling them to provide more accurate and relevant answers.
+
+## Use Cases
+
+Tag Discovery and Understanding:
+
+The main use cases for this API include discovering and understanding the descriptive tags assigned to unstructured data:
+
+1. **Understanding Data Context**: Retrieve category tags to understand how the data is described and what context agents use when referencing this data source.
+1. **Tag Validation**: Before updating categories, retrieve the current tags to understand the existing descriptive structure and ensure consistency.
+1. **Data Source Inspection**: Check which tags are assigned to a data source to verify that agents will have the proper context for answering questions.
+1. **UI Display**: Display the category tags in your user interface to help users understand what kind of information is contained in the unstructured data.
+1. **Tag Analytics**: Analyze tag usage across multiple data sources to ensure consistent tagging and identify data sources that may need better descriptions.
+
+Example implementation:
+
+- Fetch category tags when displaying an unstructured data detail page to show users what kind of data is contained.
+- Retrieve tags before updating them to ensure you maintain consistency with existing descriptive schemes.
+- Use tag information to provide users with context about which questions the data source can help answer.
+- Display tags in administrative interfaces to help users understand how agents interpret different data sources.
+- Analyze tags across multiple data sources to ensure consistent and effective tagging for agent performance.
+  Best Practices:
+
+- Cache category tag information to reduce API calls, especially if tags don't change frequently.
+- Handle empty category responses gracefully, indicating that the data source has no descriptive tags.
+- Review retrieved tags to ensure they accurately describe the data and support agent understanding.
+- Use tag information to help users understand what kind of questions this data source can help answer.
+- Verify tags are meaningful and descriptive before relying on them for agent context.

docs/common-workflows/analytics/unstructured-data-api/unstructured-data-api.md

@@ -0,0 +1,31 @@
+---
+title: Unstructured Data APIs
+description: This page contains a summary of REST APIs for managing unstructured data. You can use REST API requests to update and configure unstructured data that agents use to answer questions.
+---
+
+<Available since="Strategy ONE (March 2026)" />
+
+Strategy ONE (March 2026) introduces a set of public APIs designed to manage unstructured data that power agent capabilities.
+
+The Unstructured Data APIs provide comprehensive control over unstructured data, allowing you to update data content, manage categories (tags) that describe the data, and retrieve category information. Unstructured data serves as knowledge sources that agents use to provide contextual and accurate answers to user questions. Categories are descriptive tags that help agents understand the nature and content of each data source, enabling them to provide more relevant and accurate responses. These APIs enable you to keep your data up-to-date and well-described, ensuring optimal agent performance.
+
+Previously available as internal APIs, these endpoints are now publicly accessible, enabling developers to seamlessly integrate unstructured data management into their applications and workflows.
+
+### Key Features
+
+- **Update unstructured data**: Re-upload files to refresh or replace the content of existing unstructured data, keeping your agent's knowledge base current.
+- **Update categories**: Assign or modify category tags that describe the data within unstructured data, helping agents better understand the content and context of each data source.
+- **Retrieve categories**: Get the current category tags of an unstructured data source to understand which descriptive information is available to agents.
+
+### Benefits
+
+- **Content Freshness**: Keep your agent's knowledge base up-to-date by replacing outdated documents with current versions.
+- **Better Agent Understanding**: Use category tags to describe the data within unstructured data, helping agents understand the context and content of each data source.
+- **Improved Answer Accuracy**: By tagging data with relevant categories, agents can better understand when and how to use specific data sources, resulting in more accurate and contextually relevant answers.
+- **Flexible Content Management**: Update data without needing to reconfigure your agents or change their IDs.
+
+For more information on how to use these APIs, see the following sections of this manual:
+
+- [Update an unstructured data](./update-unstructured-data.md)
+- [Update categories for an unstructured data](./update-unstructured-data-categories.md)
+- [Get categories for an unstructured data](./get-unstructured-data-categories.md)

docs/common-workflows/analytics/unstructured-data-api/update-unstructured-data-categories.md

@@ -0,0 +1,103 @@
+---
+title: Update categories for an unstructured data
+description: This page explains how to retrieve categories (tags) for a specific unstructured data item that helps agents better understand and use the data.
+---
+
+<Available since="Strategy ONE (March 2026)" />
+
+This API is used to update the categories for unstructured data. Categories are tags that describe the data within the unstructured data, helping agents better understand the context and content of the data source. By assigning appropriate categories (tags), you enable agents to provide more accurate and contextually relevant answers to user questions.
+
+:::info
+
+Obtain the authorization token needed to execute the request using [POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin).
+
+:::
+
+## Update categories for an unstructured data
+
+Endpoint: [PUT /api/nuggets/\{id}/categories](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots/updateCategories)
+
+Request Parameters:
+
+| Name             | Located in | Description                 | Required | Type   |
+| ---------------- | ---------- | --------------------------- | -------- | ------ |
+| id               | path       | ID of the unstructured data | Yes      | string |
+| X-MSTR-AuthToken | header     | Authentication token        | Yes      | string |
+| X-MSTR-ProjectID | header     | Project ID                  | Yes      | string |
+| body             | body       | Categories to update        | Yes      | object |
+
+Request Body:
+
+The request body should be a JSON object where each key represents a category name and the value is an array of category values. For example:
+
+```json
+{
+  "key1": ["v11", "v12", "v13"],
+  "key2": ["v2", "v22"]
+}
+```
+
+Sample Curl:
+
+```bash
+# Replace with your actual values
+curl -X PUT 'https://demo.microstrategy.com/MicroStrategyLibrary/api/nuggets/4B7EF8B549D2D32E941C3E9B7E0CD754/categories' \
+-H 'X-MSTR-AuthToken: pqu5mkrcbv4461hh5qprr9j5ve' \
+-H 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \
+-H 'Content-Type: application/json' \
+-d '{
+  "department": [
+    "sales",
+    "marketing",
+    "engineering"
+  ],
+  "region": [
+    "north",
+    "south"
+  ]
+}'
+```
+
+Sample Response:
+
+HTTP Status: 200 OK
+
+```json
+{
+  "status": "success"
+}
+```
+
+Notes:
+
+- This API returns a 200 OK response upon successful update of the categories.
+- Categories are key-value pairs where the key is the category name (tag type) and the value is an array of strings representing category values (tags).
+- Updating categories will replace the existing categories for the specified unstructured data.
+- Categories serve as descriptive tags that help agents understand the nature and context of the data, enabling them to provide more accurate and relevant answers.
+
+## Use Cases
+
+Data Description and Agent Enhancement:
+
+The main use cases for this API include tagging unstructured data to help agents better understand and utilize the content:
+
+1. **Content Description**: Tag unstructured data with descriptive categories (e.g., content type, department, topic) to help agents understand what kind of information is contained in the data source.
+1. **Contextual Understanding**: Use category tags to provide context about the data, enabling agents to determine when this data source is relevant for answering specific questions.
+1. **Improved Answer Accuracy**: By tagging data with relevant categories, agents can better match user questions to the appropriate data sources, resulting in more accurate and contextually relevant answers.
+1. **Domain-Specific Knowledge**: Assign domain-specific tags (e.g., "finance", "HR policies", "technical documentation") to help agents identify which data sources to reference for different types of questions.
+
+Example implementation:
+
+- Define a standard set of category tags for your organization (e.g., "sales", "product-info", "policies", "technical-specs").
+- When uploading new unstructured data, assign descriptive tags based on the content and its intended use.
+- Update category tags as the content or organizational focus changes to keep agent responses relevant.
+- Use consistent tagging schemes across all unstructured data to help agents make better connections.
+- Tag data with multiple categories when appropriate to cover different aspects of the content.
+
+Best Practices:
+
+- Use consistent and descriptive naming conventions for category tags across your organization.
+- Keep tags simple, clear, and focused on helping agents understand the data content.
+- Document your tagging schema to ensure all team members use tags consistently.
+- Use specific tags rather than overly broad ones to give agents more precise context.
+- Regularly review and update tags to ensure they accurately describe the current data and support agent performance.