• Home
  • Setup and configuration
  • Dynatrace Managed
  • Cluster API
  • Cluster API v2
  • Environments
  • Create a new environment

Create a new environment

This API call creates a new environment.

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

ParameterTypeDescriptionInRequired
createTokenboolean

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.

queryoptional
bodyEnvironment

The JSON body of the request. The body must not provide an ID as it will be automatically assigned by the Dynatrace server.

bodyrequired

Request body objects

The Environment object

Basic configuration for an environment.

ElementTypeDescription
namestring

The display name of the environment.

idstring

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

Can be null.

trialboolean

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).

Can be null.

statestring

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

The element can hold these values
  • DISABLED
  • ENABLED

Can be null.

tagsstring[]

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

Can be null.

creationDatestring

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

Can be null.

quotasEnvironmentQuotas

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.

Can be null.

storageEnvironmentStorage

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.

Can be null.

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.

ElementTypeDescription
hostUnitsHostUnitQuota

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

Can be null.

demUnitsDemUnitsQuota

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.

Can be null.

userSessionsUserSessionsQuota

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

Can be null.

sessionPropertiesSessionPropertiesQuota

User session properties consumption information on environment level.

Can be null.

syntheticMonitorsSyntheticQuota

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.

Can be null.

customMetricsCustomMetricsQuota

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.

Can be null.

davisDataUnitsDavisDataUnitsQuota

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.

Can be null.

logMonitoringLogMonitoringQuota

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.

Can be null.

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.

ElementTypeDescription
currentUsagenumber

Current environment usage.

Can be null.

maxLimitinteger

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

Can be null.

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.

ElementTypeDescription
consumedThisMonthnumber

Monthly environment consumption. Resets each calendar month.

Can be null.

consumedThisYearnumber

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

Can be null.

monthlyLimitinteger

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

Can be null.

annualLimitinteger

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

Can be null.

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.

ElementTypeDescription
consumedUserSessionsWithMobileSessionReplayThisYearnumber

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

Can be null.

consumedUserSessionsWithWebSessionReplayThisMonthnumber

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

Can be null.

consumedUserSessionsWithMobileSessionReplayThisMonthnumber

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

Can be null.

totalAnnualLimitinteger

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

Can be null.

totalConsumedThisMonthnumber

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

Can be null.

totalConsumedThisYearnumber

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

Can be null.

totalMonthlyLimitinteger

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

Can be null.

consumedUserSessionsWithWebSessionReplayThisYearnumber

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

Can be null.

consumedMobileSessionsThisMonthnumber

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

Can be null.

consumedMobileSessionsThisYearnumber

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

Can be null.

The SessionPropertiesQuota object

User session properties consumption information on environment level.

ElementTypeDescription
consumedThisMonthnumber

Monthly environment consumption. Resets each calendar month.

Can be null.

consumedThisYearnumber

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

Can be null.

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.

ElementTypeDescription
consumedThisMonthnumber

Monthly environment consumption. Resets each calendar month.

Can be null.

consumedThisYearnumber

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

Can be null.

monthlyLimitinteger

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

Can be null.

annualLimitinteger

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

Can be null.

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.

ElementTypeDescription
currentUsagenumber

Current environment usage.

Can be null.

maxLimitinteger

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

Can be null.

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.

ElementTypeDescription
consumedThisMonthnumber

Monthly environment consumption. Resets each calendar month.

Can be null.

consumedThisYearnumber

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

Can be null.

monthlyLimitinteger

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

Can be null.

annualLimitinteger

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

Can be null.

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.

ElementTypeDescription
consumedThisMonthnumber

Monthly environment consumption. Resets each calendar month.

Can be null.

consumedThisYearnumber

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

Can be null.

monthlyLimitinteger

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

Can be null.

annualLimitinteger

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

Can be null.

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.

ElementTypeDescription
transactionStorageTransactionStorage

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

Can be null.

sessionReplayStorageSessionReplayStorage

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

Can be null.

symbolFilesFromMobileAppsSymbolFilesFromMobileApps

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.

Can be null.

logMonitoringStorageLogMonitoringStorage

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.

Can be null.

serviceRequestLevelRetentionServiceRequestLevelRetention

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.

Can be null.

serviceCodeLevelRetentionServiceCodeLevelRetention

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.

Can be null.

realUserMonitoringRetentionRealUserMonitoringRetention

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.

Can be null.

syntheticMonitoringRetentionSyntheticMonitoringRetention

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.

Can be null.

sessionReplayRetentionSessionReplayRetention

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.

Can be null.

logMonitoringRetentionLogMonitoringRetention

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.

Can be null.

userActionsPerMinuteUserActionsPerMinute

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.

Can be null.

transactionTrafficQuotaTransactionTrafficQuota

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.

Can be null.

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.

ElementTypeDescription
retentionReductionPercentagestring

Percentage of truncation for new data.

Can be null.

retentionReductionReasonstring

Reason of truncation.

Can be null.

maxLimitinteger

Maximum storage limit [bytes]

Can be null.

currentlyUsedinteger

Currently used storage [bytes]

Can be null.

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.

ElementTypeDescription
retentionReductionPercentagestring

Percentage of truncation for new data.

Can be null.

retentionReductionReasonstring

Reason of truncation.

Can be null.

maxLimitinteger

Maximum storage limit [bytes]

Can be null.

currentlyUsedinteger

Currently used storage [bytes]

Can be null.

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.

ElementTypeDescription
maxLimitinteger

Maximum storage limit [bytes]

Can be null.

currentlyUsedinteger

Currently used storage [bytes]

Can be null.

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.

ElementTypeDescription
maxLimitinteger

