DLP APIs - Native SaaS Apps

The native SaaS app APIs can be utilized by customers using Nightfall’s SaaS apps, supported natively, to fetch violations, search violations by app meta-data attributes, and fetch findings within violations. These DLP APIs do not provide access to violations for apps scanned via the developer platform. These APIs require you to create an API key as outlined in the Getting Started with the Developer Platform section. However, to use these APIs, you need not create any detectors, detection rules, and policies in the developer platform.

If you are using Nightfall SaaS apps, you can use APIs to fetch violations, search through the violations, and fetch specific findings within the Violations. To scan data in any custom apps or cloud infrastructure services like AWS S3, you must use the APIs in the DLP APIs - Firewall for AI Platform section.

Fetch violations

get

Fetch a list of violations for a period

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

createdAfterintegerOptional

Unix timestamp in seconds, filters records created ≥ the value, defaults to -90 days UTC

createdBeforeintegerOptional

Unix timestamp in seconds, filters records created < the value, defaults to end of the current day UTC

updatedAfterintegerOptional

Unix timestamp in seconds, filters records updated > the value

limitinteger · max: 100Optional

The maximum number of records to be returned in the response

Default: 50

pageTokenstringOptional

Cursor for getting the next page of results

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/violations

HTTPcURLJavaScriptPython

