Update specific environment

This API call updates an existing environment or creates a new one.

Authentication

To execute this request, you need the Service Provider API (ServiceProviderAPI) permission assigned to your API token. Generate your API token via Cluster Management Console (CMC). To learn how to obtain and use it, see Cluster API - Authentication.

Endpoint

/api/cluster/v2/environments

Parameter

Parameter
Type
Description
In
Required
id
string

The ID of the environment to update.

If you set the ID in the body as well, it must match this ID.

path
required
createToken
boolean

If true, a token management token with the scopes 'apiTokens.read' and 'apiTokens.write' (for usage with token API v2) and 'TenantTokenManagement' (for usage with token API v1) is created when creating a new environment. This token is then returned in the response body. It can be used within the newly created environment to create other tokens for configuring this environment.

query
optional
body

JSON body of the request, containing updated parameters of the environment.

body
optional

Request body objects

The Environment object

Basic configuration for an environment.

Element
Type
Description
Required
name
string

The display name of the environment.

required
id
string

The ID of the environment. Has to match [a-zA-Z0-9_-]{1,70}

optional
trial
boolean

Specifies whether the environment is a trial environment or a non-trial environment. Creating a trial environment is only possible if your license allows that. The default value is false (non-trial).

optional
state
string

Indicates whether the environment is enabled or disabled. The default value is ENABLED.

  • DISABLED
  • ENABLED
optional
tags
string[]

A set of tags that are assigned to this environment. Every tag can have a maximum length of 100 characters.

optional
creationDate
string

The creation date of the environment in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

optional
quotas

Environment level consumption and quotas information. Only returned if includeConsumptionInfo or includeUncachedConsumptionInfo param is true. If skipped when editing via PUT method then already set quotas will remain.

optional
storage

Environment level storage usage and limit information. Not returned if includeStorageInfo param is not true. If skipped when editing via PUT method then already set limits will remain.

optional

The EnvironmentQuotas object

Environment level consumption and quotas information. Only returned if includeConsumptionInfo or includeUncachedConsumptionInfo param is true. If skipped when editing via PUT method then already set quotas will remain.

Element
Type
Description
Required
hostUnits

Host units consumption and quota information on environment level. If skipped when editing via PUT method then already set quota will remain.

optional
demUnits

DEM units consumption and quota information on environment level. Not set (and not editable) if DEM units is not enabled. If skipped when editing via PUT method then already set quotas will remain.

optional
userSessions

User sessions consumption and quota information on environment level. If skipped when editing via PUT method then already set quotas will remain.

optional
sessionProperties

User session properties consumption information on environment level.

optional
syntheticMonitors

Synthetic monitors consumption and quota information on environment level. Not set (and not editable) if neither Synthetic nor DEM units is enabled. If skipped when editing via PUT method then already set quotas will remain.

optional
customMetrics

Custom metrics consumption and quota information on environment level. Not set (and not editable) if Custom metrics is not enabled. Not set (and not editable) if Davis data units is enabled. If skipped when editing via PUT method then already set quota will remain.

optional
davisDataUnits

Davis data units consumption and quota information on environment level. Not set (and not editable) if Davis data units is not enabled. If skipped when editing via PUT method then already set quotas will remain.

optional
logMonitoring

Log monitoring consumption and quota information on environment level. Not set (and not editable) if Log monitoring is not enabled. Not set (and not editable) if Log monitoring is migrated to Davis data on license level. If skipped when editing via PUT method then already set quotas will remain.

optional

The HostUnitQuota object

Host units consumption and quota information on environment level. If skipped when editing via PUT method then already set quota will remain.

Element
Type
Description
Required
currentUsage
number

Current environment usage.

optional
maxLimit
integer

Concurrent environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional

The DemUnitsQuota object

DEM units consumption and quota information on environment level. Not set (and not editable) if DEM units is not enabled. If skipped when editing via PUT method then already set quotas will remain.

Element
Type
Description
Required
consumedThisMonth
number

Monthly environment consumption. Resets each calendar month.

optional
consumedThisYear
number

Yearly environment consumption. Resets each year on license creation date anniversary.

optional
monthlyLimit
integer

Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional
annualLimit
integer

Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional

The UserSessionsQuota object

User sessions consumption and quota information on environment level. If skipped when editing via PUT method then already set quotas will remain.

Element
Type
Description
Required
consumedUserSessionsWithMobileSessionReplayThisYear
number

Yearly Mobile user sessions with replay environment consumption. Resets each year on license creation date anniversary.

optional
consumedUserSessionsWithWebSessionReplayThisMonth
number

Monthly Web user sessions with replay environment consumption. Resets each calendar month.

optional
consumedUserSessionsWithMobileSessionReplayThisMonth
number

Monthly Mobile user sessions with replay environment consumption. Resets each calendar month.

optional
totalAnnualLimit
integer

Annual total User sessions environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional
totalConsumedThisMonth
number

Monthly total User sessions environment consumption. Resets each calendar month.

optional
totalConsumedThisYear
number

Yearly total User sessions environment consumption. Resets each year on license creation date anniversary.

