Nightfall Documentation
  • Data Detection and Response
  • Posture Management
  • Data Exfiltration Prevention
  • Data Encryption
  • Firewall for AI
  • Data Classification and Discovery
  • Welcome
  • Introduction to Firewall for AI
    • Overview
    • Quickstart
    • Use Cases
    • Authentication and Security
  • Key Concepts
    • Entities and Terms to Know
    • Setting Up Nightfall
      • Creating API Key
      • Creating Detectors
      • Creating Detection Rules
      • Creating Policies
    • Alerting
    • Scanning Text
    • Scanning Files
      • Supported File Types
      • File Scanning and Webhooks
      • Uploading and Scanning API Calls
      • Special File Types
      • Specialized File Detectors
      • Webhooks and Asynchronous Notifications
        • Accessing Your Webhook Signing Key
        • Creating a Webhook Server
    • Scanning Features
      • Using Pre-Configured Detection Rules
        • Scanning Images for patterns using Custom Regex Detectors
      • Creating an Inline Detection Rule
      • Using Exclusion Rules
      • Using Context Rules
      • Using Redaction
      • Using Policies to Send Alerts
      • Detecting Secrets
      • PHI Detection Rules
    • Detector Glossary
    • Test Datasets
    • Errors
    • Nightfall Playground
  • Nightfall APIs
    • DLP APIs - Firewall for AI Platform
      • Rate Limits for Firewall APIs
    • DLP APIs - Native SaaS Apps
      • Policy User Scope Update API
      • Rate Limits for Native SaaS app APIs
  • Exfiltration Prevention APIs
    • Default
    • Models
  • Posture Management APIs
    • Default
    • Models
  • Nightfall Software Development Kit (SDK)
    • Overview
    • Java SDK
    • Python SDK
    • Go SDK
    • Node.JS SDK
  • Language Specific Guides
    • Overview
    • Python
    • Ruby
    • Java
  • Tutorials
    • GenAI Protection
      • OpenAI Prompt Sanitization Tutorial
      • Anthropic Prompt Sanitization Tutorial
      • LangChain Prompt Sanitization Tutorial
    • SaaS Protection
      • HubSpot DLP Tutorial
      • Zendesk DLP Tutorial
    • Observability Protection
      • Datadog DLP Tutorial
      • New Relic DLP Tutorial
    • Datastore Protection
      • Airtable DLP Tutorial
      • Amazon Kinesis DLP Tutorial
      • Amazon RDS DLP Tutorial
      • Amazon RDS DLP Tutorial - Full Scan
      • Amazon S3 DLP Tutorial
      • Elasticsearch DLP Tutorial
      • Snowflake DLP Tutorial
  • Nightfall Use Cases
    • Overview
    • GenAI Content Filtering-How to prevent exposure of sensitive data
    • Redacting Sensitive Data in 4 Lines of Code
    • Detecting Sensitive Data in SMS Automations
    • Building Endpoint DLP to Detect PII on Your Machine in Real-Time
    • Deploy a File Scanner for Sensitive Data in 40 Lines of Code
    • Using Scan API (with Python)
  • FAQs
    • What Can I do with the Firewall for AI
    • How quickly can I get started with Firewall for AI?
    • What types of data can I scan with API?
    • What types of detectors are supported out of the box?
    • Can I customize or bring my own detectors?
    • What is the pricing model?
    • How do I know my data is secure?
    • How do I get in touch with you?
    • Can I test out the detection and my own detection rules before writing any code?
    • How does Nightfall support custom data types?
    • How does Nightfall's Firewall for AI differs from other solutions?
  • Nightfall Playground
  • Login to Nightfall
  • Contact Us
Powered by GitBook
On this page

Was this helpful?

Export as PDF
  1. Nightfall APIs

DLP APIs - Native SaaS Apps

PreviousRate Limits for Firewall APIsNextPolicy User Scope Update API

Last updated 6 days ago

Was this helpful?

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 . 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.

Getting Started with the Developer Platform section

Fetch violations

get

Fetch a list of violations for a period

Authorizations
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
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
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
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
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:"amy@rocketrides.io"
field user_email
operator :
value amy@rocketrides.io

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:john@example.com
  • 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
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
GET /dlp/v1/violations/search 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
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
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"
}

Fetch annotation

get

Fetch an annotation by ID

Authorizations
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
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
}

Remove finding annotation

post

Remove the annotation for a finding

Authorizations
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
POST /dlp/v1/findings/{findingId}/unannotate HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

  • GETFetch violations
  • GETFetch violation
  • GETSearch violations
  • GETFetch violation findings
  • POSTTake an action on Violations
  • GETFetch annotation
  • POSTAnnotate finding
  • POSTRemove finding annotation

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

Annotate finding

post

Annotate a finding

Authorizations
Path parameters
findingIdstring · uuidRequired

The UUID of the finding to annotate

Body
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
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
}