GET /dlp/v1/violations HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "violations": [
    {
      "id": "text",
      "integration": "SLACK",
      "createdAt": 1,
      "updatedAt": 1,
      "possibleActions": [
        "ACKNOWLEDGE"
      ],
      "state": "ACTIVE",
      "resourceLink": "text",
      "metadata": {
        "slackMetadata": {
          "location": "text",
          "locationType": "text",
          "username": "text",
          "userID": "text",
          "messagePermalink": "text",
          "locationMembers": [
            "text"
          ],
          "locationMemberCount": 1,
          "channelID": "text",
          "workspaceName": "text"
        },
        "confluenceMetadata": {
          "itemName": "text",
          "itemType": "text",
          "isArchived": true,
          "createdAt": 1,
          "updatedAt": 1,
          "labels": [
            "text"
          ],
          "spaceName": "text",
          "spaceKey": "text",
          "spaceNameLink": "text",
          "parentPageName": "text",
          "authorName": "text",
          "authorEmail": "text",
          "authorNameLink": "text",
          "permalink": "text",
          "confluenceID": "text",
          "confluenceUserID": "text",
          "itemVersion": 1,
          "parentPageID": "text",
          "parentVersion": 1
        },
        "gdriveMetadata": {
          "fileID": "text",
          "fileName": "text",
          "fileType": "text",
          "fileSize": "text",
          "fileLink": "text",
          "permissionSetting": "text",
          "sharingExternalUsers": [
            "text"
          ],
          "sharingInternalUsers": [
            "text"
          ],
          "canViewersDownload": true,
          "fileOwner": "text",
          "isInTrash": true,
          "createdAt": 1,
          "updatedAt": 1,
          "drive": "text",
          "updatedBy": "text"
        },
        "jiraMetadata": {
          "projectName": "text",
          "ticketNumber": "text",
          "projectType": "text",
          "issueID": "text",
          "projectLink": "text",
          "ticketLink": "text",
          "commentLink": "text",
          "attachmentLink": "text"
        },
        "githubMetadata": {
          "branchName": "text",
          "organization": "text",
          "repository": "text",
          "authorEmail": "text",
          "authorUsername": "text",
          "createdAt": 1,
          "isRepoPrivate": true,
          "filePath": "text",
          "githubPermalink": "text",
          "repositoryOwner": "text",
          "githubRepoLink": "text"
        },
        "salesforceMetadata": {
          "orgName": "text",
          "recordID": "text",
          "objectName": "text",
          "contentType": "text",
          "userID": "text",
          "userName": "text",
          "updatedAt": 1,
          "fields": [
            "text"
          ],
          "fileType": "text",
          "attachmentLink": "text",
          "attachmentName": "text",
          "objectLink": "text"
        },
        "zendeskMetadata": {
          "ticketStatus": "text",
          "ticketTitle": "text",
          "ticketRequestor": "text",
          "ticketGroupAssignee": "text",
          "ticketAgentAssignee": "text",
          "currentUserRole": "text",
          "ticketID": 1,
          "ticketFollowers": [
            "text"
          ],
          "ticketTags": "text",
          "createdAt": 1,
          "UpdatedAt": 1,
          "location": "text",
          "subLocation": "text",
          "ticketCommentID": 1,
          "ticketGroupID": 1,
          "ticketGroupLink": "text",
          "ticketAgentID": 1,
          "ticketAgentLink": "text",
          "ticketEvent": "text",
          "userRole": "text",
          "attachmentName": "text",
          "attachmentLink": "text"
        },
        "notionMetadata": {
          "createdBy": "text",
          "updatedBy": "text",
          "workspaceName": "text",
          "workspaceLink": "text",
          "pageID": "text",
          "pageTitle": "text",
          "createdAt": 1,
          "updatedAt": 1,
          "privatePageLink": "text",
          "publicPageLink": "text",
          "sharedExternally": true,
          "attachmentID": "text"
        },
        "browserMetadata": {
          "location": "text",
          "subLocation": "text",
          "browserName": "text",
          "userComment": "text"
        },
        "m365TeamsMetadata": {
          "teamName": "text",
          "tenantID": "text",
          "tenantDomain": "text",
          "teamID": "text",
          "teamVisibility": "text",
          "teamWebURL": "text",
          "channelID": "text",
          "channelName": "text",
          "channelType": "text",
          "channelWebURL": "text",
          "messageID": "text",
          "createdAt": 1,
          "updatedAt": 1,
          "chatMessageSender": "text",
          "userID": "text",
          "userPrincipalName": "text",
          "attachments": [
            {
              "attachmentID": "text",
              "attachmentName": "text",
              "attachmentURL": "text"
            }
          ],
          "chatMessageImportance": "text",
          "chatID": "text",
          "chatType": "text",
          "chatTopic": "text",
          "chatParticipants": [
            {
              "userID": "text",
              "email": "text",
              "displayName": "text"
            }
          ]
        },
        "m365OnedriveMetadata": {
          "tenantID": "text",
          "tenantDomain": "text",
          "driveItemID": "text",
          "driveItemName": "text",
          "driveItemURL": "text",
          "driveItemMimeType": "text",
          "driveItemSize": 1,
          "parentPath": "text",
          "createdByID": "text",
          "updatedByEmail": "text",
          "updatedByID": "text",
          "updatedByName": "text",
          "createdAt": 1,
          "updatedAt": 1,
          "specialFolderName": "text",
          "driveID": "text",
          "driveOwnerName": "text",
          "driveOwnerEmail": "text",
          "driveOwnerID": "text"
        },
        "inlineEmailMetadata": {
          "domain": "text",
          "user_name": "text",
          "from": "text",
          "to": [
            "text"
          ],
          "cc": [
            "text"
          ],
          "bcc": [
            "text"
          ],
          "subject": "text",
          "sent_at": 1,
          "thread_id": "text",
          "attachment_name": "text",
          "attachment_type": "text"
        }
      },
      "fileDetails": {
        "fileName": "text",
        "mimeType": "text",
        "permalink": "text"
      },
      "policyUUIDs": [
        "text"
      ],
      "detectionRuleUUIDs": [
        "text"
      ],
      "detectorUUIDs": [
        "text"
      ],
      "risk": "UNSPECIFIED",
      "riskSource": "NIGHTFALL",
      "riskScore": 1,
      "userInfo": {
        "username": "text",
        "userEmail": "text"
      }
    }
  ],
  "nextPageToken": "text"
}

Fetch violation

get

Fetch a violation by ID

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

violationIdstring · uuidRequired

