diff --git a/docs/common-workflows/administration/project-duplication/project-duplication.md b/docs/common-workflows/administration/project-duplication/project-duplication.md new file mode 100644 index 00000000..36f922ed --- /dev/null +++ b/docs/common-workflows/administration/project-duplication/project-duplication.md @@ -0,0 +1,522 @@ +--- +sidebar_label: Project Duplication +title: Project Duplication +description: The REST API provides endpoints to duplicate projects within same environment, enabling + administrators to create copies of projects with customizable settings. +--- + +Project duplication enables administrators to duplicate projects within the same environment for the same MD type (PostgreSQL to PostgreSQL) directly using REST APIs, replacing the need for legacy tools like Object Manager, Developer. + +## APIs + +- [POST /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/createProjectDuplication) +- [GET /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/getProjectDuplication) +- [GET /api/projectDuplications](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/getProjectDuplications) +- [PUT /api/projectDuplications/\{id}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Project%20Duplication/updateProjectDuplication) + +## Privileges and authorization + +You need the following privileges to use the project duplication functionality: + +- [DssXmlPrivilegesDuplicateProject](https://www2.microstrategy.com/producthelp/Current/WebAPIReference/com/microstrategy/webapi/EnumDSSXMLPrivilegeTypes.html#DssXmlPrivilegesDuplicateProject) and [DssXmlPrivilegesBypassAccessChecks](https://www2.microstrategy.com/producthelp/Current/WebAPIReference/com/microstrategy/webapi/EnumDSSXMLPrivilegeTypes.html#DssXmlPrivilegesBypassAccessChecks) privilege on the duplicated project + +To execute the API, you must get the authorization token by executing the `POST /api/auth/login` +request, and get a token as `X-MSTR-AuthToken` in the response header. Keep the token value. It is +required to execute the REST API. See [Authentication](/docs/getting-started/authentication.md) for +more information. + +## General workflow + +The general workflow for using the project duplication APIs involves: + +1. [Initiate project duplication](#initiate-project-duplication) +1. [Check duplication status](#check-duplication-status) +1. [List all project duplications](#list-all-project-duplications) +1. [Cancel project duplication](#cancel-project-duplication) + +### Initiate project duplication + +Use `POST /api/projectDuplications` to start a project duplication operation. This initiates an +asynchronous process that creates a duplicate of the source project with the settings you specify. + +#### Step 1: Create the duplication request + +Sample Request Header: + +```http +Content-Type: application/json +X-MSTR-AuthToken: +Prefer: respond-async +X-MSTR-ProjectID: +``` + +:::tip The `Prefer: respond-async` header instructs the server to process the duplication asynchronously without waiting for completion. +::: + +Sample Request Body: + +:::important The `source.environment.id` must be equal to `target.environment.id` as project duplication only works within the same environment. +::: + +```json +{ + "source": { + "environment": { + "id": "http://example.com/MicroStrategyLibrary", + "name": "Source Environment" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "name": "Tutorial" + } + }, + "target": { + "environment": { + "id": "http://example.com/MicroStrategyLibrary", + "name": "Target Environment" + }, + "project": { + "name": "Target Project" + } + }, + "settings": { + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [1033, 2052] + } + } +} +``` + +Sample Curl: + +```bash +curl -X POST "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications" \ + -H "Content-Type: application/json" \ + -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" \ + -H "Prefer: respond-async" \ + -H "X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754" \ + -d '{ + "source": { + "environment": { + "id": "http://example.com/MicroStrategyLibrary", + "name": "Source Environment" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "name": "Tutorial" + } + }, + "target": { + "environment": { + "id": "http://example.com/MicroStrategyLibrary", + "name": "Target Environment" + }, + "project": { + "name": "Target Project" + } + }, + "settings": { + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [1033, 2052] + } + } +}' +``` + +Sample Response Code: 202 (Accepted) + +Sample Response Body: + +```json +{ + "id": "F8F1280022A444C5A10B3445B552E33A", + "source": { + "environment": { + "id": "http://example.com/MicroStrategyLibrary", + "name": "Source Environment" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "name": "Tutorial" + }, + "creator": { + "id": "86A002474C1A18F1F92F2B8150A43741", + "name": "mstr1" + } + }, + "target": { + "environment": { + "id": "http://example.com/MicroStrategyLibrary", + "name": "Target Environment" + }, + "project": { + "id": "B0D8B3CC70854505A1576DBBE26C4B8B", + "name": "Target Project" + }, + "creator": { + "id": "86A002474C1A18F1F92F2B8150A43741", + "name": "mstr1" + } + }, + "createdDate": "2025-05-20T02:30:24.632+0000", + "lastUpdatedDate": "2025-05-20T02:34:57.748+0000", + "status": "EXPORTING", + "progress": 0, + "message": "", + "settings": { + "export": { + "projectObjectsPreference": { + "schemaObjectsOnly": false, + "skipEmptyProfileFolders": false + }, + "subscriptionPreferences": { + "includeUserSubscriptions": false, + "includeContactSubscriptions": false + } + }, + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [1033, 2052] + } + } +} +``` + +:::note The duplication process is executed asynchronously. The response includes a unique `id` that you can use to check the status of the operation using the `GET /api/projectDuplications/{id}` endpoint. +::: + +### Check duplication status + +Use `GET /api/projectDuplications/{id}` to check the status of a specific project duplication +operation. Since duplication is an asynchronous process, you should poll this endpoint to monitor +the progress. + +#### Step 2: Monitor the duplication progress + +Sample Request Header: + +```http +X-MSTR-AuthToken: +``` + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications/F8F1280022A444C5A10B3445B552E33A" \ + -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" +``` + +Sample Response Body: + +```json +{ + "id": "F8F1280022A444C5A10B3445B552E33A", + "source": { + "environment": { + "id": "http://example.com/MicroStrategyLibrary", + "name": "Source Environment" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "name": "Tutorial" + }, + "creator": { + "id": "86A002474C1A18F1F92F2B8150A43741", + "name": "mstr1" + } + }, + "target": { + "environment": { + "id": "http://example.com/MicroStrategyLibrary", + "name": "Target Environment" + }, + "project": { + "id": "B0D8B3CC70854505A1576DBBE26C4B8B", + "name": "Target Project" + }, + "creator": { + "id": "86A002474C1A18F1F92F2B8150A43741", + "name": "mstr1" + } + }, + "createdDate": "2025-05-20T02:30:24.632+0000", + "lastUpdatedDate": "2025-05-20T02:34:57.748+0000", + "status": "COMPLETED", + "progress": 100, + "message": "", + "settings": { + "export": { + "projectObjectsPreference": { + "schemaObjectsOnly": false, + "skipEmptyProfileFolders": false + }, + "subscriptionPreferences": { + "includeUserSubscriptions": false, + "includeContactSubscriptions": false + } + }, + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [1033, 2052] + } + } +} +``` + +Sample Response Code: 200 (OK) + +:::info Duplication Status Values + +- `EXPORTING`: The duplication is currently in export progress +- `EXPORTED`: The duplication has been successfully exported +- `EXPORT_FAILED`: The duplication has failed (check the `message` field for details) +- `IMPORTING`: The duplication is currently in import progress +- `IMPORT_FAILED`: The duplication has failed (check the `message` field for details) +- `COMPLETED`: The duplication has been successfully completed +- `CANCELLED`: The duplication was cancelled by a user + +You should poll the status endpoint at reasonable intervals (e.g., every 10-30 seconds) until the +status changes to `COMPLETED`, `IMPORT_FAILED`, `EXPORT_FAILED`, or `CANCELLED`. +::: + +### List all project duplications + +Use `GET /api/projectDuplications` to retrieve a list of all project duplication operations. This is +useful for monitoring and managing multiple duplication tasks. + +#### Retrieving the duplication history + +Sample Request Header: + +```http +X-MSTR-AuthToken: +``` + +Sample Curl: + +```bash +curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications?offset=0&limit=1" \ + -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" +``` + +Sample Response Body: + +```json +{ + "projectDuplications": [ + { + "id": "F8F1280022A444C5A10B3445B552E33A", + "source": { + "environment": { + "id": "http://example.com/MicroStrategyLibrary", + "name": "Source Environment" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754", + "name": "Tutorial" + }, + "creator": { + "id": "86A002474C1A18F1F92F2B8150A43741", + "name": "mstr1" + } + }, + "target": { + "environment": { + "id": "http://example.com/MicroStrategyLibrary", + "name": "Target Environment" + }, + "project": { + "id": "B0D8B3CC70854505A1576DBBE26C4B8B", + "name": "Target Project" + }, + "creator": { + "id": "86A002474C1A18F1F92F2B8150A43741", + "name": "mstr1" + } + }, + "createdDate": "2025-05-20T02:30:24.632+0000", + "lastUpdatedDate": "2025-05-20T02:34:57.748+0000", + "status": "COMPLETED", + "progress": 100, + "message": "", + "settings": { + "export": { + "projectObjectsPreference": { + "schemaObjectsOnly": false, + "skipEmptyProfileFolders": false + }, + "subscriptionPreferences": { + "includeUserSubscriptions": false, + "includeContactSubscriptions": false + } + }, + "import": { + "description": "this is a test description", + "defaultLocale": 2052, + "locales": [1033, 2052] + } + } + } + ] +} +``` + +Sample Response Code: 200 (OK) + +:::tip You can use this endpoint to check all your past and current duplication operations. It provides a comprehensive view of all duplication tasks and their statuses. +::: + +### Cancel project duplication + +Use `PUT /api/projectDuplications/{id}` to cancel an ongoing project duplication operation. This is +useful if you made a mistake or need to stop a long-running duplication task. + +#### Step 3: Cancel a duplication (if needed) + +Sample Request Header: + +```http +Content-Type: application/json +X-MSTR-AuthToken: +``` + +Sample Request Body: + +```json +{ + "status": "cancelled" +} +``` + +Sample Curl: + +```bash +curl -X PUT "https://demo.microstrategy.com/MicroStrategyLibrary/api/projectDuplications/F8F1280022A444C5A10B3445B552E33A" \ + -H "Content-Type: application/json" \ + -H "X-MSTR-AuthToken: o0ak9privdo27nfo798j40m8aa" \ + -d '{ + "status": "cancelled" +}' +``` + +Sample Response Code: 204 (No Content) + +:::note Important limitations: + +- You can only cancel duplications that are in `EXPORTING`, `EXPORTED`, or `IMPORTING` status +- Attempting to cancel a duplication that has already completed (`COMPLETED`), failed + (`EXPORT_FAILED`, `IMPORT_FAILED`), or been cancelled (`CANCELLED`) will result in an error +- Once cancelled, a duplication cannot be resumed and must be initiated again if needed + ::: + +## Project duplication settings + +You can customize various aspects of the project duplication process using the settings in the +request. The following sections describe the available options. + +### Export settings + +The `settings.export` object controls how the source project is exported: + +```json +"settings": { + "export": { + "projectObjectsPreference": { + "schemaObjectsOnly": false, + "skipEmptyProfileFolders": false + }, + "subscriptionPreferences": { + "includeUserSubscriptions": false, + "includeContactSubscriptions": false + } + } +} +``` + +### Import settings + +The `settings.import` object controls how the project is imported to the target environment: + +```json +"settings": { + "import": { + "description": "Development copy of production project", + "defaultLocale": 2052, + "locales": [1033, 2052] + } +} +``` + +## Request fields reference + +The following table describes the fields available in the project duplication request: + +| Field | Type | Description | Required | +| --------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------- | -------- | +| `source.environment.id` | String | URL of the source environment (must be identical to target.environment.id) | Yes | +| `source.environment.name` | String | Name of the source environment | Yes | +| `source.project.id` | String | ID of the source project | Yes | +| `source.project.name` | String | Name of the source project | Yes | +| `target.environment.id` | String | URL of the target environment (must be identical to source.environment.id) | Yes | +| `target.environment.name` | String | Name of the target environment | Yes | +| `target.project.name` | String | Name to assign to the duplicated project | Yes | +| `settings.import.description` | String | Description for the duplicated project | No | +| `settings.import.defaultLocale` | Number | Default locale ID for the duplicated project | No | +| `settings.import.locales` | Array | List of locale IDs to include in the duplicated project | No | +| `settings.export.projectObjectsPreference.schemaObjectsOnly` | Boolean | Whether to include only schema objects | No | +| `settings.export.projectObjectsPreference.skipEmptyProfileFolders` | Boolean | Whether to skip empty profile folders | No | +| `settings.export.subscriptionPreferences.includeUserSubscriptions` | Boolean | Whether to include user subscriptions | No | +| `settings.export.subscriptionPreferences.includeContactSubscriptions` | Boolean | Whether to include contact subscriptions | No | + +## Response fields reference + +The following table describes the fields available in the project duplication response: + +| Field | Type | Description | +| -------------------- | ------ | ---------------------------------------------------------- | +| `id` | String | Unique identifier for the duplication operation | +| `source` | Object | Information about the source project and environment | +| `source.environment` | Object | Details about the source environment | +| `source.project` | Object | Details about the source project | +| `source.creator` | Object | Details about the user who created the source project | +| `target` | Object | Information about the target project and environment | +| `target.environment` | Object | Details about the target environment | +| `target.project` | Object | Details about the target project | +| `target.creator` | Object | Details about the user who created the target project | +| `createdDate` | String | ISO datetime when the duplication was initiated | +| `lastUpdatedDate` | String | ISO datetime when the duplication was last updated | +| `status` | String | Current status of the duplication operation | +| `progress` | Number | Completion percentage of the duplication operation (0-100) | +| `message` | String | Additional information or error message | +| `settings` | Object | Configuration settings used for the duplication operation | + +## Common errors and troubleshooting + +| HTTP Status | Error Code | Description | Resolution | +| ----------- | ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- | +| 400 | DIFFERENT_ENVIRONMENTS | Source and target environments are not the same | Ensure source.environment.id and target.environment.id are identical | +| 400 | INVALID_REQUEST | Request body is not valid | Check the request JSON format and required fields | +| 403 | FORBIDDEN | User lacks sufficient privileges | Ensure the user has administrator privileges on both source and target projects | +| 404 | PROJECT_NOT_FOUND | Source project not found | Verify the source project ID is correct | +| 409 | PROJECT_NAME_EXISTS | Target project name already exists | Choose a different name for the target project | +| 500 | INTERNAL_SERVER_ERROR | Internal server error occurred | Check server logs for details and retry the operation | + +## Best practices + +1. **Plan for downtime**: Project duplication operations can be resource-intensive. Schedule them + during off-peak hours if possible. + +1. **Use descriptive names**: Give your duplicated projects clear, descriptive names that indicate + their purpose (e.g., "Sales_Dev", "Marketing_Test"). + +1. **Monitor progress**: Large projects may take considerable time to duplicate. Use the status + field to monitor progress. + +1. **Testing**: Test the duplication process with a small project before attempting to duplicate + large, complex projects. diff --git a/docs/common-workflows/analytics/auto-bot-api/auto-bot-api.md b/docs/common-workflows/analytics/auto-bot-api/auto-bot-api.md new file mode 100644 index 00000000..712de78b --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/auto-bot-api.md @@ -0,0 +1,28 @@ +--- +title: Next-Gen AI +description: This page contains a summary of REST APIs for the "auto bots" endpoint. You can use REST API requests to interact with Auto Bots. +--- + + + +With the release of Strategy ONE (March 2025), we have introduced an enhanced set of APIs designed to leverage the capabilities of Next-Gen AI. These APIs are built on top of the existing question APIs and are compatible with both the Next-Gen AI and the legacy Auto Bots. + +The Next-Gen AI APIs provide a seamless way to interact with Next-Gen AI, allowing you to ask questions, retrieve answers, and get historical chat messages from specific bots. Additionally, the APIs offer the ability to get suggested questions, enhancing the user experience by providing relevant queries and answers efficiently. + +Starting from Strategy ONE (June 2025), we've added support for retrieving images within answers, allowing for richer, more visual responses from the Next-Gen AI system. This feature includes customizable resolution settings to optimize image quality based on your specific needs. + +### Key Features + +- **Ask a question to a specific bot**: Submit a question to the specific Auto Bot. This API has been enhanced from the existing question API. +- **Get answer by the question ID**: Retrieve the answer to a specific question using its ID. This API has been enhanced from the existing question API. +- **Get chat history from a specific bot**: Obtain all historical chat messages from a specific bot. +- **Get suggested questions from a specific bot**: Get recommended questions based on the context from a specific bot. +- **Image support in answers**: Request and retrieve images as part of answers from Next-Gen AI, with customizable resolution settings. (Available from Strategy ONE (June 2025)) + +For further details on how to use these APIs, please refer to the following sections of this manual: + +- [Ask a question to a specific bot](./post-question.md) +- [Get answer by the question ID](./get-question-by-id.md) +- [Get chat history from a specific bot](./get-questions-by-bot.md) +- [Get suggested questions from a specific bot](./post-suggestion.md) +- [Get image from an answer](./get-image-of-answer.md) diff --git a/docs/common-workflows/analytics/auto-bot-api/get-image-of-answer.md b/docs/common-workflows/analytics/auto-bot-api/get-image-of-answer.md new file mode 100644 index 00000000..97af8bae --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/get-image-of-answer.md @@ -0,0 +1,41 @@ +--- +sidebar_label: Get an image in the answer of a specific question +title: Get an image in the answer of a specific question +description: This workflow sample demonstrates how to get an image in the answer of a specific question. +--- + + + +This workflow sample demonstrates how to get an image in the answer of a specific 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). + +::: + +## Get an image of an answer related to a question with bot routing + +Endpoint: [GET /api/questions/\{questionsId}/answers/images/\{imageId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/getMessageImage) + +:::note +Replace `{questionsId}` in `GET /api/questions/{questionsId}/answers/images/{imageId}` with the question ID from `POST /api/questions` and `{imageId}` with your image ID from `GET /api/questions/{questionId}`. +::: + +Sample Curl: + +```bash +curl 'https://demo.microstrategy.com/MicroStrategyLibrary/api/questions/862D61DE2EDD4937B31139B7F574E8EE/answers/images/32A0F79BB4374D4792253B38C1177A6D' \ +-H 'accept: image/png' \ +-H 'X-MSTR-AuthToken: t40ltbk411923ipk85r8r0tace' \ +``` + +Sample Response: + +| Response Code | Status | +| ------------- | ------------------------------- | +| 200 | Successfully returned the image | +| 400 | Error in getting the image | +| 401 | Authorization failed | +| 403 | Forbidden | +| 404 | Image not found | diff --git a/docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md b/docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md new file mode 100644 index 00000000..911e0d70 --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/get-question-by-id.md @@ -0,0 +1,83 @@ +--- +sidebar_label: Get answer by the question ID +title: Get answer by the question ID +description: This workflow sample demonstrates how to get a question's answer by the question ID. +--- + + + +This workflow sample demonstrates how to get a question's answer by the question ID. + +:::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 a question with question ID + +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`. +::: + +Sample Request Body: +No request body. + +Sample Curl: + +```bash +curl 'https://demo.microstrategy.com/MicroStrategyLibrary/api/questions/9161386651E84054A6230796C84E12C5:68696ADB633946B4B430ABD959433B3B:FCC1C28296014AB19ABD877E60590890' \ +-H 'accept: */*' \ +-H 'X-MSTR-AuthToken: evvk84kcucn8abon6c1qfbud7' \ +``` + +Sample Response Code: + +| Response Code | Status | +| ------------- | ------------------------------------------------------------------------------ | +| 200 | Successfully returned the question from the bot that has been answered | +| 202 | Successfully returned the question from the bot which is still being processed | +| 400 | Error in getting the question from the bot | +| 401 | Authorization failed | +| 404 | Question does not exist | + +## Response Body on Success + +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 question is being processed, the response is: + +```json +{ + "id": "9161386651E84054A6230796C84E12C5:68696ADB633946B4B430ABD959433B3B:FCC1C28296014AB19ABD877E60590890", + "text": "Analyze the distribution of cooking times for recipes", + "answers": [], + "creationDate": "2024-03-08T09:01:43.154+0000" +} +``` + +### Response when all data is ready + +If the status code is 200, indicating that the question has been answered. + +```json +{ + "id": "9161386651E84054A6230796C84E12C5:68696ADB633946B4B430ABD959433B3B:FCC1C28296014AB19ABD877E60590890", + "text": "Analyze the distribution of cooking times for recipes", + "answers": [ + { + "bot": { "id": "68696ADB633946B4B430ABD959433B3B" }, + "text": "#Title 1\nThe distribution of cooking times for recipes is as follows:\n- The shortest cooking time is -1 minute.\n- The majority of recipes have cooking times ranging from 2 to 60 minutes.\n- There are a few recipes with longer cooking times, such as 75, 90, 120, and 720 minutes.\n- The exact distribution of cooking times can be seen in the visualization result.", + "images": [{ "id": "79FD176AEAD9446395B083B5931E9EC7", "width": 800, "height": 600 }], + "route": "sql" + } + ], + "creationDate": "2024-03-08T09:01:43.154+0000" +} +``` diff --git a/docs/common-workflows/analytics/auto-bot-api/get-questions-by-bot.md b/docs/common-workflows/analytics/auto-bot-api/get-questions-by-bot.md new file mode 100644 index 00000000..f5cde644 --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/get-questions-by-bot.md @@ -0,0 +1,102 @@ +--- +sidebar_label: Get chat history from a specific bot +title: Get chat history from a specific bot +description: This workflow sample demonstrates how to get the historical chat messages from a specific bot. +--- + + + +This API is used to get the historical questions from a specific bot for the current user, which can be used as the `history` parameter in the `Ask a question to a specific bot` 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). + +::: + +## Get Questions by Bot + +Endpoint: [GET /api/questions/](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/getChats_1) + +Sample Request Headers: + +| Header | Required | Description | Sample Value | +| ---------------- | -------- | -------------------------- | -------------------------------- | +| X-MSTR-AuthToken | Yes | Authorization Token | t40ltbk411923ipk85r8r0tace | +| X-MSTR-ProjectID | Yes | Project ID | B7CA92F04B9FAE8D941C3E9B7E0CD754 | +| Content-Type | Yes | Type of content being sent | application/json | + +Sample Request Query Strings: + +| Query String | Required | Description | Sample Value | +| ------------ | -------- | ---------------------------------------------------------- | -------------------------------- | +| botId | Yes | The ID of the bot whose chat history you want to retrieve. | 065B007500614D158B41B0D020C96966 | + +Sample Curl: + +```bash +curl 'https://demo.microstrategy.com/MicroStrategyLibrary/api/questions?botId=065B007500614D158B41B0D020C96966' \ +-H 'accept: */*' \ +-H 'X-MSTR-AuthToken: evvk84kcucn8abon6c1qfbud7' \ +-H 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \ +``` + +Sample Response Code: + +| Response Code | Status | +| ------------- | ------------------------------------------------ | +| 200 | Successfully returned the questions from the bot | +| 400 | Error in getting the questions from the bot | +| 401 | Authorization failed | +| 404 | Bot does not exist | + +## Response Body on Success + +The response is a list of questions and answers from the specific bot. + +### Sample Response + +```json +{ + "questions": [ + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:1BA14D43628D40ABA5DF6616843C611F", + "text": "Show the revenue in euros per month of the highest-grossing branch in Germany in 2024 in a gid.", + "answers": [ + { + "bot": { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + }, + "text": "The highest-grossing branch in Germany in 2024 generated the following revenue in euros per month:\n- August: €11,327,719\n- September: €10,847,290\n- October: €12,609,864\n- November: €13,793,524\n- December: €12,002,767", + "route": "sql" + } + ], + "creationDate": "2025-03-06T06:07:47.272+0000", + "snapshot": false, + "type": "snapshots" + }, + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:75262B7346CC469EA7B874E49888040E", + "text": "What was the Umsatz in Euro in Kristallhöhle during 2024/10 Okt?", + "answers": [ + { + "bot": { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + }, + "text": "Der Gesamtumsatz in Euro (Umsatz in Euro) für die Region 'kristallhöhle' im Oktober 2024 betrug €92.541.045.", + "route": "sql" + } + ], + "creationDate": "2025-03-07T02:56:53.708+0000", + "snapshot": false, + "type": "history" + } + ] +} +``` + +:::note +Questions with `type` as `snapshots` should not be used as history in the `Ask a Specific Bot a Question` API. +::: diff --git a/docs/common-workflows/analytics/auto-bot-api/post-question.md b/docs/common-workflows/analytics/auto-bot-api/post-question.md new file mode 100644 index 00000000..d2d1cf9d --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/post-question.md @@ -0,0 +1,129 @@ +--- +sidebar_label: Ask a question to a specific bot +title: Ask a question to a specific bot +description: Submit a question to the Auto Bot and receive an question ID. +--- + + + +Use this API to submit a question to a specific Auto Bot and receive an question ID. + +:::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). + +::: + +## Ask a Specific Bot a Question + +Endpoint: [POST /api/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/createQuestion) + +Sample Request Headers: + +| Header | Required | Description | Sample Value | +| ---------------- | -------- | ----------------------------------------------- | -------------------------- | +| X-MSTR-AuthToken | Yes | Authorization Token | t40ltbk411923ipk85r8r0tace | +| Prefer | Yes | The response mode, which must be respond-async. | respond-async | +| Content-Type | Yes | Type of content being sent | application/json | + +Sample Request Body: + +| Field | Required | Description | Sample Value | +| -------------- | -------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| question | Yes | The question text | Which customer has the highest revenue? | +| bots | Yes | The bot to which the question is directed. Only one bot is supported. | [\{"id": "065B007500614D158B41B0D020C96966", "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754"\}] | +| answers.images | No | Optional. If not specified, the image is not generated. Supports one image. | [\{"width": 800, "height": 600\}] | +| history | No | Optional. Previous questions and answers. Supports up to 5 entries. | [\{"id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:E41CC2178F6042BCAAD72E322E802A90", "question": "show the monthly percentage development of the revenue in euros compared to the previous month for branch a013.. today's date is 04-march-2025. make sure to do correct datetime based calculation.", "text": "The monthly percentage development of revenue in euros for branch A013 shows fluctuations over the observed period. Starting in September 2024, there was an 8% decrease in revenue compared to the previous month. This was followed by a smaller decline of 3% in October 2024. November 2024 saw a slight increase of 1%, while December 2024 experienced a significant rise of 42%. However, in January 2025, there was a notable decrease of 19% in revenue compared to December 2024." \}, \{"id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:5720DC60EBB648FFAFCDE05A7363395B", "question": "what was the revenue in euros for branch a013 in december 2024?", "text": "The revenue in euros for branch A013 in December 2024 was €4,519,521." \}] | + +:::note +Get the history questions by `GET /api/questions?botId={botId}`. +::: + +```json +{ + "question": "What was the Umsatz in Euro in Kristallhöhle during 2024/10 Okt?", + "bots": [ + { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + } + ], + "answers": { + "images": [ + { + "width": 800, + "height": 600 + } + ] + }, + "history": [ + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:E41CC2178F6042BCAAD72E322E802A90", + "question": "show the monthly percentage development of the revenue in euros compared to the previous month for branch a013.. today's date is 04-march-2025. make sure to do correct datetime based calculation.", + "text": "The monthly percentage development of revenue in euros for branch A013 shows fluctuations over the observed period. Starting in September 2024, there was an 8% decrease in revenue compared to the previous month. This was followed by a smaller decline of 3% in October 2024. November 2024 saw a slight increase of 1%, while December 2024 experienced a significant rise of 42%. However, in January 2025, there was a notable decrease of 19% in revenue compared to December 2024." + }, + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:5720DC60EBB648FFAFCDE05A7363395B", + "question": "what was the revenue in euros for branch a013 in december 2024?", + "text": "The revenue in euros for branch A013 in December 2024 was €4,519,521." + } + ] +} +``` + +Sample Curl: + +```bash +curl 'https://demo.microstrategy.com/MicroStrategyLibrary/api/questions' \ +-X 'POST' \ +--header 'X-MSTR-AuthToken: t40ltbk411923ipk85r8r0tace' \ +--header 'X-MSTR-ProjectID: FCC1924411EAABC39C6C0080EFA54501' \ +--header 'Prefer: respond-async' \ +--header 'Content-Type: application/json' \ +--data '{ + "question": "What was the Umsatz in Euro in Kristallhöhle during 2024/10 Okt?", + "bots": [ + { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + } + ], + "answers": { + "images": [ + { + "width": 800, + "height": 600 + } + ] + }, + "history": [ + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:E41CC2178F6042BCAAD72E322E802A90", + "question": "show the monthly percentage development of the revenue in euros compared to the previous month for branch a013.. today's date is 04-march-2025. make sure to do correct datetime based calculation.", + "text": "The monthly percentage development of revenue in euros for branch A013 shows fluctuations over the observed period. Starting in September 2024, there was an 8% decrease in revenue compared to the previous month. This was followed by a smaller decline of 3% in October 2024. November 2024 saw a slight increase of 1%, while December 2024 experienced a significant rise of 42%. However, in January 2025, there was a notable decrease of 19% in revenue compared to December 2024." + }, + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:5720DC60EBB648FFAFCDE05A7363395B", + "question": "what was the revenue in euros for branch a013 in december 2024?", + "text": "The revenue in euros for branch A013 in December 2024 was €4,519,521." + } + ] +}' +``` + +Sample Response: + +| Response Code | Status | +| ------------- | ---------------------------------- | +| 202 | Successfully accepted the question | +| 400 | Error in accepting the question | +| 401 | Authorization failed | +| 404 | No bot found | + +Sample Response Body on success: + +```json +{ + "id": "9161386651E84054A6230796C84E12C5:68696ADB633946B4B430ABD959433B3B:FCC1C28296014AB19ABD877E60590890" +} +``` diff --git a/docs/common-workflows/analytics/auto-bot-api/post-suggestion.md b/docs/common-workflows/analytics/auto-bot-api/post-suggestion.md new file mode 100644 index 00000000..c43fc2df --- /dev/null +++ b/docs/common-workflows/analytics/auto-bot-api/post-suggestion.md @@ -0,0 +1,130 @@ +--- +sidebar_label: Get suggested questions from a specific bot +title: Get suggested questions from a specific bot +description: This workflow sample demonstrates how to get suggested questions from a specific bot. +--- + + + +This workflow sample demonstrates how to get suggested questions from a specific bot. + +:::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). + +::: + +## Ask suggested questions with bot routing + +Endpoint: [POST /api/questions/suggestions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/createSuggestions_1) + +Sample Request Header: + +| Header Name | Required | Description | +| ---------------- | -------- | -------------------------------------------------------- | +| X-MSTR-AuthToken | Yes | Authorization token obtained from `POST /api/auth/login` | +| Content-Type | Yes | The body request type, which must be `application/json` | + +Sample Request Body: + +| Field | Required | Description | Sample Value | +| ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| count | Yes | The count of suggestions you want to get, Supports up to 5. | 5 | +| bots | Yes | The bot to which the question is directed. Only one bot is supported. | [\{"id": "065B007500614D158B41B0D020C96966", "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754"\}] | +| history | No | Optional. Previous questions and answers. Supports up to 5 entries. | [\{"id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:E41CC2178F6042BCAAD72E322E802A90", "question": "show the monthly percentage development of the revenue in euros compared to the previous month for branch a013.. today's date is 04-march-2025. make sure to do correct datetime based calculation.", "text": "The monthly percentage development of revenue in euros for branch A013 shows fluctuations over the observed period. Starting in September 2024, there was an 8% decrease in revenue compared to the previous month. This was followed by a smaller decline of 3% in October 2024. November 2024 saw a slight increase of 1%, while December 2024 experienced a significant rise of 42%. However, in January 2025, there was a notable decrease of 19% in revenue compared to December 2024." \}, \{"id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:5720DC60EBB648FFAFCDE05A7363395B", "question": "what was the revenue in euros for branch a013 in december 2024?", "text": "The revenue in euros for branch A013 in December 2024 was €4,519,521." \}] | +| route | No | Route information for the answer to the last question. Retrieve it from the `route` field in the response of GET /api/questions/\{questionId\}. | sql | + +:::note +Get the history questions by `GET /api/questions?botId={botId}`. +::: + +```json +{ + "count": 3, + "bots": [ + { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + } + ], + "history": [ + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:75262B7346CC469EA7B874E49888040E", + "question": "what was the umsatz in euro in kristallhöhle during october 2024?", + "text": "Der Gesamtumsatz in Euro (Umsatz in Euro) für die Region 'kristallhöhle' im Oktober 2024 betrug €92.541.045." + } + ], + "route": "sql" +} +``` + +Sample Curl: + +```bash +curl 'https://demo.microstrategy.com/MicroStrategyLibrary/api/questions/suggestions' \ +-X 'POST' \ +--header 'X-MSTR-AuthToken: t40ltbk411923ipk85r8r0tace' \ +--header 'Content-Type: application/json' \ +--data '{ + "count": 3, + "bots": [ + { + "id": "065B007500614D158B41B0D020C96966", + "projectId": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + } + ], + "history": [ + { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754:065B007500614D158B41B0D020C96966:75262B7346CC469EA7B874E49888040E", + "question": "what was the umsatz in euro in kristallhöhle during october 2024?", + "text": "Der Gesamtumsatz in Euro (Umsatz in Euro) für die Region 'kristallhöhle' im Oktober 2024 betrug €92.541.045." + } + ], + "route": "sql" +}' +``` + +Sample Response: + +| Response Code | Status | +| ------------- | --------------------------------------------- | +| 200 | Successfully returned the suggested questions | +| 400 | Error in generating the suggested questions | +| 401 | Authorization failed | +| 404 | No bot or bot instance found | + +Sample Response Body on Success: + +```json +{ + "suggestions": [ + { + "bot": { + "id": "065B007500614D158B41B0D020C96966" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + }, + "text": "What is the Umsatz in Euro for the Duft Warensortiment in the Kristallhöhle region during November 2024?" + }, + { + "bot": { + "id": "065B007500614D158B41B0D020C96966" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + }, + "text": "How much Menge was sold for the Ernährung Warensortiment in the Zauberwald region in September 2024?" + }, + { + "bot": { + "id": "065B007500614D158B41B0D020C96966" + }, + "project": { + "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754" + }, + "text": "What was the Umsatz in Euro for Haar Warensortiment in Zauberwald during December 2024?" + } + ] +} +``` diff --git a/docs/common-workflows/analytics/question-with-bot-routing-api/ask-question-to-bots-in-the-application.md b/docs/common-workflows/analytics/question-with-bot-routing-api/ask-question-to-bots-in-the-application.md index 2c3be7ff..7d4fe4f6 100644 --- a/docs/common-workflows/analytics/question-with-bot-routing-api/ask-question-to-bots-in-the-application.md +++ b/docs/common-workflows/analytics/question-with-bot-routing-api/ask-question-to-bots-in-the-application.md @@ -16,7 +16,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Ask a question with bot routing -Endpoint: [POST /api/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/createQuestion) +Endpoint: [POST /api/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Next-Gen%20AI/createQuestion) Sample Request Headers: diff --git a/docs/common-workflows/analytics/question-with-bot-routing-api/get-image-of-answer.md b/docs/common-workflows/analytics/question-with-bot-routing-api/get-image-of-answer.md index 4eef3efd..3b5b3997 100644 --- a/docs/common-workflows/analytics/question-with-bot-routing-api/get-image-of-answer.md +++ b/docs/common-workflows/analytics/question-with-bot-routing-api/get-image-of-answer.md @@ -16,7 +16,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Get an image of an answer related to a question with bot routing -Endpoint: [GET /api/questions/\{questionsId}/answers/images/\{imageId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/getMessageImage) +Endpoint: [GET /api/questions/\{questionsId}/answers/images/\{imageId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/getMessageImage) :::note Replace `{questionsId}` in `GET /api/questions/{questionsId}/answers/images/{imageId}` with the question ID from `POST /api/questions` and `{imageId}` with your image ID from `GET /api/questions/{questionId}`. diff --git a/docs/common-workflows/analytics/question-with-bot-routing-api/get-question-from-bots-in-the-application.md b/docs/common-workflows/analytics/question-with-bot-routing-api/get-question-from-bots-in-the-application.md index fd7a25d9..56fda8e7 100644 --- a/docs/common-workflows/analytics/question-with-bot-routing-api/get-question-from-bots-in-the-application.md +++ b/docs/common-workflows/analytics/question-with-bot-routing-api/get-question-from-bots-in-the-application.md @@ -16,7 +16,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Get a question with bot routing -Endpoint: [GET /api/questions/\{questionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/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`. diff --git a/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-question.md b/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-question.md index 66fe137c..b8520f97 100644 --- a/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-question.md +++ b/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-question.md @@ -28,7 +28,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Ask the bot instance a question -Endpoint: [POST /api/bots/\{botId}/instances/\{instanceId}/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/postQuestion) +Endpoint: [POST /api/bots/\{botId}/instances/\{instanceId}/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/postQuestion) :::note Replace `{botId}` in `POST /api/bots/{botId}/instances/{instanceId}/questions` with the chatbot ID and `{instanceId}` with your bot instance ID created with `POST /api/bots/{botId}/instances` in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-suggested-question.md b/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-suggested-question.md index 904cf555..0f5118f2 100644 --- a/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-suggested-question.md +++ b/docs/common-workflows/analytics/use-bot-api/ask-bot-instance-suggested-question.md @@ -28,7 +28,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Ask a bot instance for suggested questions -Endpoint: [POST /api/bots/\{botId}/instances/\{instanceId}/suggestions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/createSuggestions) +Endpoint: [POST /api/bots/\{botId}/instances/\{instanceId}/suggestions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/createSuggestions) :::note Replace `{botId}` in `POST /api/bots/{botId}/instances/{instanceId}/suggestions` with the chatbot ID and `{instanceId}` with your bot instance ID created with `POST /api/bots/{botId}/instances` in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/create-a-bot-instance.md b/docs/common-workflows/analytics/use-bot-api/create-a-bot-instance.md index aa69f6fb..952ca77e 100644 --- a/docs/common-workflows/analytics/use-bot-api/create-a-bot-instance.md +++ b/docs/common-workflows/analytics/use-bot-api/create-a-bot-instance.md @@ -28,7 +28,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Create a bot instance -Endpoint: [POST /api/bots/\{botId}/instances](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/createInstance) +Endpoint: [POST /api/bots/\{botId}/instances](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/createInstance) :::note Replace `{botId}` in `POST /api/bots/{botId}/instances` with the chatbot ID in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/delete-a-bot-instance.md b/docs/common-workflows/analytics/use-bot-api/delete-a-bot-instance.md index fc771a59..0b754ebd 100644 --- a/docs/common-workflows/analytics/use-bot-api/delete-a-bot-instance.md +++ b/docs/common-workflows/analytics/use-bot-api/delete-a-bot-instance.md @@ -32,7 +32,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Delete a bot instance -Endpoint: [DELETE /api/bots/\{botId}/instances/\{instanceId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/deleteInstance) +Endpoint: [DELETE /api/bots/\{botId}/instances/\{instanceId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/deleteInstance) :::note Replace `{botId}` in `DELETE /api/bots/{botId}/instances/{instanceId}` with the chatbot ID and `{instanceId}` with your bot instance ID created with `POST /api/bots/{botId}/instances` in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/get-a-bot-question.md b/docs/common-workflows/analytics/use-bot-api/get-a-bot-question.md index e9e45a7a..52d3a1d2 100644 --- a/docs/common-workflows/analytics/use-bot-api/get-a-bot-question.md +++ b/docs/common-workflows/analytics/use-bot-api/get-a-bot-question.md @@ -24,7 +24,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Get a chat bot's question -Endpoint: [GET /api/bots/\{botId}/questions/\{questionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/queryMessage) +Endpoint: [GET /api/bots/\{botId}/questions/\{questionId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/queryMessage) :::note Replace `{botId}` in `GET /api/bots/{botId}/questions/{questionId}` with the chatbot ID and `{questionId}` with your question ID in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/get-bot-configuration.md b/docs/common-workflows/analytics/use-bot-api/get-bot-configuration.md index fd33b984..1d94d703 100644 --- a/docs/common-workflows/analytics/use-bot-api/get-bot-configuration.md +++ b/docs/common-workflows/analytics/use-bot-api/get-bot-configuration.md @@ -16,7 +16,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Get a chat bot's configuration -Endpoint: [GET /api/bots/\{botId}/configuration](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/getConfiguration) +Endpoint: [GET /api/bots/\{botId}/configuration](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/getConfiguration) :::note Replace `{botId}` in `GET /api/bots/{botId}/configuration` with the chatbot ID and `{questionId}` with your question ID in your environment. diff --git a/docs/common-workflows/analytics/use-bot-api/get-bot-question-list.md b/docs/common-workflows/analytics/use-bot-api/get-bot-question-list.md index 1582e043..b955e9b1 100644 --- a/docs/common-workflows/analytics/use-bot-api/get-bot-question-list.md +++ b/docs/common-workflows/analytics/use-bot-api/get-bot-question-list.md @@ -16,7 +16,7 @@ Obtain the authorization token needed to execute the request using [POST /api/au ## Get a chat bot's question list -Endpoint: [GET /api/bots/\{botId}/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/AI%20Chatbot/queryMessages) +Endpoint: [GET /api/bots/\{botId}/questions](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Auto%20Bots%20/queryMessages) :::note Replace `{botId}` in `GET /api/bots/{botId}/questions` with the chatbot ID in your environment. diff --git a/docs/getting-started/getting-started.md b/docs/getting-started/getting-started.md index e9605c6e..75c92985 100644 --- a/docs/getting-started/getting-started.md +++ b/docs/getting-started/getting-started.md @@ -8,7 +8,8 @@ To get started, view the following topics to know the basics of the Strategy RES - [REST API architecture](rest-api-architecture.md) - [REST API families](rest-api-families.md) -After learning the basics, view the following topics to understand some general topics that apply to the REST API: +After learning the basics, view the following topics to understand some general topics that apply to +the REST API: - [Authentication](authentication.md) - [Configure clustered environments](configure-clustered-environments.md) @@ -21,4 +22,10 @@ You can use the REST API Explorer and Playground as tools to learn more and run - [Strategy REST API Explorer](microstrategy-rest-api-explorer.md) - [Strategy REST API Playground](playground.md) -For more specific REST API topics, view the [common workflows](../common-workflows/common-workflows.md). +For more specific REST API topics, view the +[common workflows](../common-workflows/common-workflows.md). + +As newly introduced, Strategy Library now supports OAuth2 authorization for accessing the Strategy +Library API, which can simplify API usage: + +- [Using REST API with OAuth2](oauth2.md) diff --git a/docs/getting-started/oauth2.md b/docs/getting-started/oauth2.md new file mode 100644 index 00000000..ae460c60 --- /dev/null +++ b/docs/getting-started/oauth2.md @@ -0,0 +1,80 @@ +--- +title: Using REST API with OAuth2 +description: + Learn how to implement OAuth2 authentication with Strategy REST API for secure and scalable + client-server communication. +--- + +## Overview + +Strategy's OAuth2 authentication provides a modern, secure, and standardized way for clients to +authenticate with the Library server. This implementation follows industry best practices and +simplifies the authentication process across different client applications. + +## Why OAuth2? + +### What is OAuth2? + +OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It enables +secure delegation of access to resources on behalf of a user without sharing their credentials. +OAuth2 is widely adopted for its flexibility, scalability, and ability to support various use cases, +such as single sign-on (SSO), third-party integrations, and API access. + +At its core, OAuth2 operates through the exchange of tokens, which represent a user's authorization +to access specific resources. These tokens are issued by an authorization server and can be used by +client applications to interact with resource servers securely. + +### Why Using OAuth2? + +The traditional authentication methods required clients to implement multiple authentication modes +separately (standard mode, SAML, OIDC), each with its own API calls and cookie management. This +approach became increasingly complex as the number of clients grew, especially with integrations +like Tableau, PowerBI, and Google plugins. + +One of the most significant limitations of the previous authentication system was its heavy reliance +on cookies. Every API request required maintaining and managing cookie headers, which introduced +several challenges: + +- Session stickiness requirements +- Cross-Site Request Forgery (CSRF) vulnerabilities +- Complex cookie management across different domains +- Limited scalability in distributed systems + +The new OAuth2-based authentication mechanism offers several key advantages: + +1. **Unified Authentication Flow**: All clients and third-party integrations can use a single, + standardized method to authenticate with the Library server, regardless of the authentication + mode configured on the server. +1. **Improved Security**: Replaces cookie-based authentication with secure token-based + authentication, eliminating CSRF risks and session stickiness requirements. +1. **Better Scalability**: Follows modern security best practices for distributed systems by using + stateless token-based authentication instead of stateful cookie-based sessions. + +## How to Use OAuth2 + +### Configure OAuth2 + +Please refer to [Configure OAuth 2.0 to log in to Library](https://www2.microstrategy.com/producthelp/Current/Workstation/en-us/Content/config_oauth2.htm) + +### API Access + +1. Firstly, we should implement the OAuth2 Authorization Workflow against the Authorization Endpoint + (`oauth2/authorize`) and Token Endpoint (`oauth2/token`) to get a valid Access Token + +1. Then the following Rest API calls will only require puting this Access Token in the Authorization + Header (`X-MSTR-AuthToken`) + +1. If the client doesn't want require User Login for a certain time, it can also persist a Refresh + Token locally which can be used to refresh the Access Token later. + +### Sample Projects + +We provide a comprehensive +[OAuth2 Extension Sample](https://github.com/MicroStrategy/rest-api-samples) that demonstrates how +to implement OAuth2 authentication with Strategy REST API. This sample includes: + +- Complete authentication flow implementation +- Token management examples +- Test API with Access Token +- Best practices for secure token storage +- Error handling and session management diff --git a/docs/whats-new.md b/docs/whats-new.md index 4e7b854e..f31bb7b8 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -4,6 +4,15 @@ sidebar_label: What's new Description: What's New in the REST API. --- +## Strategy ONE (June 2025) + +- [Next-Gen AI Image Support](common-workflows/analytics/auto-bot-api/auto-bot-api.md). Request and retrieve images in answer from Next-Gen AI. +- [Project Duplication](common-workflows/administration/project-duplication/project-duplication.md). Duplicate a project within the same environment. + +## Strategy ONE (March 2025) + +- [Next-Gen AI](common-workflows/analytics/auto-bot-api/auto-bot-api.md). Ask questions, retrieve answers, get historical chat messages and suggested questions from Next-Gen AI. + ## MicroStrategy ONE (September 2024) - [Managing bookmarks](common-workflows/administration/manage-bookmarks/manage-bookmarks.md). Retrieve, create, update, and delete bookmarks. diff --git a/sidebars.js b/sidebars.js index 3fc93108..98b1eef7 100644 --- a/sidebars.js +++ b/sidebars.js @@ -47,6 +47,7 @@ const sidebars = { "getting-started/microstrategy-rest-api-explorer", "getting-started/playground", "getting-started/embedding-sdk", + "getting-started/oauth2", ], }, { @@ -409,13 +410,28 @@ const sidebars = { "common-workflows/analytics/manage-insights/update-insight-status", ], }, + { + type: "category", + link: { + type: "doc", + id: "common-workflows/analytics/auto-bot-api/auto-bot-api", + }, + label: "Next-Gen AI", + items: [ + "common-workflows/analytics/auto-bot-api/post-question", + "common-workflows/analytics/auto-bot-api/get-question-by-id", + "common-workflows/analytics/auto-bot-api/get-questions-by-bot", + "common-workflows/analytics/auto-bot-api/post-suggestion", + "common-workflows/analytics/auto-bot-api/get-image-of-answer", + ], + }, { type: "category", link: { type: "doc", id: "common-workflows/analytics/use-bot-api/use-bot-api", }, - label: "Bot APIs", + label: "Bot APIs ", items: [ "common-workflows/analytics/use-bot-api/get-bot-configuration", "common-workflows/analytics/use-bot-api/get-bot-question-list", @@ -432,7 +448,7 @@ const sidebars = { type: "doc", id: "common-workflows/analytics/question-with-bot-routing-api/question-api", }, - label: "Question with Bot Routing APIs", + label: "Question with Bot Routing APIs ", items: [ "common-workflows/analytics/question-with-bot-routing-api/ask-question-to-bots-in-the-application", "common-workflows/analytics/question-with-bot-routing-api/get-question-from-bots-in-the-application", @@ -1056,6 +1072,15 @@ const sidebars = { "common-workflows/administration/manage-bookmarks/get-bookmarks/get-bookmarks", ], }, + { + type: "category", + link: { + type: "doc", + id: "common-workflows/administration/project-duplication/project-duplication", + }, + label: "Project Duplication", + items: ["common-workflows/administration/project-duplication/project-duplication"], + }, ], }, ],