Digital Experience API examples

Create and manage Digital Experience entities, such as websites, URIs, page speed checks, and Synthetic transactions with the SolarWinds Observability REST API.

This topic will demonstrate some commonly used Digital Experience API queries.

Prerequisites

Before getting started, you need the following.

A full access API token. See API Tokens.
Your organization's base API URL. See Public API.
A user with permission to create and update Digital Experience entities.

After meeting the prerequisites, you will be ready to try any of these Digital Experience API examples in your SolarWinds Observability environment.

List entities by Digital Experience type examples

You should use the generic entity endpoint when you want to list Digital Experience entities by type. You can list entity's by Website, URI, Pagespeed check, and Synthetic transaction.

Note the following in the examples below.

type filters the returned entities to one Digital Experience type.
pageSize controls how many entities are returned per page.
name, before, and after are also supported query parameters when you need narrower list queries.

List Website entities example

curl --request GET \
  --url 'https://api.na-01.cloud.solarwinds.com/v1/entities?type=Website&pageSize=50' \
  --header 'Authorization: Bearer <your_api_token>' \
  --header 'accept: application/json'

List URI entities example

curl --request GET \
  --url 'https://api.na-01.cloud.solarwinds.com/v1/entities?type=Uri&pageSize=50' \
  --header 'Authorization: Bearer <your_api_token>' \
  --header 'accept: application/json'

List Pagespeed entities example

curl --request GET \
  --url 'https://api.na-01.cloud.solarwinds.com/v1/entities?type=PageSpeed&pageSize=50' \
  --header 'Authorization: Bearer <your_api_token>' \
  --header 'accept: application/json'

List Synthetic transaction entities example

curl --request GET \
  --url 'https://api.na-01.cloud.solarwinds.com/v1/entities?type=SyntheticTransaction&pageSize=50' \
  --header 'Authorization: Bearer <your_api_token>' \
  --header 'accept: application/json'

Website entity examples

In the examples below, you can create a Website entity with Availability check, and Update a Website entity Availability check.

Create a Website Availability check

This example can be used to create a new Website entity to monitor.

curl -X POST \
  'https://api.na-01.cloud.solarwinds.com/v1/dem/websites' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <your_api_token>' \
  -d '{
    "name": "example.com",
    "url": "https://example.com",
    "availabilityCheckSettings": {
      "platformOptions": {
        "probePlatforms": ["AWS"],
        "testFromAll": true
      },
      "testFrom": {
        "type": "REGION",
        "values": ["NA"]
      },
      "testIntervalInSeconds": 300,
      "protocols": ["HTTPS"]
    }
  }'

Here's a quick breakdown of some of the parameters used in the example above.

name is the customer-visible monitor name and must be unique within the organization.
url must be a valid absolute URL.
availabilityCheckSettings.platformOptions.probePlatforms limits execution to selected cloud probe platforms.
availabilityCheckSettings.testFrom.type defines the location granularity, such as REGION, COUNTRY, or CITY.
availabilityCheckSettings.testFrom.values supplies the actual location values for the selected granularity.
availabilityCheckSettings.testIntervalInSeconds sets how often the check runs and must be divisible by 60.
availabilityCheckSettings.protocols defines whether the check runs over HTTP, HTTPS, or both.

Update a Website Availability check

This example can be used to update an existing Website entity.

curl -X PUT \
  'https://api.na-01.cloud.solarwinds.com/v1/dem/websites/e-<website_id>' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <your_api_token>' \
  -d '{
    "name": "example.com - production",
    "url": "https://example.com",
    "availabilityCheckSettings": {
      "platformOptions": {
        "probePlatforms": ["AWS"],
        "testFromAll": true
      },
      "testFrom": {
        "type": "REGION",
        "values": ["NA", "EU"]
      },
      "testIntervalInSeconds": 300,
      "protocols": ["HTTPS"]
    }
  }'

This examples uses the same request shape as the Create example. Only change the values you want the monitor to keep going forward.

The most common customer edits are name, locations, interval, protocols, and optional SSL or content validation settings.

URI entity examples

In the examples below, you can create a URI entity with a TCP check, and Update a URI entity TCP check.

Create a URI TCP check

This example can be used to create a URI entity that checks TCP connectivity to www.solarwinds.com on port 443.

curl -X POST \
  'https://api.na-01.cloud.solarwinds.com/v1/dem/uris' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <your_api_token>' \
  -d '{
  "name": "solarwinds.com TCP 443",
  "ipOrDomain": "solarwinds.com",
  "availabilityCheckSettings": {
    "platformOptions": {
      "probePlatforms": [
        "AWS"
      ],
      "testFromAll": true
    },
    "testFrom": {
      "type": "REGION",
      "values": [
        "NA"
      ]
    },
    "testIntervalInSeconds": 14400,
    "outageConfiguration": {
      "failingTestLocations": "all",
      "consecutiveForDown": 2
    },
    "tcp": {
      "enabled": true,
      "port": 443
    }
  },
  "tags": [
    {
      "key": "environment",
      "value": "production"
    }
  ]
}'

Here's a quick breakdown of some of the parameters used in the example above.

