Version 2021

Manage Project Settings

A high-level workflow sample for managing project settings is shown below. The sequence of REST API requests in the following procedure allows an administrative user to manage the project settings.

  1. Log in

  2. Get the project setting configurations

  3. Get the project setting values for a specific project

  4. Update a part of the project setting values for a specific project

  5. Update all project setting values for a specific project

  6. Log out

Log In

Endpoint: POST /api/auth/login

This endpoint allows the user to authenticate with the MicroStrategy REST Server. You can provide the information used to create the session in the body of the request. In this example, you can use standard authentication, so you need to provide the username and password. If the call is successful, the resulting response returns a status code of 204 and a response header containing X-MSTR-AuthToken. This authorization token is used by all subsequent requests.

In the following example, standard authentication uses a username of administrator and a blank password.

Sample Request

Request Body:

{ 
 "username": "administrator",
 "password": "yourPassword"
}

Curl:

curl -X POST "https://demo.microstrategy.com/MicroStrategyLibrary/api/auth/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"username\":\"administrator\",\"password\":\"yourPassword\"}"

Sample Response

Response Header:

cache-control: no-cache, no-store, max-age=0, must-revalidate 
 date: Mon, 28 Oct 2019 17:38:15 GMT 
 expires: 0 
 pragma: no-cache 
 x-mstr-authtoken: f34qc7evsntsks0qe6hfcgt0ur

Response Code: 204 (Success: No Content)

Get the Project Setting Configurations

Endpoint: GET /api/v2/projects/{projectId}/settings/config

This endpoint allows the user to retrieve information on all project settings that are available in MicroStrategy REST API. The information includes the setting description, type, options, unit, minimum value, maximum value, and reboot rule. You must specify an authorization token in the request header, which can be obtained from POST /api/auth/login during login.

This operation requires the Web User privilege.

Sample Request

Request Parameter:

X-MSTR-AuthToken

The authorization token generated by POST /api/auth/login.

Curl:

curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/projects/{projectId}/settings/config" -H "accept: application/json" -H "X-MSTR-AuthToken: hhl9cvevf3gqcvjadojen0p45j"

Sample Response

Response Body:

The following sample is part of the complete response body.

{
  "maxReportResultRowCount": {
    "description": "Maximum report result rows",
    "type": "number",
    "max_value": 999999999,
    "min_value": 0,
    "options": [
      {
        "name": "No Limit",
        "value": -1
      }
    ]
  },
  "maxReportExecutionTime": {
    "description": "Maximum report execution time for interactive reports (sec)",
    "type": "number",
    "max_value": 999999,
    "min_value": 0,
    "options": [
      {
        "name": "No Limit",
        "value": -1
      }
    ]
  },
  "maxJobPerUserAccount": {
    "description": "Maximum jobs per user account",
    "type": "number",
    "max_value": 999999,
    "min_value": 0,
    "options": [
      {
        "name": "No Limit",
        "value": -1
      }
    ]
  },
  ...
}

Response Code: 200 (Success: OK)

Get the Setting Values for a Specific Project

Endpoint: GET /api/v2/projects/{projectId}/settings

This endpoint allows you to retrieve all project setting values that are available in MicroStrategy REST API. You must specify an authorization token in the request header, which can be obtained from POST /api/auth/login during login.

This operation requires the Web User privilege.

Sample Request

Request Parameter:

  • X-MSTR-AuthToken

    The authorization token generated by POST /api/auth/login.

  • projectId

    The ID of the project.

Curl:

curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/projects/{projectId}/settings" -H "accept: application/json" -H "X-MSTR-AuthToken: ks6ehab41hkleoj03qvamq3bk4"

Sample Response

Response Body:

The following sample is part of the complete response body.

{
  "enableDeleteObjectDependencies": {
    "value": false
  },
  "appendInfoForEmailDelivery": {
    "value": [
      "recipient_name",
      "owner_name",
      "report_document_name",
      "project_name",
      "delivery_method",
      "schedule",
      "subscription_name",
      "delivery_status",
      "date",
      "time",
      "email_address",
      "error_message"
    ]
  },
  "cacheEncryptionLevel": {
    "value": 0
  },
  "maxEmailSubscriptionCount": {
    "value": -1
  },
  ...
}

Response Code: 200 (Success: OK)

Update a Part of the Setting Values for a Specific Project

Endpoint: PATCH /api/v2/projects/{projectId}/settings

This endpoint allows you to modify part of the project settings exposed in REST API via GET /api/v2/projects/{projectId}/settings/config. You must specify an authorization token in the request header, which can be obtained from POST /api/auth/login during login.

Depending on the setting you are modifying, the response body will tell you which privilege is required for the operation.

Sample Request

Request Parameter:

  • X-MSTR-AuthToken

    The authorization token generated by POST /api/auth/login.

  • projectId

    The ID of the project.