The UUID of the violation to fetch

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

404

Violation does not exist

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/violations/{violationId}

HTTPcURLJavaScriptPython

GET /dlp/v1/violations/{violationId} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "integration": "SLACK",
  "createdAt": 1,
  "updatedAt": 1,
  "possibleActions": [
    "ACKNOWLEDGE"
  ],
  "state": "ACTIVE",
  "resourceLink": "text",
  "metadata": {
    "slackMetadata": {
      "location": "text",
      "locationType": "text",
      "username": "text",
      "userID": "text",
      "messagePermalink": "text",
      "locationMembers": [
        "text"
      ],
      "locationMemberCount": 1,
      "channelID": "text",
      "workspaceName": "text"
    },
    "confluenceMetadata": {
      "itemName": "text",
      "itemType": "text",
      "isArchived": true,
      "createdAt": 1,
      "updatedAt": 1,
      "labels": [
        "text"
      ],
      "spaceName": "text",
      "spaceKey": "text",
      "spaceNameLink": "text",
      "parentPageName": "text",
      "authorName": "text",
      "authorEmail": "text",
      "authorNameLink": "text",
      "permalink": "text",
      "confluenceID": "text",
      "confluenceUserID": "text",
      "itemVersion": 1,
      "parentPageID": "text",
      "parentVersion": 1
    },
    "gdriveMetadata": {
      "fileID": "text",
      "fileName": "text",
      "fileType": "text",
      "fileSize": "text",
      "fileLink": "text",
      "permissionSetting": "text",
      "sharingExternalUsers": [
        "text"
      ],
      "sharingInternalUsers": [
        "text"
      ],
      "canViewersDownload": true,
      "fileOwner": "text",
      "isInTrash": true,
      "createdAt": 1,
      "updatedAt": 1,
      "drive": "text",
      "updatedBy": "text"
    },
    "jiraMetadata": {
      "projectName": "text",
      "ticketNumber": "text",
      "projectType": "text",
      "issueID": "text",
      "projectLink": "text",
      "ticketLink": "text",
      "commentLink": "text",
      "attachmentLink": "text"
    },
    "githubMetadata": {
      "branchName": "text",
      "organization": "text",
      "repository": "text",
      "authorEmail": "text",
      "authorUsername": "text",
      "createdAt": 1,
      "isRepoPrivate": true,
      "filePath": "text",
      "githubPermalink": "text",
      "repositoryOwner": "text",
      "githubRepoLink": "text"
    },
    "salesforceMetadata": {
      "orgName": "text",
      "recordID": "text",
      "objectName": "text",
      "contentType": "text",
      "userID": "text",
      "userName": "text",
      "updatedAt": 1,
      "fields": [
        "text"
      ],
      "fileType": "text",
      "attachmentLink": "text",
      "attachmentName": "text",
      "objectLink": "text"
    },
    "zendeskMetadata": {
      "ticketStatus": "text",
      "ticketTitle": "text",
      "ticketRequestor": "text",
      "ticketGroupAssignee": "text",
      "ticketAgentAssignee": "text",
      "currentUserRole": "text",
      "ticketID": 1,
      "ticketFollowers": [
        "text"
      ],
      "ticketTags": "text",
      "createdAt": 1,
      "UpdatedAt": 1,
      "location": "text",
      "subLocation": "text",
      "ticketCommentID": 1,
      "ticketGroupID": 1,
      "ticketGroupLink": "text",
      "ticketAgentID": 1,
      "ticketAgentLink": "text",
      "ticketEvent": "text",
      "userRole": "text",
      "attachmentName": "text",
      "attachmentLink": "text"
    },
    "notionMetadata": {
      "createdBy": "text",
      "updatedBy": "text",
      "workspaceName": "text",
      "workspaceLink": "text",
      "pageID": "text",
      "pageTitle": "text",
      "createdAt": 1,
      "updatedAt": 1,
      "privatePageLink": "text",
      "publicPageLink": "text",
      "sharedExternally": true,
      "attachmentID": "text"
    },
    "browserMetadata": {
      "location": "text",
      "subLocation": "text",
      "browserName": "text",
      "userComment": "text"
    },
    "m365TeamsMetadata": {
      "teamName": "text",
      "tenantID": "text",
      "tenantDomain": "text",
      "teamID": "text",
      "teamVisibility": "text",
      "teamWebURL": "text",
      "channelID": "text",
      "channelName": "text",
      "channelType": "text",
      "channelWebURL": "text",
      "messageID": "text",
      "createdAt": 1,
      "updatedAt": 1,
      "chatMessageSender": "text",
      "userID": "text",
      "userPrincipalName": "text",
      "attachments": [
        {
          "attachmentID": "text",
          "attachmentName": "text",
          "attachmentURL": "text"
        }
      ],
      "chatMessageImportance": "text",
      "chatID": "text",
      "chatType": "text",
      "chatTopic": "text",
      "chatParticipants": [
        {
          "userID": "text",
          "email": "text",
          "displayName": "text"
        }
      ]
    },
    "m365OnedriveMetadata": {
      "tenantID": "text",
      "tenantDomain": "text",
      "driveItemID": "text",
      "driveItemName": "text",
      "driveItemURL": "text",
      "driveItemMimeType": "text",
      "driveItemSize": 1,
      "parentPath": "text",
      "createdByID": "text",
      "updatedByEmail": "text",
      "updatedByID": "text",
      "updatedByName": "text",
      "createdAt": 1,
      "updatedAt": 1,
      "specialFolderName": "text",
      "driveID": "text",
      "driveOwnerName": "text",
      "driveOwnerEmail": "text",
      "driveOwnerID": "text"
    },
    "inlineEmailMetadata": {
      "domain": "text",
      "user_name": "text",
      "from": "text",
      "to": [
        "text"
      ],
      "cc": [
        "text"
      ],
      "bcc": [
        "text"
      ],
      "subject": "text",
      "sent_at": 1,
      "thread_id": "text",
      "attachment_name": "text",
      "attachment_type": "text"
    }
  },
  "fileDetails": {
    "fileName": "text",
    "mimeType": "text",
    "permalink": "text"
  },
  "policyUUIDs": [
    "text"
  ],
  "detectionRuleUUIDs": [
    "text"
  ],
  "detectorUUIDs": [
    "text"
  ],
  "risk": "UNSPECIFIED",
  "riskSource": "NIGHTFALL",
  "riskScore": 1,
  "userInfo": {
    "username": "text",
    "userEmail": "text"
  }
}

