Skip to main content

Manage project settings

Available since 2021
tip

You can try out this workflow at REST API Playground.

Learn more about MicroStrategy REST API Playground here.

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.

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.

tip

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.

tip

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.

tip

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.

tip

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 /api/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)