Synthetic locations API - POST a location

Creates a new private synthetic location.

The request consumes and produces an application/json payload.

Early Adopter

This request is an Early Adopter release and may be changed in non-compatible way.

POST	Managed https://{your-domain}/e/{your-environment-id}/api/v2/synthetic/locations SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/synthetic/locations

Authentication

To execute this request, you need the Write synthetic locations using API V2 (syntheticLocations.write) permission assigned to your API token. 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	optional

Request parameters JSON model

The PrivateSyntheticLocation object

Configuration of a synthetic location.

The actual set of fields depends on the type of the location.

Element	Type	Description	Required
entityId	string	The Dynatrace entity ID of the location.	required
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 type element can hold these values.	required
name	string	The name of the location.	required
city	string	The city of the location.	optional
latitude	number	The latitude of the location in `DDD.dddd` format.	required
longitude	number	The longitude of the location in `DDD.dddd` format.	required
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 status element can hold these values.	optional
nodes	string[]	A list of synthetic nodes belonging to the location.	required
availabilityLocationOutage	boolean	The alerting of location outage is enabled (`true`) or disabled (`false`).	optional
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.	optional
locationNodeOutageDelayInMinutes	integer	Alert if the location or node outage lasts longer than X minutes. Only applicable when availabilityLocationOutage or availabilityNodeOutage is set to `true`.	optional
geoLocationId	string	The Dynatrace GeoLocation ID of the location.	required

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request. See the Example expandable section for working sample request.

      
  {
  "type": "PRIVATE",
  "name": "Linz Location",
  "latitude": 48.306351,
  "longitude": 14.287399,
  "nodes": [
    "93302281"
  ],
  "status": "ENABLED",
  "availabilityLocationOutage": false,
  "availabilityNodeOutage": false,
  "availabilityLocationNodeOutageDelayInMinutes": 5
}

Possible values

Possible values for the status element in the PrivateSyntheticLocation object:

DISABLED
ENABLED
HIDDEN

Possible values for the type element in the PrivateSyntheticLocation object:

CLUSTER
PRIVATE
PUBLIC

Response codes

Code	Description
201	Success. The private location has been created. The response contains the ID of the new location.

Response format

Response parameters JSON model

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

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

Download

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