Search violations

get

Fetch a list of violations based on some filters

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

createdAfterintegerOptional

Unix timestamp in seconds, filters records created ≥ the value, defaults to -90 days UTC

createdBeforeintegerOptional

Unix timestamp in seconds, filters records created < the value, defaults to end of the current day UTC

updatedAfterintegerOptional

Unix timestamp in seconds, filters records updated > the value

limitinteger · max: 100Optional

The maximum number of records to be returned in the response

Default: 50

pageTokenstringOptional

Cursor for getting the next page of results

sortstring · enumOptional

Sort key and direction, defaults to descending order by creation time

Default: TIME_DESCPossible values:

querystringRequired

The query containing filter clauses

Search query language

Query structure and terminology

A query clause consists of a field followed by an operator followed by a value:

term	value
clause	user_email:"[email protected]"
field	user_email
operator	:
value	[email protected]

You can combine multiple query clauses in a search by separating them with a space.

Field types, substring matching, and numeric comparators

Every search field supports exact matching with a :. Certain fields such as user_email and user_name support substring matching.

Quotes

You may use quotation marks around string values. Quotation marks are required in case the value contains spaces. For example:

• user_mail:[email protected]
• user_name:"John Doe"

Special Characters

+ - && || ! ( ) { } [ ] ^ " ~ * ? : are special characters need to be escaped using \. For example:

• a value like (1+1):2 should be searched for using \(1\+1)\:2

Search Syntax

The following table lists the syntax that you can use to construct a query.

SYNTAX	USAGE	DESCRIPTION	EXAMPLES
:	field:value	Exact match operator (case insensitive)	state:"pending" returns records where the currency is exactly "PENDING" in a case-insensitive comparison
(space)	field1:value1 field2:value2	The query returns only records that match both clauses	state:active slack.channel_name:general
OR	field:(value1 OR value2)	The query returns records that match either of the values (case insensitive)	state:(active OR pending)

Query Fields

param	description
state	the violation states to filter on
user_email	the emails of users updating the resource resulting in the violation
user_name	the usernames of users updating the resource resulting in the violation
integration_name	the integration to filter on
confidence	one or more likelihoods/confidences
policy_id	one or more policy IDs
detection_rule_id	one or more detection rule IDs
detector_id	one or more detector IDs
risk_label	the risk label to filter on
risk_source	the risk determination source to filter on
slack.channel_name	the slack channel names to filter on
slack.channel_id	the slack channel IDs to filter on
slack.workspace	the slack workspaces to filter on
confluence.parent_page_name	the names of the parent pages in confluence to filter on
confluence.space_name	the names of the spaces in confluence to filter on
gdrive.drive	the drive names in gdrive to filter on
jira.project_name	the jira project names to filter on
jira.ticket_number	the jira ticket numbers to filter on
salesforce.org_name	the salesforce organization names to filter on
salesforce.object	the salesforce object names to filter on
salesforce.record_id	the salesforce record IDs to filter on
github.author_email	the github author emails to filter on
github.branch	the github branches to filter on
github.commit	the github commit ids to filter on
github.org	the github organizations to filter on
github.repository	the github repositories to filter on
github.repository_owner	the github repository owners to filter on
teams.team_name	the m365 teams team names to filter on
teams.channel_name	the m365 teams channels to filter on
teams.channel_type	the m365 teams channel types to filter on
teams.team_sensitivity	the m365 teams sensitivities to filter on
teams.sender	the m365 teams senders to filter on
teams.msg_importance	the m365 teams importance to filter on
teams.msg_attachment	the m365 teams attachment names to filter on
teams.chat_id	the m365 teams chat ID to filter on
teams.chat_type	the m365 teams chat type to filter on
teams.chat_topic	the m365 teams chat topic to filter on
teams.chat_participant	the m365 teams chat participant's display name to filter on
onedrive.drive_owner	drive owner's display name to filter on
onedrive.drive_owner_email	drive owner's email to filter on
onedrive.file_name	the file name to filter on
onedrive.created_by	the m365 user, who created the file in the drive, display name to filter on
onedrive.created_by_email	the m365 users, who created the file in the drive, email to filter on
onedrive.modified_by	the m365 users, who last modified the file in the drive, display name to filter on
onedrive.modified_by_email	the m365 users, who last modified the file in the drive, email to filter on
zendesk.ticket_status	the zendesk ticket status to filter on
zendesk.ticket_title	the zendesk ticket titles to filter on
zendesk.ticket_group_assignee	the zendesk ticket assignee groups to filter on
zendesk.current_user_role	the zendesk ticket current assignee user's roles to filter on
notion.created_by	the names of the users creating a resource in notion to filter on
notion.last_edited_by	the names of the users editing a resource in notion to filter on
notion.page_title	the page names in notion to filter on
notion.workspace_name	the workspace names in notion to filter on
gmail.user_name	the names of the sender to filter on
gmail.from	the email of sender to filter on
gmail.to	the email or name of recipients to filter on
gmail.cc	the email or name of cc to filter on
gmail.bcc	the email or name of bcc to filter on
gmail.thread_id	the thread id of email to filter on
gmail.subject	the subject of email to filter on
gmail.attachment_name	the name of attachment to filter on
gmail.attachment_type	the type of attachment to filter on
last_actioned_by	the entity that performed the last action on the violation, can be one of NIGHTFALL, ADMIN or END_USER

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/violations/search

