API request examples

Get workspace details

The workspace query is a simple query that can be used to test that you have the correct workspaceAri string and GraphQL syntax. This is important because the workspace ARI is required for most queries. A workspace ARI typically takes the following format:

1
2
ari:cloud:beacon:{cloudId}:workspace/{workspaceId}

Run the query below to test your workspace ARI.

For additional information consult the GraphQL API documentation.

Query:

1
2
query getWorkspace($workspaceAri: ID!) {
  shepherd {
    workspace(id: $workspaceAri) {
      __typename
      ... on ShepherdWorkspaceConnection {
        edges {
          node {
            ... on ShepherdWorkspace {
              id
              cloudName
            }
          }
        }
      }
      ... on QueryError {
        message
        extensions {
          errorType
          ... on ShepherdGenericQueryErrorExtension {
            statusCode
            type
          }
        }
      }
    }
  }
}

Variables:

1
2
{ "workspaceAri": "your-workspace-ari-here" }

Sample response:

1
2
{
  "data": {
    "shepherd": {
      "workspace": {
        "__typename": "ShepherdWorkspaceConnection",
        "edges": [
          {
            "node": {
              "id": "ari:cloud:beacon:1a11d016-8984-4c3e-b9ab-142dd06acb1b:workspace/84d8e33f-139b-4ca4-b5cd-586a5d858a2f",
              "cloudName": "beacon-staging-with-fe"
            }
          }
        ]
      }
    }
  }
}

Listing Webhook, Slack, and MS Teams subscriptions

The subscriptions query will return information about any subscriptions configured for your Guard Detect workspace. For additional information consult the GraphQL API documentation.

Query:

1
2
fragment SubscriptionEdge on ShepherdSubscriptionConnection {
  edges {
    node {
      id
      status
      ... on ShepherdWebhookSubscription {
        callbackURL
        destinationType
      }
      ... on ShepherdSlackSubscription {
        teamId
        channelId
      }
    }
  }
}

query getSubscriptions($workspaceAri: ID!) {
  shepherd {
    subscriptions(workspaceId: $workspaceAri) {
      ... on ShepherdSubscriptionConnection {
        ...SubscriptionEdge
      }
      ... on QueryError {
        message
        extensions {
          errorType
          ... on ShepherdGenericQueryErrorExtension {
            statusCode
            type
          }
        }
      }
    }
  }
}

Variables:

1
2
{ "workspaceAri": "your-workspace-ari-here" }

Sample response:

1
2
{
  "data": {
    "shepherd": {
      "subscriptions": {
        "edges": [
          {
            "node": {
              "id": "ari:cloud:beacon:1a11d016-8984-4c3e-b9ab-142dd06acb1b:subscription/84d8e33f-139b-4ca4-b5cd-586a5d858a2f/645d2ddc81c1b2b66a655e82",
              "status": "INACTIVE",
              "callbackURL": "https://piteams.webhook.office.com/webhookb2/8395d62b-8141-48d0-ac4e-23fe4ffda107@f9bc1ba0-fc67-4045-b1af-0969c406b55f/IncomingWebhook/c42d4d5c58e04680bb16b5cba1167ae0/5bc17da5-c45a-4292-94fe-552e977ce74f",
              "destinationType": "MICROSOFT_TEAMS"
            }
          },
          {
            "node": {
              "id": "ari:cloud:beacon:1a11d016-8984-4c3e-b9ab-142dd06acb1b:subscription/84d8e33f-139b-4ca4-b5cd-586a5d858a2f/66c395e2587d565028fce5f9",
              "status": "ACTIVE",
              "teamId": "TFCUTJ123",
              "channelId": "C03TVV8B123"
            }
          },
          {
            "node": {
              "id": "ari:cloud:beacon:1a11d016-8984-4c3e-b9ab-142dd06acb1b:subscription/84d8e33f-139b-4ca4-b5cd-586a5d858a2f/67ec1da2a1sdff99c4889fa88",
              "status": "ACTIVE",
              "callbackURL": "https://webhook.site/a5d3b943-ed06-4975-be55-ae3198dc14f4",
              "destinationType": "DEFAULT"
            }
          }
        ]
      }
    }
  }
}

Get the latest 10 alerts for a workspace

The alert query will return the most recent alerts for your Guard Detect workspace. For a full list of available attributes consult the GraphQL API documentation.

Query:

1
2
query getAlertsByWorkspace($workspaceAri: ID!) {
  shepherd {
    alert {
      byWorkspace(workspaceId: $workspaceAri, first: 10) {
        ... on ShepherdAlertsConnection {
          edges {
            node {
              id
              type
              title
              status
              type
              actor {
                __typename
                ... on ShepherdActor {
                  aaid
                  user {
                    accountStatus
                  }
                }
                ... on ShepherdAnonymousActor {
                  ipAddress
                }
              }
              time {
                start
                end
              }
              customFields
            }
          }
        }
        ... on QueryError {
          message
          extensions {
            errorType
            ... on ShepherdGenericQueryErrorExtension {
              statusCode
              type
            }
          }
        }
      }
    }
  }
}

