• Home
  • Dynatrace API
  • Environment
  • Synthetic v1
  • Locations
  • POST a location

Synthetic locations API - POST a location

We have a new version of this API—Synthetic API v2. Check it out!

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.

POSTManaged https://{your-domain}/e/{your-environment-id}/api/v1/synthetic/locations
SaaS https://{your-environment-id}.live.dynatrace.com/api/v1/synthetic/locations
Environment ActiveGate https://{your-activegate-domain}/e/{your-environment-id}/api/v1/synthetic/locations

Authentication

To execute this request, you need Create and read synthetic monitors, locations, and nodes (ExternalSyntheticIntegration) 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.

ParameterTypeDescriptionInRequired
bodyPrivateSyntheticLocation

The JSON body of the request. Contains parameters of the new private synthetic location.

bodyoptional

Request body objects

The PrivateSyntheticLocation object

Configuration of a private synthetic location.

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

ElementTypeDescriptionRequired
entityIdstring

The Dynatrace entity ID of the location.

required
typestring

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

The name of the location.

required
countryCodestring

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
regionCodestring

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
citystring

The city of the location.

optional
latitudenumber

The latitude of the location in DDD.dddd format.

required
longitudenumber

The longitude of the location in DDD.dddd format.

required
statusstring

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
optional
nodesstring[]

A list of synthetic nodes belonging to the location.

You can retrieve the list of available nodes with the GET all nodes call.

required
availabilityLocationOutageboolean

The alerting of location outage is enabled (true) or disabled (false).

optional
availabilityNodeOutageboolean

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
locationNodeOutageDelayInMinutesinteger

Alert if the location or node outage lasts longer than X minutes.

Only applicable when availabilityLocationOutage or availabilityNodeOutage is set to true.

optional
availabilityNotificationsEnabledboolean

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

optional
autoUpdateChromiumboolean

Auto upgrade of Chromium is enabled (true) or disabled (false).

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.

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

Response

Response codes

CodeTypeDescription
200EntityIdDto

Success

Response body objects

The EntityIdDto object

A DTO for entity ID.

ElementTypeDescriptionRequired
entityIdstring

Entity ID to be transferred

required

Response body JSON model

json
{
  "entityId": "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 93302281.

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.

Curl

bash
curl -X POST \
  https://mySampleEnv.live.dynatrace.com/api/v1/synthetic/locations \
  -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "PRIVATE",
  "name": "REST example - Linz",
  "countryCode": "AT",
  "regionCode": "AU04",
  "city": "Linz",
  "latitude": 48.306351,
  "longitude": 14.287399,
  "nodes": [
    "93302281"
  ]
}
'

Request URL

http
https://mySampleEnv.live.dynatrace.com/api/v1/synthetic/locations

Request body

json
{
  "type": "PRIVATE",
  "name": "REST example - Linz",
  "countryCode": "AT",
  "regionCode": "AU04",
  "city": "Linz",
  "latitude": 48.306351,
  "longitude": 14.287399,
  "nodes": [
    "93302281"
  ]
}

Response body

json
{
  "entityId": "SYNTHETIC_LOCATION-8F419D1B53639A45"
}

Response code

200

Related topics
  • Synthetic Monitoring

    Learn about Synthetic Monitoring and how to create a single-URL browser monitor, a browser clickpath, or an HTTP monitor.

  • Create a private Synthetic location

    Learn how to create a private location for synthetic monitoring.