Maximum storage limit [bytes]

Can be null.

currentlyUsedinteger

Currently used storage [bytes]

Can be null.

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.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

Can be null.

currentlyUsedInMillisinteger

Current data age [milliseconds]

Can be null.

currentlyUsedInDaysinteger

Current data age [days]

Can be null.

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.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

Can be null.

currentlyUsedInMillisinteger

Current data age [milliseconds]

Can be null.

currentlyUsedInDaysinteger

Current data age [days]

Can be null.

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.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

Can be null.

currentlyUsedInMillisinteger

Current data age [milliseconds]

Can be null.

currentlyUsedInDaysinteger

Current data age [days]

Can be null.

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.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

Can be null.

currentlyUsedInMillisinteger

Current data age [milliseconds]

Can be null.

currentlyUsedInDaysinteger

Current data age [days]

Can be null.

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.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

Can be null.

currentlyUsedInMillisinteger

Current data age [milliseconds]

Can be null.

currentlyUsedInDaysinteger

Current data age [days]

Can be null.

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.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

Can be null.

currentlyUsedInMillisinteger

Current data age [milliseconds]

Can be null.

currentlyUsedInDaysinteger

Current data age [days]

Can be null.

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.

ElementTypeDescription
maxLimitinteger

Maximum traffic [units per minute]

Can be null.

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.

ElementTypeDescription
maxLimitinteger

Maximum traffic [units per minute]

Can be null.

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.

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

Response

Response codes

CodeTypeDescription
201EnvironmentShortRepresentation

Success. The environment has been created and started. The response body contains the generated ID of the environment and a token with the scopes 'apiTokens.read' and 'apiTokens.write' (for usage with token API v2) and 'TenantTokenManagement'. The location header contains the generated ID as well.

400-

Failed. The input is invalid.

Response body objects

The EnvironmentShortRepresentation object

The short representation of an environment.

ElementTypeDescription
idstring

The ID of the Dynatrace entity.

namestring

The name of the Dynatrace entity.

Can be null.

descriptionstring

A short description of the Dynatrace entity.

Can be null.

tokenManagementTokenstring

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'.

Can be null.

Response body JSON model

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

Example

Creates an environment called MyNewTeam specifying details on license quota, storage limits and data retention.

Curl

shell
curl -X POST "https://myManaged.cluster.com/api/cluster/v2/environments?createToken=true" -H "accept: application/json; charset=utf-8" -H "Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890" -H "Content-Type: application/json; charset=utf-8" -d "{\"name\":\"MyNewTeam\",\"state\":\"ENABLED\",\"tags\":[\"owner:john.wicked@dynatrace.com\",\"department:finance\"],\"trial\":false}, \"quotas\":{\"hostUnits\":{\"maxLimit\":1},\"demUnits\":{\"monthlyLimit\":1,\"annualLimit\":1},\"userSessions\":{\"totalMonthlyLimit\":1,\"totalAnnualLimit\":2},\"syntheticMonitors\":{\"monthlyLimit\":1,\"annualLimit\":1},\"davisDataUnits\":{\"monthlyLimit\":1,\"annualLimit\":2}},\"storage\":{\"transactionStorage\":{\"maxLimit\":1024},\"sessionReplayStorage\":{\"maxLimit\":2048},\"symbolFilesFromMobileApps\":{\"maxLimit\":5050},\"serviceRequestLevelRetention\":{\"maxLimitInDays\":35},\"serviceCodeLevelRetention\":{\"maxLimitInDays\":10},\"realUserMonitoringRetention\":{\"maxLimitInDays\":35},\"syntheticMonitoringRetention\":{\"maxLimitInDays\":35},\"sessionReplayRetention\":{\"maxLimitInDays\":35},\"userActionsPerMinute\":{\"maxLimit\":3500},\"transactionTrafficQuota\":{\"maxLimit\":1000}}}"

Request URL

plaintext
https://myManaged.cluster.com/api/cluster/v2/environments?createToken=true

Request body

json
{ "name": "MyNewTeam", "state": "ENABLED", "tags": [ "owner:john.wicked@dynatrace.com", "department:finance" ], "trial": false, "quotas": { "hostUnits": { "maxLimit": 1 }, "demUnits": { "monthlyLimit": 1, "annualLimit": 1 }, "userSessions": { "totalMonthlyLimit": 1, "totalAnnualLimit": 2 }, "syntheticMonitors": { "monthlyLimit": 1, "annualLimit": 1 }, "davisDataUnits": { "monthlyLimit": 1, "annualLimit": 2 } }, "storage": { "transactionStorage": { "maxLimit": 1024 }, "sessionReplayStorage": { "maxLimit": 2048 }, "symbolFilesFromMobileApps": { "maxLimit": 5050 }, "serviceRequestLevelRetention": { "maxLimitInDays": 35 }, "serviceCodeLevelRetention": { "maxLimitInDays": 10 }, "realUserMonitoringRetention": { "maxLimitInDays": 35 }, "syntheticMonitoringRetention": { "maxLimitInDays": 35 }, "sessionReplayRetention": { "maxLimitInDays": 35 }, "userActionsPerMinute": { "maxLimit": 3500 }, "transactionTrafficQuota": { "maxLimit": 1000 } } }

Response body

Success. The environment has been created and started. The response body contains the generated ID of the environment and a token with the Token management permission. The location header contains the generated ID as well.

json
{ "id": "11a113a1-a11b-1234-123a-4df674c8eb8e", "name": "MyNewTeam", "tokenManagementToken": "dt0c01.LJMAHMWOKCL5IPH3E2ORNHTR.<token-value>" }

Response code

201