Variables:

1
2
{ "workspaceAri": "your-workspace-ari-here" }

Sample response:

1
2
{
  "data": {
    "shepherd": {
      "alert": {
        "byWorkspace": {
          "edges": [
            {
              "node": {
                "id": "ari:cloud:beacon:1a11d016-8984-4c3e-b9ab-142dd06acb1b:alert/84d8e33f-139b-4ca4-b5cd-586a5d858a2f/67f59a35802a76b6d5911a73",
                "type": "user-revoked-role",
                "title": "Organization admin removed",
                "status": "UNTRIAGED",
                "actor": {
                  "__typename": "ShepherdActor",
                  "aaid": "d1819018-ac64-4489-9826-fe47f0af673f",
                  "user": {
                    "accountStatus": "active"
                  }
                },
                "time": {
                  "start": "2025-04-08T21:50:45.299158226Z",
                  "end": null
                },
                "customFields": {
                  "auditLogEventId": "122b6c04-753a-4dbd-8a21-6b3cf5aa8214",
                  "userAri": "ari:cloud:identity::user/d1819018-ac64-4489-9826-fe47f0af673f"
                }
              }
            },
            {
              "node": {
                "id": "ari:cloud:beacon:1a11d016-8984-4c3e-b9ab-142dd06acb1b:alert/84d8e33f-139b-4ca4-b5cd-586a5d858a2f/67f42cd4f6e5bb72e88ae028",
                "type": "jira-data-discovery-iban",
                "title": "Sensitive data detected: IBAN",
                "status": "UNTRIAGED",
                "actor": {
                  "__typename": "ShepherdActor",
                  "aaid": "655363:10c3b7d6-fc46-4eb6-af8c-08493b289adf",
                  "user": {
                    "accountStatus": "active"
                  }
                },
                "time": {
                  "start": "2025-04-07T19:51:46.505Z",
                  "end": null
                },
                "customFields": {
                  "auditLogEventId": "d1819018-ac64-4489-9826-fe47f0af673f",
                  "jiraProjectAri": "ari:cloud:jira:1a11d016-8984-4c3e-b9ab-142dd06acb1b:project/10001",
                  "contentAri": "ari:cloud:jira:1a11d016-8984-4c3e-b9ab-142dd06acb1b:issue/10000",
                  "versionTimestamp": "2025-04-07T19:51:46.505Z",
                  "detectedContent": [
                    {
                      "reason": "International Bank Account Numbers (IBAN)",
                      "pointer": {
                        "from": {
                          "index": 0,
                          "pointer": "/content/1/content/0/text"
                        },
                        "to": {
                          "index": 28,
                          "pointer": "/content/1/content/0/text"
                        }
                      },
                      "isUnredactable": false,
                      "entityType": "IBAN_CODE",
                      "id": "6ce0453a-7824-4cd1-b65f-e5df6c54f5ea",
                      "hash": "wG0lh+rrn33sKHh74qZPJnIxsegNPFf+bw/8zozCLcY=",
                      "fieldId": "description"
                    },
                    {
                      "reason": "International Bank Account Numbers (IBAN)",
                      "pointer": {
                        "from": {
                          "index": 33,
                          "pointer": "/content/1/content/0/text"
                        },
                        "to": {
                          "index": 57,
                          "pointer": "/content/1/content/0/text"
                        }
                      },
                      "isUnredactable": false,
                      "entityType": "IBAN_CODE",
                      "id": "59031f75-0490-4b73-aab8-bc391e04d271",
                      "hash": "ozN0wTCXHtYbsbyXN7c7GfoZYppPPquqTDs7umEPMD0=",
                      "fieldId": "description"
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    }
  }
}

Update an alert status

The updateAlert mutation can be used to set the status or assignee of an alert. For additional information consult the GraphQL API documentation.

Mutation:

1
2
mutation updateAlert($alertAri: ID!, $status: ShepherdAlertStatus) {
  shepherd {
    updateAlert(id: $alertAri, input: { status: $status }) {
      success
      node {
        id
        title
        status
      }
      errors {
        message
        extensions {
          ... on ShepherdGenericMutationErrorExtension {
            statusCode
            type
          }
        }
      }
    }
  }
}

Variables:

1
2
{
  "alertAri": "ari:cloud:beacon:1a11d016-8984-4c3e-b9ab-142dd06acb1b:alert/84d8e33f-139b-4ca4-b5cd-586a5d858a2f/67f42cd4f6e5bb72e88ae028",
  "status": "IN_PROGRESS"
}

Sample response:

1
2
{
  "data": {
    "shepherd": {
      "updateAlert": {
        "success": true,
        "node": {
          "id": "ari:cloud:beacon:1a11d016-8984-4c3e-b9ab-142dd06acb1b:alert/84d8e33f-139b-4ca4-b5cd-586a5d858a2f/67f42cd4f6e5bb72e88ae028",
          "title": "Organization admin removed",
          "status": "IN_PROGRESS"
        },
        "errors": []
      }
    }
  }
}