Synthetic locations API v2 - POST a location

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.

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

Body format

The PrivateSyntheticLocation 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.

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
 required
name string

The name of the location.

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

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

 optional
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.
 optional
geoLocationId string

The Dynatrace GeoLocation ID of 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
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
availabilityNotificationsEnabled boolean

The notifications of location and node outage is enabled (true) or disabled (false).

 optional

Response

Response codes

Code Description
201

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

Response body

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

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

api-examples/env/synthetic-v2/post-location.json
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