Create a new environment

Creates a new environment.

Endpoint

/api/cluster/v2/environments

Parameter

Parameter	Type	Description	In	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	Environment	The JSON body of the request. The body must not provide an ID as it will be automatically assigned by the Dynatrace server.	body	optional

Body format

Request parametersJSON model

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. The element can hold these values 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
quotas	EnvironmentQuotas		optional
storage	EnvironmentStorage		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	Required
transactionStorage	TransactionStorage	optional
sessionReplayStorage	SessionReplayStorage	optional
symbolFilesFromMobileApps	SymbolFilesFromMobileApps	optional
logMonitoringStorage	LogMonitoringStorage	optional
serviceRequestLevelRetention	ServiceRequestLevelRetention	optional
serviceCodeLevelRetention	ServiceCodeLevelRetention	optional
realUserMonitoringRetention	RealUserMonitoringRetention	optional
syntheticMonitoringRetention	SyntheticMonitoringRetention	optional
sessionReplayRetention	SessionReplayRetention	optional
logMonitoringRetention	LogMonitoringRetention	optional
userActionsPerMinute	UserActionsPerMinute	optional
transactionTrafficQuota	TransactionTrafficQuota	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

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

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

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

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

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

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

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

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

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
maxLimit	integer	Maximum storage limit [bytes]	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
maxLimit	integer	Maximum storage limit [bytes]	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	Required
hostUnits	HostUnitQuota	optional
demUnits	DemUnitsQuota	optional
userSessions	UserSessionsQuota	optional
sessionProperties	SessionPropertiesQuota	optional
syntheticMonitors	SyntheticQuota	optional
customMetrics	CustomMetricsQuota	optional
davisDataUnits	DavisDataUnitsQuota	optional
logMonitoring	LogMonitoringQuota	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
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 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
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
maxLimit	integer	Concurrent environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.	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
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 SessionPropertiesQuota object

User session properties consumption information on environment level.

Element	Type	Description	Required

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

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
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 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
maxLimit	integer	Concurrent environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.	optional

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	Description
201	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

Response parametersJSON model

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

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

Example

Creates and enables an environment called MyNewTeam with a token with scopes apiTokens.read and apiTokens.write (for use with Tokens API v2) and TenantTokenManagement (for use with Tokens API v1)

Curl

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}

Request URL

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

Request body

{
  "name": "MyNewTeam",
  "state": "ENABLED",
  "tags": [
    "owner:john.wicked@dynatrace.com",
    "department:finance"
  ],
  "trial": false
}

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.

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

Response code

201