optional
totalMonthlyLimit
integer

Monthly total User sessions environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional
consumedUserSessionsWithWebSessionReplayThisYear
number

Yearly Web user sessions with replay environment consumption. Resets each year on license creation date anniversary.

optional
consumedMobileSessionsThisMonth
number

Monthly Mobile user sessions environment consumption. Resets each calendar month.

optional
consumedMobileSessionsThisYear
number

Yearly Mobile user sessions environment consumption. Resets each year on license creation date anniversary.

optional

The SessionPropertiesQuota object

User session properties consumption information on environment level.

Element
Type
Description
Required
consumedThisMonth
number

Monthly environment consumption. Resets each calendar month.

optional
consumedThisYear
number

Yearly environment consumption. Resets each year on license creation date anniversary.

optional

The SyntheticQuota object

Synthetic monitors consumption and quota information on environment level. Not set (and not editable) if neither Synthetic nor DEM units is enabled. If skipped when editing via PUT method then already set quotas will remain.

Element
Type
Description
Required
consumedThisMonth
number

Monthly environment consumption. Resets each calendar month.

optional
consumedThisYear
number

Yearly environment consumption. Resets each year on license creation date anniversary.

optional
monthlyLimit
integer

Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional
annualLimit
integer

Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional

The CustomMetricsQuota object

Custom metrics consumption and quota information on environment level. Not set (and not editable) if Custom metrics is not enabled. Not set (and not editable) if Davis data units is enabled. If skipped when editing via PUT method then already set quota will remain.

Element
Type
Description
Required
currentUsage
number

Current environment usage.

optional
maxLimit
integer

Concurrent environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional

The DavisDataUnitsQuota object

Davis data units consumption and quota information on environment level. Not set (and not editable) if Davis data units is not enabled. If skipped when editing via PUT method then already set quotas will remain.

Element
Type
Description
Required
consumedThisMonth
number

Monthly environment consumption. Resets each calendar month.

optional
consumedThisYear
number

Yearly environment consumption. Resets each year on license creation date anniversary.

optional
monthlyLimit
integer

Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional
annualLimit
integer

Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional

The LogMonitoringQuota object

Log monitoring consumption and quota information on environment level. Not set (and not editable) if Log monitoring is not enabled. Not set (and not editable) if Log monitoring is migrated to Davis data on license level. If skipped when editing via PUT method then already set quotas will remain.

Element
Type
Description
Required
consumedThisMonth
number

Monthly environment consumption. Resets each calendar month.

optional
consumedThisYear
number

Yearly environment consumption. Resets each year on license creation date anniversary.

optional
monthlyLimit
integer

Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional
annualLimit
integer

Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

optional

The EnvironmentStorage object

Environment level storage usage and limit information. Not returned if includeStorageInfo param is not true. If skipped when editing via PUT method then already set limits will remain.

Element
Type
Description
Required
transactionStorage

Transaction storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

optional
sessionReplayStorage

Session replay storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

optional
symbolFilesFromMobileApps

Symbol files from mobile apps storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

optional
logMonitoringStorage

Log monitoring storage usage and limit information on environment level. Not editable when Log monitoring is not allowed by license or not configured on cluster level. If skipped when editing via PUT method then already set limit will remain.

optional
serviceRequestLevelRetention

Service request level retention settings on environment level. Service code level retention time can't be greater than service request level retention time and both can't exceed one year.If skipped when editing via PUT method then already set limit will remain.

optional
serviceCodeLevelRetention

Service code level retention settings on environment level. Service code level retention time can't be greater than service request level retention time and both can't exceed one year.If skipped when editing via PUT method then already set limit will remain.

optional
realUserMonitoringRetention

Real user monitoring retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

optional
syntheticMonitoringRetention

Synthetic monitoring retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

optional
sessionReplayRetention

Session replay retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

optional
logMonitoringRetention

Log monitoring retention settings on environment level. Not editable when Log monitoring is not allowed by license or not configured on cluster level. Can be set to any value from 5 to 90 days. If skipped when editing via PUT method then already set limit will remain.

optional
userActionsPerMinute

Maximum number of user actions generated per minute on environment level. Can be set to any value from 1 to 2147483646 or left unlimited. If skipped when editing via PUT method then already set limit will remain.

optional
transactionTrafficQuota

Maximum number of newly monitored entry point PurePaths captured per process/minute on environment level. Can be set to any value from 100 to 100000. If skipped when editing via PUT method then already set limit will remain.

optional

The TransactionStorage object

Transaction storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
retentionReductionPercentage
string

Percentage of truncation for new data.

optional
retentionReductionReason
string

Reason of truncation.

optional
maxLimit
integer

Maximum storage limit [bytes]

optional
currentlyUsed
integer

Currently used storage [bytes]

optional

The SessionReplayStorage object

Session replay storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
retentionReductionPercentage
string

Percentage of truncation for new data.

optional
retentionReductionReason
string

Reason of truncation.

optional
maxLimit
integer

Maximum storage limit [bytes]

