--- title: Synthetics REST API version 1 (deprecated) source: https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/synthetics-api/synthetics-rest-api-version-1 --- Currently New Relic supports two versions of the synthetic monitoring API: v1 and v3. Version 3 was released October 2016. **Version 1 is deprecated** and will eventually no longer be available. No termination date has been announced. However, no further development or modifications will be made to v1. > #### ⚠️ CAUTION > > Recommendation: Create new monitors using the [v3 synthetics API](https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/manage-synthetics-monitors-via-rest-api) and migrate v1 scripts to their v3 equivalent. To use the REST API for New Relic's synthetic monitoring, you must [activate API access and generate your Admin User's API key](https://docs.newrelic.com/docs/apis/rest-api-v2/requirements/api-keys#creating) from your account settings. Then you can make standard API calls via the command line. ## Managing simple and scripted monitors [#simple-monitor-calls] You must use your Admin User's API key to make synthetics REST API calls. > #### ⚠️ CAUTION > > The synthetics REST API limits an account's rate of requests to three requests per second. Requests made in excess of this threshold will return a 429 response code. These examples show curl commands: **Get all monitors** To view a list of all monitors in New Relic for your account, send a GET request to `https://synthetics.newrelic.com/synthetics/api/v1/monitors`. For example: ````sh curl -v \ -H 'X-Api-Key:API_KEY' https://synthetics.newrelic.com/synthetics/api/v1/monitors ``` A successful request will return a **200 OK** response. The [data returned](/docs/apis/synthetics-rest-api/monitor-examples/payload-attributes-synthetics-rest-api#api-attributes) will be a JSON object in the following format: ```json { "count": integer, "monitors": [ { "id": UUID, "name": string, "type": string, "frequency": integer, "uri": string, "locations": array of strings, "status": string, "slaThreshold": double, "userId": integer, "apiVersion": string } ] } ``` ```` **Get a specific monitor** To view a single existing monitor in New Relic, send a GET request to `https://synthetics.newrelic.com/synthetics/api/v1/monitors/MONITOR_ID`. Replace the `MONITOR_ID` in the following example with the specific monitor ID. ````sh curl -v \ -H 'X-Api-Key:API_KEY' https://synthetics.newrelic.com/synthetics/api/v1/monitors/MONITOR_ID ``` A successful request will return a **200 OK** response. The [data returned](/docs/apis/synthetics-rest-api/monitor-examples/payload-attributes-synthetics-rest-api#api-attributes) will be a JSON object in the following format: ```json { "id": UUID, "name": string, "type": string, "frequency": integer, "uri": string, "locations": array of strings, "status": string, "slaThreshold": double, "userId": integer, "apiVersion": string } ``` An invalid monitor ID will return the error **404 Not Found**: The specified monitor doesn't exist. ```` **Create a monitor** To add a new monitor to your account in New Relic, send a POST request to `https://synthetics.newrelic.com/synthetics/api/v1/monitors` with a JSON payload that describes the monitor: ````json { "name": string [required], "type": string (SIMPLE, BROWSER, SCRIPT_API, SCRIPT_BROWSER) [required], "frequency": integer (minutes) [required, must be one of 1, 5, 10, 15, 30, 60, 360, 720, or 1440], "uri": string [required for SIMPLE and BROWSER type], "locations": array of strings (send a GET request to https://synthetics.newrelic.com/synthetics/api/v1/locations to get a list of valid locations) [at least one required], "status": string (ENABLED, DISABLED) [required], "slaThreshold": double, } ``` In addition, to **add a scripted monitor** via the REST API, call an [additional API endpoint](/docs/apis/synthetics-rest-api/monitor-examples/manage-synthetics-monitor-scripts-rest-api) to send the script for the monitor just created. Replace the [Synthetics REST API attributes](/docs/apis/synthetics-rest-api/monitor-examples/payload-attributes-synthetics-rest-api) in the following example with your specific values. ```sh curl -v \ -X POST -H 'X-Api-Key:API_KEY' \ -H 'Content-Type: application/json' https://synthetics.newrelic.com/synthetics/api/v1/monitors \ -d \ '{ "name": "monitor1", "frequency": 15, "uri": "http://my-uri.com", "locations": ["AWS_US_WEST_1"], "type": "browser" }' ``` A successful request will return a **201 Created** response, with the URI of the newly-created monitor specified in the `location` header. Possible error codes include: * **400 Bad Request**: One or more of the monitor values is invalid, or the format of the request is invalid. For example, the frequency is out of bounds or one or more of the specified locations is invalid (See the error message in the body of the response.) * **402 Payment Required**: Creating the monitor will increase your scheduled checks past your account's purchased check limit. ```` **Update an existing monitor** To update an existing monitor in New Relic, send a PUT request to `https://synthetics.newrelic.com/synthetics/api/v1/monitors/MONITOR_ID`. In addition, for scripted monitors, follow the procedures to [update the BASE64 encoded script](https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/manage-synthetics-monitor-scripts-rest-api). Replace the `MONITOR_ID` in the following example with the specific monitor ID, and replace the [Synthetics REST API attributes](https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/payload-attributes-synthetics-rest-api) with your specific values. ````sh curl -v \ -X PUT -H 'X-Api-Key:API_KEY' \ -H 'Content-Type: application/json' https://synthetics.newrelic.com/synthetics/api/v1/monitors/MONITOR_ID \ -d \ '{ "name": "updated monitor name", "type": "simple", "frequency": 15, "uri": "http://my-uri.com/", "locations": ["AWS_US_WEST_1"], "status": "enabled", "slaThreshold": "7.0" }' ``` PUT requests are intended to replace target entities, so all attributes required in the JSON payload when [creating a new monitor](/docs/apis/synthetics-rest-api/monitor-examples/manage-synthetics-monitors-via-rest-api#add-simple-ping-monitor) are also required when updating an existing monitor. A successful request will return a **204 No Content** response, with an empty body. Possible error codes include: * **400 Bad Request**: One or more of the monitor values is invalid, or the format of the request is invalid. For example, the frequency is out of bounds or one or more of the specified locations is invalid (See the error message in the body of the response.) * **404 Not Found**: The specified monitor does not exist. ```` **Delete an existing monitor** To delete an existing monitor in New Relic, send a DELETE request to `https://synthetics.newrelic.com/synthetics/api/v1/monitors/MONITOR_ID`. Replace the [`MONITOR_ID`](https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/payload-attributes-synthetics-rest-api) in the following example with the specific monitor ID. ````sh curl -v \ -H 'X-Api-Key:API_KEY' \ -X DELETE https://synthetics.newrelic.com/synthetics/api/v1/monitors/MONITOR_ID ``` A successful request will return a **204 No Content** response, with an empty body. An unsuccessful request will return the response, **404 Not Found**: The specified monitor does not exist. ```` **Get list of valid locations** To retrieve the list of valid locations in New Relic, use the following command. ````sh curl -v \ -X GET -H 'X-Api-Key:API_KEY' https://synthetics.newrelic.com/synthetics/api/v1/locations ``` ```` ## Managing scripted monitors [#scripted-monitor-calls] In addition to the general API, there are several API methods for the **scripted browser** (`SCRIPT_BROWSER`) and **api test** (`SCRIPT_API`) monitor types. These examples show curl commands. **Get monitor script** To view the script associated with a specific `SCRIPT_BROWSER` or `SCRIPT_API` monitor in New Relic for your account, send a GET request to `https://synthetics.newrelic.com/synthetics/api/v1/monitors/MONITOR_ID/script`. Replace the `MONITOR_ID` with the specific monitor ID. For example: ````sh curl -v -H 'X-Api-Key: API_KEY' https://synthetics.newrelic.com/synthetics/api/v1/monitors/MONITOR_ID/script ``` A successful request will return a **200 OK** response. The data returned will be a JSON object in the following format: ```json { "scriptText": BASE64 encoded string } ``` Possible error codes include: * **403 Forbidden:** The specified monitor is not of type `SCRIPT_BROWSER` or `SCRIPT_API`. * **404 Not Found:** The specified monitor doesn't exist or the script associated with the monitor doesn't exist. ```` **Add scripted monitor** To add a new scripted monitor to New Relic with the REST API: 1. Follow [standard API procedures to add a new monitor](https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/manage-synthetics-monitors-via-rest-api#add-simple-ping-monitor), and identify the `type` as a `SCRIPT_BROWSER` or `SCRIPT_API`. 2. Update the new monitor with a BASE64 encoded version of the script to the `$MONITOR_UUID/script` endpoint. For more information, refer to the [example](#sample-script). **Update monitor script** To update the script associated with a specific `SCRIPT_BROWSER` or `SCRIPT_API` monitor in New Relic for your account, send a PUT request to `https://synthetics.newrelic.com/synthetics/api/v1/monitors/MONITOR_ID/script` with a JSON payload that contains the `scriptText` (required). The `scriptLocations` data is required only for private locations with [**Verified Script Execution**](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/private-locations/verified-script-execution-private-locations) turned on. The password used to generate the HMAC string must match the password set for the private location. When generating the HMAC string, use the SHA256 algorithm. ````json { "scriptText": BASE64 encoded String, "scriptLocations": [ { "name": Location name, "hmac" BASE64 encoded String of SHA256 HMAC for location } ] } ``` Replace the `MONITOR_ID` with the specific monitor ID. Here is an example for the script: ``` var assert = require('assert'); assert.equal('1', '1'); ``` This example uses `password` as the password for the `scriptLocation`. ```sh curl -v \ -H "X-Api-Key:'API_KEY'" \ -H 'content-type: application/json' \ 'https://synthetics.newrelic.com/synthetics/api/v1/monitors/MONITOR_ID/script' \ -d \ '{ "scriptText": "dmFyIGFzc2VydCA9IHJlcXVpcmUoJ2Fzc2VydCcpOw0KYXNzZXJ0LmVxdWFsKCcxJywgJzEnKTs=", "scriptLocations": [{ "name": "my_vse_enabled_location", "hmac": "MjhiNGE4MjVlMDE1N2M4NDQ4MjNjNDFkZDEyYTRjMmUzZDE3NGJlNjU0MWFmOTJlMzNiODExOGU2ZjhkZTY4" }] }' ``` A successful request will return a **204 No Content** response with an empty body. Possible error codes include: * **400 Bad Request:** Invalid BASE64 encoded string for `scriptText` or `hmac`. * **403 Forbidden:** The specified monitor is not of the type `SCRIPT_BROWSER` or `SCRIPT_API`. * **404 Not Found:** The specified monitor does not exist. ```` ## Scripted browser example Here is an example of using New Relic's REST API and the bash script to create a scripted browser monitor. **Scripted browser API example** The following example shows curl commands to create a scripted browser monitor. - At the top of the script, replace the variables with your specific values. - For the `scriptfile` variable, identify the filename for the script to be created. Here is a sample script that can be saved as `sample_synth_script.js` to use in the example: ```js var assert = require("assert"); $browser .get("http://example.com") .then(function () { // Check the H1 title matches "Example Domain" return $browser.findElement($driver.By.css("h1")).then(function (element) { return element.getText().then(function (text) { assert.equal("Example Domain", text, "Page H1 title did not match"); }); }); }) .then(function () { // Check that the external link matches "http://www.iana.org/domains/example" return $browser .findElement($driver.By.css("div > p > a")) .then(function (element) { return element.getAttribute("href").then(function (link) { assert.equal( "http://www.iana.org/domains/example", link, "More information link did not match" ); }); }); }); ``` **Bash script example** This example show the bash script that will create the `SCRIPTED_BROWSER` monitor. ````bash #!/bin/bash # Admin API key from your account settings adminAPIKey='' # Other attributes found at https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/attributes-synthetics-rest-api#api-attributes monitorName='Test API Script' monitorType='SCRIPT_BROWSER' frequency=1440 locations='"AWS_US_WEST_1", "AWS_US_EAST_1"' slaThreshold=7.0 # Location of the file with your script scriptfile=sample_synth_script.js # Test that the script file exists (does not validate content) if [ -e "$scriptfile" ] then script=$(cat "$scriptfile") payload="{ \"name\" : \"$monitorName\", \"frequency\" : $frequency, \"locations\" : [ $locations ], \"status\" : \"ENABLED\", \"type\" : \"$monitorType\", \"slaThreshold\" : $slaThreshold, \"uri\":\"\"}" echo "Creating monitor" # Make cURL call to API and parse response headers to get monitor UUID shopt -s extglob # Required to trim whitespace; see below while IFS=':' read key value; do # trim whitespace in "value" value=${value##+([[:space:]])}; value=${value%%+([[:space:]])} case "$key" in location) LOCATION="$value" ;; HTTP*) read PROTO STATUS MSG <<< "$key{$value:+:$value}" ;; esac done < <(curl -sS -i -X POST -H "X-Api-Key:$adminAPIKey" -H 'Content-Type: application/json' https://synthetics.newrelic.com/synthetics/api/v1/monitors -d "$payload") # Validate monitor creation & add script unless it failed if [ $STATUS = 201 ]; then echo "Monitor created, $LOCATION " echo "Uploading script" # base64 encode script encoded=`echo "$script" | base64` scriptPayload='{"scriptText":"'$encoded'"}' curl -s -X PUT -H "X-Api-Key:$adminAPIKey" -H 'Content-Type: application/json' "$LOCATION/script" -d $scriptPayload echo "Script uploaded" else echo "Monitor creation failed" fi else echo "script file not found, not creating monitor" fi ``` ```` ## Synthetics attributes [#api-attributes] Here are the attributes used with Synthetics REST API calls, listed in alphabetical order. | **Synthetics API attribute** | **Definition** | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiVersion` | String: The version number. | | `emails` | Array of strings: Email addresses for [alert notifications](https://docs.newrelic.com/docs/apis/synthetics-rest-api/alert-examples/manage-synthetics-alert-notifications-rest-api) with New Relic. | | `frequency` | Integer: Number of minutes between [checks](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/using-monitors/add-edit-monitors#setting-frequency). Valid values include 1, 5, 15, 30, 60, 360, 720, and 1440. | | `id` | The UUID for the specific synthetic monitor. | | `locations` | Array of strings: [Array of locations](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/using-monitors/add-edit-monitors#setting-location) by full label. | | `name` | String: The [monitor's name](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/using-monitors/add-edit-monitors#setting-name). | | `scriptLocations` | String: The `name` and `hmac` values for [private locations](https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/manage-synthetics-monitor-scripts-rest-api) using [Verified Script Execution](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/private-locations/verified-script-execution-private-locations). | | `scriptText` | String: The BASE64 encoded text for [scripted monitors](https://docs.newrelic.com/docs/apis/synthetics-rest-api/monitor-examples/manage-synthetics-monitor-scripts-rest-api). | | `slaThreshold` | Double: Value for the [Synthetics SLA report](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/pages/synthetics-sla-report-aggregate-monitor-metrics), in seconds. | | `status` | String: Valid values include `ENABLED` and `DISABLED`. | | `type` | String: [Type of monitor](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/using-monitors/add-edit-monitors#settings-type). Valid values include: - `SIMPLE` (Ping) - `BROWSER` - `SCRIPT_BROWSER` - `SCRIPT_API` | | `uri` | String: The URI for `SIMPLE` and `BROWSER` [monitor types](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/using-monitors/add-edit-monitors#settings-type); for example, `http://my-site.com`. Optional for `SCRIPT_BROWSER` and `SCRIPT_API`. | | `userID` | Integer: The specific user ID. | ## Specific monitor endpoint [#specific-monitor] When making REST API calls for a specific monitor, include the `monitor_uuid` as part of the endpoint. The `monitor_uuid` is the GUID which is part of the URL. For example, a selected [synthetics monitor](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/pages/synthetics-overview-page-view-monitors-performance) has this URL: ``` https://synthetics.newrelic.com/accounts/nnnn/monitors/ab123-c456d-e78-90123-f45g ``` The `monitor_uuid` is the value that follows `/monitors/`.