ipOrDomain is the host to monitor, without a URL scheme or path.
tcp.enabled enables the TCP check.
tcp.port is the destination port. This example configures TCP only.
testIntervalInSeconds: 14400 runs the check every four hours.
This is a connectivity-only check, so stringToSend and stringToExpect are omitted.

A TCP connection to port 443 does not validate TLS certificates or an HTTPS response. Do not send a plaintext HTTP request to an HTTPS port.

Update a URI TCP check

This example can be used to update an existing URI TCP check.

curl -X PUT \
  'https://api.na-01.cloud.solarwinds.com/v1/dem/uris/e-<uri_id>' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <your_api_token>' \
  -d '{
  "name": "solarwinds.com TCP 443 - production",
  "ipOrDomain": "solarwinds.com",
  "availabilityCheckSettings": {
    "platformOptions": {
      "probePlatforms": [
        "AWS"
      ],
      "testFromAll": true
    },
    "testFrom": {
      "type": "REGION",
      "values": [
        "NA",
        "EU"
      ]
    },
    "testIntervalInSeconds": 300,
    "outageConfiguration": {
      "failingTestLocations": "all",
      "consecutiveForDown": 2
    },
    "tcp": {
      "enabled": true,
      "port": 443
    }
  },
  "tags": [
    {
      "key": "environment",
      "value": "production"
    }
  ]
}'

Here's a quick breakdown of the parameters used in the example above.

e-<uri_id> is the existing URI entity ID in the path.
This example keeps TCP monitoring on port 443, changes the monitor name, selects the NA and EU regions, and sets the interval to 300 seconds.

You need to use the ipOrDomain parameter, and not the deprecated url field for URI create and update requests.

Synthetic transaction entity examples

This example can be used to create a Synthetic transaction entity to monitor.

curl -X POST \
  'https://api.na-01.cloud.solarwinds.com/v1/dem/transactions' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <your_api_token>' \
  -d '{
    "name": "Checkout flow",
    "description": "Synthetic transaction created by API",
    "relatedWebsiteId": "e-<website_id>",
    "testDefinition": {
      "testFrom": {
        "type": "REGION",
        "values": ["NA"]
      },
      "platformOptions": {
        "probePlatforms": ["AWS"],
        "testFromAll": true
      },
      "outageConfiguration": {
        "failingTestLocations": "all",
        "consecutiveForDown": 2
      },
      "testIntervalInSeconds": 900,
      "windowSize": {
        "width": 1920,
        "height": 1080
      },
      "userAgent": "537.36 Chrome",
      "commands": [
        {
          "command": "OPEN",
          "target": "https://example.com"
        }
      ]
    },
    "tags": [
      {
        "key": "environment",
        "value": "production"
      }
    ]
  }'

Here's a quick breakdown of some of the parameters used in the example above.

name is the transaction name displayed in SolarWinds Observability Digital Experience.
description helps explain the Synthetic transaction's purpose.
relatedWebsiteId links the transaction to an existing Website where relevant.
testDefinition.testFrom chooses the source region set for the journey.
testDefinition.platformOptions chooses probe platforms and whether to use all matching probes.
testDefinition.outageConfiguration controls when a failed transaction is treated as down.
testDefinition.testIntervalInSeconds sets how often the transaction runs.
testDefinition.windowSize sets the browser viewport for browser-style flows.
testDefinition.userAgent controls the browser user agent string.
testDefinition.commands defines the ordered steps of the transaction.
tags lets you attach key-value metadata to the transaction.

Update a Synthetic transaction

This example can be used to update an existing Synthetic transaction entity.

curl -X PUT \
  'https://api.na-01.cloud.solarwinds.com/v1/dem/transactions/e-<transaction_id>' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <your_api_token>' \
  -d '{
    "name": "Checkout flow",
    "description": "Updated transaction description",
    "relatedWebsiteId": "e-<website_id>",
    "testDefinition": {
      "testFrom": {
        "type": "REGION",
        "values": ["NA"]
      },
      "platformOptions": {
        "probePlatforms": ["AWS"],
        "testFromAll": true
      },
      "outageConfiguration": {
        "failingTestLocations": "all",
        "consecutiveForDown": 2
      },
      "testIntervalInSeconds": 900,
      "windowSize": {
        "width": 1920,
        "height": 1080
      },
      "userAgent": "537.36 Chrome",
      "commands": [
        {
          "command": "OPEN",
          "target": "https://example.com"
        }
      ]
    },
    "tags": [
      {
        "key": "environment",
        "value": "production"
      }
    ]
  }'

Troubleshooting example

Use this example to debug the REST API.

{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "url",
        "message": "URL must be a valid absolute HTTP or HTTPS URL."
      }
    ]
  }
}

Search SolarWinds Support

Digital Experience API examples

Prerequisites

List entities by Digital Experience type examples

List Website entities example

List URI entities example

List Pagespeed entities example

List Synthetic transaction entities example

Website entity examples

Create a Website Availability check

Update a Website Availability check

URI entity examples

Create a URI TCP check

Update a URI TCP check

Synthetic transaction entity examples

Update a Synthetic transaction

Troubleshooting example