optional
currentlyUsed
integer

Currently used storage [bytes]

optional

The SymbolFilesFromMobileApps object

Symbol files from mobile apps storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
maxLimit
integer

Maximum storage limit [bytes]

optional
currentlyUsed
integer

Currently used storage [bytes]

optional

The LogMonitoringStorage object

Log monitoring storage usage and limit information on environment level. Not editable when Log monitoring is not allowed by license or not configured on cluster level. If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
maxLimit
integer

Maximum storage limit [bytes]

optional
currentlyUsed
integer

Currently used storage [bytes]

optional

The ServiceRequestLevelRetention object

Service request level retention settings on environment level. Service code level retention time can't be greater than service request level retention time and both can't exceed one year.If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
maxLimitInDays
integer

Maximum retention limit [days]

optional
currentlyUsedInMillis
integer

Current data age [milliseconds]

optional
currentlyUsedInDays
integer

Current data age [days]

optional

The ServiceCodeLevelRetention object

Service code level retention settings on environment level. Service code level retention time can't be greater than service request level retention time and both can't exceed one year.If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
maxLimitInDays
integer

Maximum retention limit [days]

optional
currentlyUsedInMillis
integer

Current data age [milliseconds]

optional
currentlyUsedInDays
integer

Current data age [days]

optional

The RealUserMonitoringRetention object

Real user monitoring retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
maxLimitInDays
integer

Maximum retention limit [days]

optional
currentlyUsedInMillis
integer

Current data age [milliseconds]

optional
currentlyUsedInDays
integer

Current data age [days]

optional

The SyntheticMonitoringRetention object

Synthetic monitoring retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
maxLimitInDays
integer

Maximum retention limit [days]

optional
currentlyUsedInMillis
integer

Current data age [milliseconds]

optional
currentlyUsedInDays
integer

Current data age [days]

optional

The SessionReplayRetention object

Session replay retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
maxLimitInDays
integer

Maximum retention limit [days]

optional
currentlyUsedInMillis
integer

Current data age [milliseconds]

optional
currentlyUsedInDays
integer

Current data age [days]

optional

The LogMonitoringRetention object

Log monitoring retention settings on environment level. Not editable when Log monitoring is not allowed by license or not configured on cluster level. Can be set to any value from 5 to 90 days. If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
maxLimitInDays
integer

Maximum retention limit [days]

optional
currentlyUsedInMillis
integer

Current data age [milliseconds]

optional
currentlyUsedInDays
integer

Current data age [days]

optional

The UserActionsPerMinute object

Maximum number of user actions generated per minute on environment level. Can be set to any value from 1 to 2147483646 or left unlimited. If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
maxLimit
integer

Maximum traffic [units per minute]

optional

The TransactionTrafficQuota object

Maximum number of newly monitored entry point PurePaths captured per process/minute on environment level. Can be set to any value from 100 to 100000. If skipped when editing via PUT method then already set limit will remain.

Element
Type
Description
Required
maxLimit
integer

Maximum traffic [units per minute]

optional

Request body JSON model

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.

{
  "name": "example environment",
  "state": "ENABLED",
  "tags": [
    "tag1",
    "tag2"
  ],
  "trial": false
}

Response

Response codes

Code
Type
Description
201

Success. The new environment has been created. The response body contains the ID, the name and also a token management token if 'createToken' is 'true'.

204
-

Success. The environment has been updated. Response doesn't have a body.

400
-

Failed. The input is invalid.

Response body objects

The EnvironmentShortRepresentation object

The short representation of an environment.

Element
Type
Description
id
string

The ID of the Dynatrace entity.

name
string

The name of the Dynatrace entity.

description
string

A short description of the Dynatrace entity.

tokenManagementToken
string

A token with the 'Token management' permission. Can be used to within the newly created environment to create other tokens for configuring this environment. This value is only set if an environment was created with the query parameter 'createToken=true'.

Response body JSON model

{
  "id": "string",
  "name": "string",
  "description": "string",
  "tokenManagementToken": "string"
}

Example

Disables the environment with identifier 19a963a7-b19f-4382-964a-4df674c8eb8e.

Curl

curl -X PUT "https://myManaged.cluster.com/api/cluster/v2/environments/19a963a7-b19f-4382-964a-4df674c8eb8e?createToken=false" -H "accept: application/json; charset=utf-8" -H "Authorization: Api-Token fSRCdB7PQDSdFVANvNfSF" -H "Content-Type: application/json; charset=utf-8" -d "
{\"name\":\"MyNewTeam\",\"id\":\"19a963a7-b19f-4382-964a-4df674c8eb8e\",\"trial\":false,\"state\":\"DISABLED\",\"tags\":[\"owner:john.wicked@dynatrace.com\",\"department:finance\"]}

Request URL

https://myManaged.cluster.com/api/cluster/v2/environments/19a963a7-b19f-4382-964a-4df674c8eb8e?createToken=false

Request body

{
  "name": "MyNewTeam",
  "state": "DISABLED"
}

Response body

Response doesn't have a body.

Response code

204