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"
            }
          }
        ]
      }
    }
  }
}

Get workspace by organization ID

The workspace query can also be used to find workspaces by organization ID instead of workspace ARI. This is useful when you have the organization ID but need to discover the associated workspace details.

Query:

1
2
query getWorkspaceByOrg($orgId: ID!) {
  shepherd {
    workspaceByOrgId(orgId: $orgId) {
      ari
    }
  }
}

Variables:

1
2
{ "orgId": "your-organization-id-here" }

Sample response:

1
2
{
  "data": {
    "shepherd": {
      "workspaceByOrgId": {
        "ari": "ari:cloud:beacon:f089901f-92e1-41a9-9381-31169581e82f:workspace/b67ab6ee-eca4-4b96-a6fa-31d4ad4606bb"
      }
    }
  }
}

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"
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    }
  }
}

Get a single alert by ARI

The alert.byAri query allows you to retrieve detailed information about a specific alert using its ARI. This is useful when you need to get detailed information about a particular alert, including supporting data and activity highlights.

Query:

1
2
query getAlertByAri($alertAri: ID!) {
  shepherd {
    alert {
      byAri(id: $alertAri) {
        ... on ShepherdAlert {
          id
          workspaceId
          status
          title
          type
          actor {
            __typename
            ... on ShepherdActor {
              aaid
              user {
                name
                accountId
                accountStatus
                picture
              }
            }
            ... on ShepherdAnonymousActor {
              ipAddress
            }
          }
          time {
            start
            end
          }
          customFields
          supportingData {
            highlight {
              ... on ShepherdActivityHighlight {
                action
                actor {
                  aaid
                  user {
                    name
                    accountStatus
                  }
                }
                subject {
                  ari
                  ati
                  containerAri
                }
                time {
                  start
                  end
                }
              }
            }
          }
        }
        ... on QueryError {
          message
          extensions {
            errorType
            ... on ShepherdGenericQueryErrorExtension {
              statusCode
              type
            }
          }
        }
      }
    }
  }
}

Variables:

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

Sample response:

1
2
{
  "data": {
    "shepherd": {
      "alert": {
        "byAri": {
          "id": "ari:cloud:beacon:1a11d016-8984-4c3e-b9ab-142dd06acb1b:alert/84d8e33f-139b-4ca4-b5cd-586a5d858a2f/67f42cd4f6e5bb72e88ae028",
          "workspaceId": "84d8e33f-139b-4ca4-b5cd-586a5d858a2f",
          "status": "UNTRIAGED",
          "title": "Sensitive data detected: IBAN",
          "type": "test",
          "actor": {
            "__typename": "ShepherdActor",
            "aaid": "655363:10c3b7d6-fc46-4eb6-af8c-08493b289adf",
            "user": {
              "name": "John Doe",
              "accountId": "655363:10c3b7d6-fc46-4eb6-af8c-08493b289adf",
              "accountStatus": "active",
              "picture": "https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/dummy-aaid/dummy-id/128"
            }
          },
          "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"
          },
          "supportingData": {
            "highlight": {
              "action": "UPDATE",
              "actor": {
                "aaid": "655363:10c3b7d6-fc46-4eb6-af8c-08493b289adf",
                "user": {
                  "name": "John Doe",
                  "accountStatus": "active"
                }
              },
              "subject": {
                "ari": "ari:cloud:jira:1a11d016-8984-4c3e-b9ab-142dd06acb1b:issue/10000",
                "ati": "jira-issue",
                "containerAri": "ari:cloud:jira:1a11d016-8984-4c3e-b9ab-142dd06acb1b:project/10001"
              },
              "time": {
                "start": "2025-04-07T19:51:46.505Z",
                "end": "2025-04-07T19:51:47.505Z"
              }
            }
          }
        }
      }
    }
  }
}

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": []
      }
    }
  }
}

Restore redacted content

The redaction.restore mutation can be used to restore redacted Jira content up to 30 days after the content is redacted. The redaction ID can be found in the Jira work item (more actions menu (•••) > Redactions). For additional information consult the GraphQL API documentation.

Mutation:

1
2
mutation restore($workspaceAri: ID!, $redactionId: ID!) {
  shepherd {
    redaction {
      restore(workspaceId: $workspaceAri, input: { redactionId: $redactionId }) {
        success
        errors {
          message
        }
      }
    }
  }
}

Variables:

1
2
{
  "workspaceAri": "your-workspace-ari-here",
  "redactionId": "redaction-id-from-jira"
}

Sample response:

1
2
{
  "data": {
    "shepherd": {
      "redaction": {
        "restore": {
          "success": true,
          "errors": []
        }
      }
    }
  }
}