Synthetic locations API v2 - POST a location

Reference

Creates a new private Synthetic location. For more details about Synthetic location creation, see Create a private Synthetic location.

The request consumes and produces an application/json payload.

POST	SaaS	`https://{your-environment-id}.live.dynatrace.com/api/v2/synthetic/locations`
POST	Environment ActiveGateCluster ActiveGate	`https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/synthetic/locations`

Authentication

To execute this request, you need an access token with syntheticLocations.write scope.

To learn how to obtain and use it, see Tokens and authentication.

Parameter

To find all model variations that depend on the type of the model, see JSON models.

Parameter	Type	Description	In	Required
body	PrivateSyntheticLocation	The JSON body of the request. Contains parameters of the new private synthetic location.	body	required

Request body objects

The `PrivateSyntheticLocation` object

Configuration of a private synthetic location.

Some fields are inherited from the base SyntheticLocation object.

Element	Type	Description	Required
autoUpdateChromium	boolean	Non-containerized location property. Auto upgrade of Chromium is enabled (`true`) or disabled (`false`).	optional
availabilityLocationOutage	boolean	Alerting for location outage is enabled (`true`) or disabled (`false`). Supported only for private Synthetic locations.	optional
availabilityNodeOutage	boolean	Alerting for node outage is enabled (`true`) or disabled (`false`). \n\n If enabled, the outage of any node in the location triggers an alert. Supported only for private Synthetic locations.	optional
availabilityNotificationsEnabled	boolean	Notifications for location and node outage are enabled (`true`) or disabled (`false`). Supported only for private Synthetic locations.	optional
browserExecutionSupported	boolean	Containerized location property. Boolean value describes if browser monitors will be executed on this location: `false`: Browser monitor executions disabled. `true`: Browser monitor executions enabled.	optional
city	string	The city of the location.	optional
countryCode	string	The country code of the location. To fetch the list of available country codes, use the GET all countries request.	optional
countryName	string	The country name of the location.	optional
deploymentType	string	The deployment type of the location: `STANDARD`: The location is deployed on Windows or Linux. `KUBERNETES`: The location is deployed on Kubernetes. `KUBERNETES` `OPENSHIFT` `STANDARD` `UNKNOWN`	optional
entityId	string	The Dynatrace entity ID of the location.	optional
geoLocationId	string	The Dynatrace GeoLocation ID of the location.	optional
latitude	number	The latitude of the location in `DDD.dddd` format.	required
locationNodeOutageDelayInMinutes	integer	Alert if location or node outage lasts longer than X minutes. \n\n Only applicable when `availabilityLocationOutage` or `availabilityNodeOutage` is set to `true`. Supported only for private Synthetic locations.	optional
longitude	number	The longitude of the location in `DDD.dddd` format.	required
namExecutionSupported	boolean	Containerized location property. Boolean value describes if icmp monitors will be executed on this location: `false`: Icmp monitor executions disabled. `true`: Icmp monitor executions enabled.	optional
name	string	The name of the location.	required
nodeNames	object	A mapping id to name of the nodes belonging to the location.	optional
nodes	string[]	A list of synthetic nodes belonging to the location. You can retrieve the list of available nodes with the GET all nodes call.	required
regionCode	string	The region code of the location. To fetch the list of available region codes, use the GET regions of the country request.	optional
regionName	string	The region name of the location.	optional
status	string	The status of the location: `ENABLED`: The location is displayed as active in the UI. You can assign monitors to the location. `DISABLED`: The location is displayed as inactive in the UI. You can't assign monitors to the location. Monitors already assigned to the location will stay there and will be executed from the location. `HIDDEN`: The location is not displayed in the UI. You can't assign monitors to the location. You can only set location as `HIDDEN` when no monitor is assigned to it. `DISABLED` `ENABLED` `HIDDEN`	optional
type	string	- `CLUSTER` `PRIVATE` `PUBLIC`	required
useNewKubernetesVersion	boolean	Containerized location property. Boolean value describes which kubernetes version will be used: `false`: Version 1.23+ that is older than 1.26 `true`: Version 1.26+.	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.

{
  "autoUpdateChromium": true,
  "availabilityLocationNodeOutageDelayInMinutes": 5,
  "availabilityLocationOutage": false,
  "availabilityNodeOutage": false,
  "availabilityNotificationsEnabled": true,
  "browserExecutionSupported": true,
  "city": "Linz",
  "countryCode": "AT",
  "deploymentType": "STANDARD",
  "latitude": 48.306351,
  "longitude": 14.287399,
  "maxActiveGateCount": 5,
  "minActiveGateCount": 2,
  "namExecutionSupported": false,
  "name": "Linz Location",
  "nodeNames": {
    "93302281": "ActiveGate 1"
  },
  "nodeSize": "S",
  "nodes": [
    "93302281"
  ],
  "regionCode": "04",
  "status": "ENABLED",
  "type": "PRIVATE",
  "useNewKubernetesVersion": true
}

Response

Response codes

Code	Type	Description
201	SyntheticLocationIdsDto	Success. The private location has been created. The response contains the ID of the new location.
4XX	ErrorEnvelope	Client side error.
5XX	ErrorEnvelope	Server side error.

Response body objects

The `SyntheticLocationIdsDto` object

A DTO for synthetic Location IDs.

Element	Type	Description
entityId	string	Entity ID to be transferred
geoLocationId	string	GeoLocation ID to be transferred

Response body JSON model

{
  "entityId": "string",
  "geoLocationId": "string"
}

Example

In this example, the request creates a new private Synthetic location. This location lies in Linz, Austria. It uses the synthetic node with the ID of 290433380.

The API token is passed in the Authorization header.

You can download or copy the example request body to try it out on your own. Be sure to replace the list of nodes with nodes available in your environment. You can fetch the list of available nodes with the GET all nodes request.

Curl

curl -L -X POST 'https://mySampleEnv.live.dynatrace.com/api/v2/synthetic/locations' \
-H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
-H 'Content-Type: application/json' \
--data-raw '{
  "type": "PRIVATE",
  "name": "REST example - Linz",
  "countryCode": "AT",
  "city": "Linz",
  "status": "ENABLED",
  "latitude": 48.306351,
  "longitude": 14.287399,
  "nodes": [
    "290433380"
  ],
  "availabilityLocationOutage": false,
  "availabilityNodeOutage": false,
  "locationNodeOutageDelayInMillis": 5000
}
'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/synthetic/locations

Request body

{
  "type": "PRIVATE",
  "name": "REST example - Linz",
  "countryCode": "AT",
  "city": "Linz",
  "status": "ENABLED",
  "latitude": 48.306351,
  "longitude": 14.287399,
  "nodes": ["290433380"],
  "availabilityLocationOutage": false,
  "availabilityNodeOutage": false,
  "locationNodeOutageDelayInMillis": 5000
}

Response body

{
  "entityId": "SYNTHETIC_LOCATION-493122BFA29674DC",
  "geoLocationId": "GEOLOCATION-96B57899C9B5A3C7"
}

Response code

200