HTTPcURLJavaScriptPython

GET /dlp/v1/violations/search?query=text HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "violations": [
    {
      "id": "text",
      "integration": "SLACK",
      "createdAt": 1,
      "updatedAt": 1,
      "possibleActions": [
        "ACKNOWLEDGE"
      ],
      "state": "ACTIVE",
      "resourceLink": "text",
      "metadata": {
        "slackMetadata": {
          "location": "text",
          "locationType": "text",
          "username": "text",
          "userID": "text",
          "messagePermalink": "text",
          "locationMembers": [
            "text"
          ],
          "locationMemberCount": 1,
          "channelID": "text",
          "workspaceName": "text"
        },
        "confluenceMetadata": {
          "itemName": "text",
          "itemType": "text",
          "isArchived": true,
          "createdAt": 1,
          "updatedAt": 1,
          "labels": [
            "text"
          ],
          "spaceName": "text",
          "spaceKey": "text",
          "spaceNameLink": "text",
          "parentPageName": "text",
          "authorName": "text",
          "authorEmail": "text",
          "authorNameLink": "text",
          "permalink": "text",
          "confluenceID": "text",
          "confluenceUserID": "text",
          "itemVersion": 1,
          "parentPageID": "text",
          "parentVersion": 1
        },
        "gdriveMetadata": {
          "fileID": "text",
          "fileName": "text",
          "fileType": "text",
          "fileSize": "text",
          "fileLink": "text",
          "permissionSetting": "text",
          "sharingExternalUsers": [
            "text"
          ],
          "sharingInternalUsers": [
            "text"
          ],
          "canViewersDownload": true,
          "fileOwner": "text",
          "isInTrash": true,
          "createdAt": 1,
          "updatedAt": 1,
          "drive": "text",
          "updatedBy": "text"
        },
        "jiraMetadata": {
          "projectName": "text",
          "ticketNumber": "text",
          "projectType": "text",
          "issueID": "text",
          "projectLink": "text",
          "ticketLink": "text",
          "commentLink": "text",
          "attachmentLink": "text"
        },
        "githubMetadata": {
          "branchName": "text",
          "organization": "text",
          "repository": "text",
          "authorEmail": "text",
          "authorUsername": "text",
          "createdAt": 1,
          "isRepoPrivate": true,
          "filePath": "text",
          "githubPermalink": "text",
          "repositoryOwner": "text",
          "githubRepoLink": "text"
        },
        "salesforceMetadata": {
          "orgName": "text",
          "recordID": "text",
          "objectName": "text",
          "contentType": "text",
          "userID": "text",
          "userName": "text",
          "updatedAt": 1,
          "fields": [
            "text"
          ],
          "fileType": "text",
          "attachmentLink": "text",
          "attachmentName": "text",
          "objectLink": "text"
        },
        "zendeskMetadata": {
          "ticketStatus": "text",
          "ticketTitle": "text",
          "ticketRequestor": "text",
          "ticketGroupAssignee": "text",
          "ticketAgentAssignee": "text",
          "currentUserRole": "text",
          "ticketID": 1,
          "ticketFollowers": [
            "text"
          ],
          "ticketTags": "text",
          "createdAt": 1,
          "UpdatedAt": 1,
          "location": "text",
          "subLocation": "text",
          "ticketCommentID": 1,
          "ticketGroupID": 1,
          "ticketGroupLink": "text",
          "ticketAgentID": 1,
          "ticketAgentLink": "text",
          "ticketEvent": "text",
          "userRole": "text",
          "attachmentName": "text",
          "attachmentLink": "text"
        },
        "notionMetadata": {
          "createdBy": "text",
          "updatedBy": "text",
          "workspaceName": "text",
          "workspaceLink": "text",
          "pageID": "text",
          "pageTitle": "text",
          "createdAt": 1,
          "updatedAt": 1,
          "privatePageLink": "text",
          "publicPageLink": "text",
          "sharedExternally": true,
          "attachmentID": "text"
        },
        "browserMetadata": {
          "location": "text",
          "subLocation": "text",
          "browserName": "text",
          "userComment": "text"
        },
        "m365TeamsMetadata": {
          "teamName": "text",
          "tenantID": "text",
          "tenantDomain": "text",
          "teamID": "text",
          "teamVisibility": "text",
          "teamWebURL": "text",
          "channelID": "text",
          "channelName": "text",
          "channelType": "text",
          "channelWebURL": "text",
          "messageID": "text",
          "createdAt": 1,
          "updatedAt": 1,
          "chatMessageSender": "text",
          "userID": "text",
          "userPrincipalName": "text",
          "attachments": [
            {
              "attachmentID": "text",
              "attachmentName": "text",
              "attachmentURL": "text"
            }
          ],
          "chatMessageImportance": "text",
          "chatID": "text",
          "chatType": "text",
          "chatTopic": "text",
          "chatParticipants": [
            {
              "userID": "text",
              "email": "text",
              "displayName": "text"
            }
          ]
        },
        "m365OnedriveMetadata": {
          "tenantID": "text",
          "tenantDomain": "text",
          "driveItemID": "text",
          "driveItemName": "text",
          "driveItemURL": "text",
          "driveItemMimeType": "text",
          "driveItemSize": 1,
          "parentPath": "text",
          "createdByID": "text",
          "updatedByEmail": "text",
          "updatedByID": "text",
          "updatedByName": "text",
          "createdAt": 1,
          "updatedAt": 1,
          "specialFolderName": "text",
          "driveID": "text",
          "driveOwnerName": "text",
          "driveOwnerEmail": "text",
          "driveOwnerID": "text"
        },
        "inlineEmailMetadata": {
          "domain": "text",
          "user_name": "text",
          "from": "text",
          "to": [
            "text"
          ],
          "cc": [
            "text"
          ],
          "bcc": [
            "text"
          ],
          "subject": "text",
          "sent_at": 1,
          "thread_id": "text",
          "attachment_name": "text",
          "attachment_type": "text"
        }
      },
      "fileDetails": {
        "fileName": "text",
        "mimeType": "text",
        "permalink": "text"
      },
      "policyUUIDs": [
        "text"
      ],
      "detectionRuleUUIDs": [
        "text"
      ],
      "detectorUUIDs": [
        "text"
      ],
      "risk": "UNSPECIFIED",
      "riskSource": "NIGHTFALL",
      "riskScore": 1,
      "userInfo": {
        "username": "text",
        "userEmail": "text"
      }
    }
  ],
  "nextPageToken": "text"
}

