Added private locations and Downgrade a scripted API monitor's runtime

src/content/docs/apis/nerdgraph/examples/synthetics-api/private-locations.mdx

@@ -0,0 +1,303 @@
+---
+title: "NerdGraph tutorial: Manage private locations"
+tags:
+  - Synthetics
+  - APIs
+  - NerdGraph
+  - Examples
+metaDescription: How to use New Relic NerdGraph API to create and manage private locations for synthetic monitoring.
+freshnessValidatedDate: never
+---
+
+[Private locations](/docs/synthetics/synthetic-monitoring/private-locations/private-locations-overview-monitor-internal-sites-add-new-locations) allow you to monitor applications behind your firewall or in restricted networks. When you create a private location, you install and configure private minions to execute the monitors assigned to that private location. This tutorial provides examples of how to use the NerdGraph API to programmatically manage private locations.
+
+## Create a private location [#create-private-location]
+
+You can create a private location using the `syntheticsCreatePrivateLocation` mutation. This mutation allows you to set up a new private location in your monitoring infrastructure where you can deploy private minions or job managers.
+
+### Input parameters
+
+<table>
+  <thead>
+    <tr>
+      <th>Parameter</th>
+      <th>Data Type</th>
+      <th>Is it Required?</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`accountId`</td>
+      <td>Integer</td>
+      <td>Yes</td>
+      <td>The account ID associated with the private location.</td>
+    </tr>
+    <tr>
+      <td>`description`</td>
+      <td>String</td>
+      <td>No</td>
+      <td>The description of the private location.</td>
+    </tr>
+    <tr>
+      <td>`name`</td>
+      <td>String</td>
+      <td>Yes</td>
+      <td>The name of the private location.</td>
+    </tr>
+    <tr>
+      <td>`shared`</td>
+      <td>Boolean</td>
+      <td>No</td>
+      <td>Specifies whether the private location is shared across the organization.</td>
+    </tr>
+    <tr>
+      <td>`verifiedScriptExecution`</td>
+      <td>Boolean</td>
+      <td>Yes</td>
+      <td>If the value is true, the private location requires a password to edit.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Sample request
+
+```graphql
+mutation {
+  syntheticsCreatePrivateLocation(
+    accountId: ACCOUNT_ID,
+    name: "PrivateLocationName",
+    description: "Optional description",
+    shared: true,
+    verifiedScriptExecution: false
+  ) {
+    guid
+    errors {
+      description
+      type
+    }
+  }
+}
+```
+
+### Sample response
+
+A successful response returns the GUID of the newly created private location:
+
+```json
+{
+  "data": {
+    "syntheticsCreatePrivateLocation": {
+      "guid": "PRIVATE_LOCATION_GUID",
+      "errors": null
+    }
+  }
+}
+```
+
+If there are any issues creating the private location, the `errors` array will contain objects with `description` and `type` fields explaining what went wrong.
+
+## Update a private location [#update-private-location]
+
+You can update an existing private location using the `syntheticsUpdatePrivateLocation` mutation. This allows you to modify the configuration of a private location that has already been created.
+
+<Callout variant="important">
+  If a location is shared and used by other accounts in your organization to run synthetic monitors, you cannot unshare this private location until those monitors are disabled.
+</Callout>
+
+### Input parameters
+
+<table>
+  <thead>
+    <tr>
+      <th>Parameter</th>
+      <th>Data Type</th>
+      <th>Is it Required?</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`guid`</td>
+      <td>String</td>
+      <td>Yes</td>
+      <td>The unique entity GUID of the private location you want to update.</td>
+    </tr>
+    <tr>
+      <td>`description`</td>
+      <td>String</td>
+      <td>No</td>
+      <td>The description of the private location.</td>
+    </tr>
+    <tr>
+      <td>`shared`</td>
+      <td>Boolean</td>
+      <td>No</td>
+      <td>Specifies whether the private location is shared across the organization.</td>
+    </tr>
+    <tr>
+      <td>`verifiedScriptExecution`</td>
+      <td>Boolean</td>
+      <td>Yes</td>
+      <td>If the value is true, the private location requires a password to edit.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Sample request
+
+```graphql
+mutation {
+  syntheticsUpdatePrivateLocation(
+    guid: "ENTITY_GUID",
+    description: "EnterYourDescription",
+    shared: false,
+    verifiedScriptExecution: true
+  ) {
+    description
+    verifiedScriptExecution
+    errors {
+      description
+      type
+    }
+  }
+}
+```
+
+### Sample response
+
+A successful response returns the updated fields and `null` for errors:
+
+```json
+{
+  "data": {
+    "syntheticsUpdatePrivateLocation": {
+      "description": "EnterYourDescription",
+      "verifiedScriptExecution": true,
+      "errors": null
+    }
+  }
+}
+```
+
+If there are any issues updating the private location, the `errors` array will contain objects with `description` and `type` fields explaining what went wrong.
+
+## Purge a private location job queue [#purge-private-location]
+
+You can clear the job queue for a private location using the `syntheticsPurgePrivateLocationQueue` mutation. This is useful when you need to remove a backlog of queued synthetic monitor jobs that may have accumulated due to performance issues or temporary connectivity problems.
+
+<Callout variant="tip">
+  Use this operation carefully as it will permanently remove all queued jobs. Jobs currently running will not be affected.
+</Callout>
+
+### Input parameters
+
+<table>
+  <thead>
+    <tr>
+      <th>Parameter</th>
+      <th>Data Type</th>
+      <th>Is it Required?</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`guid`</td>
+      <td>String</td>
+      <td>Yes</td>
+      <td>The unique identifier (GUID) of the private location whose job queue you want to purge.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Sample request
+
+```graphql
+mutation {
+  syntheticsPurgePrivateLocationQueue(
+    guid: "PRIVATE_LOCATION_ENTITY_GUID"
+  ) {
+    errors {
+      description
+      type
+    }
+  }
+}
+```
+
+### Sample response
+
+A successful response returns `null` for errors:
+
+```json
+{
+  "data": {
+    "syntheticsPurgePrivateLocationQueue": {
+      "errors": null
+    }
+  }
+}
+```
+
+If there are any issues purging the queue, the `errors` array will contain objects with `description` and `type` fields explaining what went wrong.
+
+## Delete a private location [#delete-private-location]
+
+When a private location is no longer needed, you can permanently remove it using the `syntheticsDeletePrivateLocation` mutation.
+
+<Callout variant="important">
+  Before deleting a private location, ensure no monitors are assigned to it. Deleting a private location that has active monitors assigned will cause those monitors to fail.
+</Callout>
+
+### Input parameters
+
+<table>
+  <thead>
+    <tr>
+      <th>Parameter</th>
+      <th>Data Type</th>
+      <th>Is it Required?</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`guid`</td>
+      <td>String</td>
+      <td>Yes</td>
+      <td>The unique entity GUID of the private location you want to delete.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Sample request
+
+```graphql
+mutation {
+  syntheticsDeletePrivateLocation(
+    guid: "ENTITY_GUID"
+  ) {
+    errors {
+      description
+      type
+    }
+  }
+}
+```
+
+### Sample response
+
+A successful response returns `null` for errors:
+
+```json
+{
+  "data": {
+    "syntheticsDeletePrivateLocation": {
+      "errors": null
+    }
+  }
+}
+```
+
+If there are any issues deleting the private location, the `errors` array will contain objects with `description` and `type` fields explaining what went wrong.