Request Body:

{
  "enableDeleteObjectDependencies": {
    "value": true
  },
  "cacheEncryptionLevel": {
    "value": 1
  },
  "maxEmailSubscriptionCount": {
    "value": 200
  }
}

Curl:

curl -X PATCH "https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/projects/{projectId}/settings" -H "accept: application/json" -H "X-MSTR-AuthToken: b3q75vgt84er8ektbvhbpt9qoh" -H "Content-Type: application/json" -d "{\"enableDeleteObjectDependencies\":{\"value\":true},\"cacheEncryptionLevel\":{\"value\":1},\"maxEmailSubscriptionCount\":{\"value\":200}}"

Sample Response

Response Body:

The following sample is part of the complete response body. A complete list of project setting values with the modified values should be returned.

{
  "enableDeleteObjectDependencies": {
    "value": true
  },
  "appendInfoForEmailDelivery": {
    "value": [
      "recipient_name",
      "owner_name",
      "report_document_name",
      "project_name",
      "delivery_method",
      "schedule",
      "subscription_name",
      "delivery_status",
      "date",
      "time",
      "email_address",
      "error_message"
    ]
  },
  "cacheEncryptionLevel": {
    "value": 1
  },
  "maxEmailSubscriptionCount": {
    "value": 200
  },
  ...
}

Response Code: 200 (Success: OK)

Update All Project Setting Values

Endpoint: PUT /api/v2/projects/{projectId}/settings

This endpoint allows you to access all of the setting values that are available in MicroStrategy REST API. In this endpoint, you must provide a complete list of project settings, which is the different from the PATCH /api/v2/projects/{projectId}/settings endpoint. You can find a list of project settings exposed in REST API via GET /api/v2/projects/{projectId}/settings/config. You must specify an authorization token in the request header, which can be obtained from POST /api/auth/login during login.

This operation requires the following privileges:

  • Web User
  • Configure Server Basic
  • Configure Caches
  • Configure Subscription Setting
  • Configure Governing
  • Configure Project Basic
  • Configure Statistics
  • Configure History Lists

Sample Request

Request Parameter:

  • X-MSTR-AuthToken

    The authorization token generated by POST /api/auth/login.

  • projectId

    The ID of the project.

Request Body:

The following sample is part of the complete request body. The complete request body must contain all project settings.

{
  "enableDeleteObjectDependencies": {
    "value": true
  },
  "appendInfoForEmailDelivery": {
    "value": [
      "recipient_name",
      "owner_name",
      "report_document_name",
      "project_name",
      "delivery_method",
      "schedule",
     "subscription_name",
      "delivery_status",
      "date",
      "time",
      "email_address",
      "error_message"
    ]
  },
  "cacheEncryptionLevel": {
    "value": 1
  },
  "maxEmailSubscriptionCount": {
    "value": 200
  },
  ...
}

Curl:

curl -X PUT "https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/projects/{projectId}/settings" -H "accept: application/json" -H "X-MSTR-AuthToken: 9kdr8gbhtt60crk0mulbma4msp" -H "Content-Type: application/json" -d "{\"enableDeleteObjectDependencies\":{\"value\":true},\"appendInfoForEmailDelivery\":{\"value\":[\"recipient_name\",\"owner_name\",\"report_document_name\",\"project_name\",\"delivery_method\",\"schedule\",\"subscription_name\",\"delivery_status\",\"date\",\"time\",\"email_address\",\"error_message\"]},\"cacheEncryptionLevel\":{\"value\":1},\"maxEmailSubscriptionCount\":{\"value\":200},...}"

Sample Response

Response Body:

The following sample is part of the complete response body. A complete list of project setting values with the modified values should be returned.

{
  "enableDeleteObjectDependencies": {
    "value": true
  },
  "appendInfoForEmailDelivery": {
    "value": [
      "recipient_name",
      "owner_name",
      "report_document_name",
      "project_name",
      "delivery_method",
      "schedule",
      "subscription_name",
      "delivery_status",
      "date",
      "time",
      "email_address",
      "error_message"
    ]
  },
  "cacheEncryptionLevel": {
    "value": 1
  },
  "maxEmailSubscriptionCount": {
    "value": 200
  },
  ...
}

Response Code: 200 (Success: OK)

Log Out

Endpoint: POST /api/auth/logout

This endpoint allows the caller to log out the authenticated user from the MicroStrategy REST server. In this example, you close the active user session by providing the X-MSTR-AuthToken authorization token, which is generated by POST /auth/login. If the call is successful, the resulting response returns a status code of 204.

Sample Request

Curl:

curl -X POST "https:// demo.microstrategy.com/MicroStrategyLibrary/api/auth/logout" -H "accept: application/json" -H "X-MSTR-AuthToken: c8afkjurl1r9qk2k7puj2hs9cu"

Sample Response

Response Code: 204 (Accepted)