Fetch violation findings

get

Get findings for a specific violation

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

violationIdstring · uuidRequired

The UUID of the violation

Query parameters

pageTokenstringOptional

Cursor for getting the next page of results

limitinteger · int32 · max: 1000Optional

Number of findings to fetch in one page (max 1000)

Default: 1000

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

404

Violation does not exist

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/violations/{violationId}/findings

HTTPcURLJavaScriptPython

GET /dlp/v1/violations/{violationId}/findings HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "findings": [
    {
      "id": "text",
      "detectorUUID": "text",
      "subDetectorUUID": "text",
      "confidence": "text",
      "redactedSensitiveText": "text",
      "redactedContext": {
        "beforeContext": "text",
        "afterContext": "text"
      },
      "redactedLocation": {
        "byteRange": {
          "start": 1,
          "end": 1
        },
        "lineRange": {
          "start": 1,
          "end": 1
        }
      },
      "metadata": {
        "apiKeyMetaData": {
          "status": "UNVERIFIED",
          "kind": "UNSPECIFIED",
          "description": "text"
        }
      },
      "subLocation": "text",
      "annotationUUID": "text"
    }
  ],
  "nextPageToken": "text"
}

Take an action on Violations

post

Perform an action on a list of violations. If an action can't be performed on a violation, that violation is ignored. Depending on the action, it could be processed immediately or queued.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

