Synthetic locations API v2 - POST a location (Dynatrace Managed)

This API call 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.

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/synthetic/locations

Parameter

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

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

Request body objects

The `RequestBody` object

Element	Type	Description
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. Can be `null`.
availabilityLocationOutage	boolean	The alerting of location outage is enabled (`true`) or disabled (`false`). Can be `null`.
availabilityNodeOutage	boolean	The alerting of node outage is enabled (`true`) or disabled (`false`). If enabled, the outage of any node in the location triggers an alert. Can be `null`.
locationNodeOutageDelayInMinutes	integer	Alert if the location or node outage lasts longer than X minutes. Only applicable when availabilityLocationOutage or availabilityNodeOutage is set to `true`. Can be `null`.
availabilityNotificationsEnabled	boolean	The notifications of location and node outage is enabled (`true`) or disabled (`false`). Can be `null`.
autoUpdateChromium	boolean	Auto upgrade of Chromium is enabled (`true`) or disabled (`false`). Can be `null`.

The `SyntheticLocation` object

Configuration of a synthetic location.

countryCode, regionCode, city parameters are optional as they can be retrieved based on latitude and longitude of location.

The actual set of fields depends on the type of the location. Find the list of actual objects in the description of the type field or see Synthetic locations API v2 - JSON models.

Element	Type	Description
entityId	string	The Dynatrace entity ID of the location.
type	string	Defines the actual set of fields depending on the value. See one of the following objects: `PUBLIC` -> PublicSyntheticLocation `PRIVATE` -> PrivateSyntheticLocation `CLUSTER` -> PrivateSyntheticLocation The element can hold these values `CLUSTER` `PRIVATE` `PUBLIC`
name	string	The name of the location.
countryCode	string	The country code of the location. Use the alpha-2 code of the ISO 3166-2 standard, (for example, `AT` for Austria or `PL` for Poland). Can be `null`.
regionCode	string	The region code of the location. For the USA or Canada use ISO 3166-2 state codes (without `US-` or `CA-` prefix), for example, `VA` for Virginia or `OR` for Oregon. For the rest of the world use FIPS 10-4 codes. Can be `null`.
city	string	The city of the location. Can be `null`.
latitude	number	The latitude of the location in `DDD.dddd` format.
longitude	number	The longitude of the location in `DDD.dddd` format.
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. The element can hold these values `DISABLED` `ENABLED` `HIDDEN` Can be `null`.
geoLocationId	string	The Dynatrace GeoLocation ID of the location. 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
{
  "nodes": [
    "string"
  ],
  "availabilityLocationOutage": true,
  "availabilityNodeOutage": true,
  "locationNodeOutageDelayInMinutes": 1,
  "availabilityNotificationsEnabled": true,
  "autoUpdateChromium": 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.

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

json
{
  "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

shell
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

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

Request body

json
{
  "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

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

Response code

200