violationUUIDsstring · uuid[]Required

The UUIDs of the violations to perform the action on

actionstring · enumRequired

The action to perform on the violations

Possible values:

Responses

200

Successful response (processed immediately)

application/json

202

Accepted response (queued for processing)

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

post

/violations/actions

HTTPcURLJavaScriptPython

POST /dlp/v1/violations/actions HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "violationUUIDs": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "action": "ACKNOWLEDGE"
}

{
  "submitted": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Fetch annotation

get

Fetch an annotation by ID

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

annotationIdstring · uuidRequired

The UUID of the annotation to fetch

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

404

Annotation does not exist

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/annotations/{annotationId}

HTTPcURLJavaScriptPython

GET /dlp/v1/annotations/{annotationId} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "DETECTOR_FALSE_POSITIVE",
  "comment": "text",
  "autoApply": true
}

Annotate finding

post

Annotate a finding

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

findingIdstring · uuidRequired

The UUID of the finding to annotate

Body

application/json

typestring · enumRequired

The annotation type

Possible values:

commentstringOptional

The comment to add to the annotation

autoApplybooleanOptional

Whether the annotation applies to all findings of this sensitive data (defaults to true)

Default: true

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

409

Finding already annotated

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

post

/findings/{findingId}/annotate

HTTPcURLJavaScriptPython

POST /dlp/v1/findings/{findingId}/annotate HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 68

{
  "type": "DETECTOR_FALSE_POSITIVE",
  "comment": "text",
  "autoApply": true
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "DETECTOR_FALSE_POSITIVE",
  "comment": "text",
  "autoApply": true
}

Remove finding annotation

post

Remove the annotation for a finding

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

findingIdstring · uuidRequired

The UUID of the finding to unannotate

Responses

200

Successful response (even if annotation does not exist)

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

post

/findings/{findingId}/unannotate

HTTPcURLJavaScriptPython

POST /dlp/v1/findings/{findingId}/unannotate HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Fetch violation activity feed

get

Fetch the activity feed for a specific violation

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

violationIdstring · uuidRequired

The UUID of the violation

Query parameters

limitinteger · int32 · max: 100Optional

Number of activity items to fetch in one page

Default: 50

createdAfterintegerOptional

Unix timestamp in seconds, filters activity created > the value

createdBeforeintegerOptional

Unix timestamp in seconds, filters activity created < the value

descendingbooleanOptional

Whether to sort results in descending order (default false)

Default: false

pageTokenstringOptional

Cursor for getting the next page of results

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

404

Violation does not exist

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/violations/{violationId}/activity

HTTPcURLJavaScriptPython

GET /dlp/v1/violations/{violationId}/activity HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "activities": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "message": "text",
      "timestamp": 1,
      "type": "CREATION",
      "data": {
        "action": "ACKNOWLEDGE",
        "userUUID": "123e4567-e89b-12d3-a456-426614174000",
        "userName": "text",
        "userEmail": "text",
        "receiverEmail": "text",
        "actionLogData": {
          "applyLabelsActionLogData": {
            "activityType": "LABELS_SUCCESSFULLY_APPLIED",
            "labels": [
              "text"
            ],
            "labelUpdatesOnResource": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "failureReason": "text"
          },
          "setExpirationActionLogData": {
            "expirationTime": 1
          },
          "revokeAccessActionLogData": {
            "revokedEmails": [
              "text"
            ],
            "unRevokedEmails": [
              "text"
            ]
          },
          "notifyEmailActionLogData": {
            "receiverEmail": "text"
          },
          "genericActionLogData": {
            "additionalContext": "text"
          },
          "blockActionActionLogData": {
            "isBlocked": true,
            "blockReason": "text",
            "skippedReason": "text"
          }
        }
      }
    }
  ],
  "nextPageToken": "text"
}