Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
Remove the annotation for a finding
The UUID of the finding to unannotate
Successful response (even if annotation does not exist)
How many remaining requests you can make within the next second before being throttled
How many remaining requests you can make within the next quota period
When the current quota period expires
Fetch an annotation by ID
The UUID of the annotation to fetch
Successful response
How many remaining requests you can make within the next second before being throttled
How many remaining requests you can make within the next quota period
When the current quota period expires
The annotation id
The annotation comment
Whether the annotation applies to all findings of this sensitive data
Annotate a finding
The UUID of the finding to annotate
The comment to add to the annotation
Whether the annotation applies to all findings of this sensitive data (defaults to true)
Successful response
How many remaining requests you can make within the next second before being throttled
How many remaining requests you can make within the next quota period
When the current quota period expires
The annotation id
The annotation comment
Whether the annotation applies to all findings of this sensitive data
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.
The UUIDs of the violations to perform the action on
Successful response (processed immediately)
How many remaining requests you can make within the next second before being throttled
How many remaining requests you can make within the next quota period
When the current quota period expires
violation UUIDs that were processed
Fetch a list of violations based on some filters
Unix timestamp in seconds, filters records created ≥ the value, defaults to -90 days UTC
Unix timestamp in seconds, filters records created < the value, defaults to end of the current day UTC
Unix timestamp in seconds, filters records updated > the value
The maximum number of records to be returned in the response
Cursor for getting the next page of results
Sort key and direction, defaults to descending order by creation time
The query containing filter clauses
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.comuser_name:"John Doe"Special Characters
+ - && || ! ( ) { } [ ] ^ " ~ * ? : are special characters need to be escaped using \. For example:
(1+1):2 should be searched for using \(1\+1)\:2Search 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 |
Successful response
How many remaining requests you can make within the next second before being throttled
How many remaining requests you can make within the next quota period
When the current quota period expires
The violation id
Unix timestamp when the violation was created
Unix timestamp when the violation was updated
Possible actions for the violation
The link to the resource on the integration
The channel name in case of a message in a channel
Type of location
User name
ID - user
Link to message
Members for the location
Count of members for the location
ID - channel
Name of workspace
Name of item
Type of item
Archived status
Unix timestamp
Unix timestamp
List of labels
Name of space
Key of space
Link of space
Parent page
Name of author
Email of author
Link of author name
Link to resource
ID - Confluence internal
ID - Confluence user
Version of item
ID - parent page
Version of parent page
ID of file
The name of the file
Type of file
File size
Link to file
Permissions
User list shared with - external
User list shared with - internal
Available for viewers to download
File owner
In trash
Unix timestamp, when the file was created
Unix timestamp, when the file was updated
Drive name
Updated by user
Name of project
Ticket number
Type of project
ID for the issue
Link to project
Link to ticket
Link to comment
Link to attachment
Branch on which violation occurred
Name of the organization or username in case of an individual account
Name of the repository
Email of the user who pushed the changes to GitHub
Username of the user who pushed the changes to GitHub
Unix timestamp
Boolean to check if the repo is private or public
Path of the file on which violation occurred
Permalink to the version of the file where sensitive content was identified
Owner of the repository
Link to the repository
Name of the Salesforce organization
ID of the record
Name of the object
Attachment or Object
ID of the user
Salesforce username of the author
Unix timestamp when the object was last updated
Fields of the Object
File Type
Link to the attachment
Name of the attachment
Link to the object
Status of the ticket
Title of the ticket
Ticket requested by
Group the ticket is assigned to
Agent the ticket is assigned to
User role
ID of the ticket
Followers of the ticket
Tags for the ticket
Unix timestamp
Unix timestamp
Location
Sub-location
ID - ticket comment
ID - ticket group
Link to the ticket group
ID - ticket agent
Link - ticket agent
Ticket event
Role of the user
Name of the attachment
Link for the attachment
Page creator
Page update by
Workspace name
Link to workspace
ID of the page
Title of the page
Unix timestamp
Unix timestamp
Private page link
Public page link
Externally shared state
ID of the attachment
Page URL where the extension is launched
Specific location on the page
Browser type
Remediation comment from the user
Name of the team containing the channel where the message was sent
ID of the tenant
Domain name of the tenant
ID of the team containing the channel where the message was sent
Visibility of the team containing the channel where the message was sent
Web URL of the team containing the channel where the message was sent
ID of the channel where the message was sent
Name of the channel where the message was sent
Type of the channel where the message was sent
Web URL of the channel where the message was sent
ID of the message
Unix timestamp
Unix timestamp
Sender of the chat message
ID of the user who sent the message
Principal name of the user who sent the message
Attachment details
ID of the attachment present in the message
Name of the attachment present in the message
URL of the attachment present in the message
Importance of the sent message
ID of the chat conversation
Type of the chat conversation (one-on-one, group, meeting)
Topic or subject of the chat conversation
ID of the user participating in the chat conversation
email address of the chat participant
display name of the chat participant
ID of the tenant
Domain name of the tenant
ID of the drive item
Name of the drive item
URL of the drive item
Mime type of the drive item
Size of the drive item in bytes
Path to the drive item relative to the root of the drive
ID of the user who created the drive item
Email of the user who last updated the drive item
ID of the user who last updated the drive item
Name of the user who last updated the drive item
Unix timestamp when the drive item was created
Unix timestamp when the drive item was last updated
Name of the special folder if drive item is inside one
ID of the drive where the drive item is present
Name of user who owns the drive where the drive item is present
Email of user who owns the drive where the drive item is present
ID of user who owns the drive where the drive item is present
Domain of the company where email was sent from
User Name who sent the email
Email of the sender
Recipients of the Email
Recipients mentioned in the CC field of the Email
Recipients mentioned in the BCC field of the Email
Subject of the email
Unix timestamp of when email was sent
ThreadID of the email
Name of the attachment
Type of attachment
The name of the file
The file mime type
The link to the resource on the integration
Policies violated
Detection rules triggered
Detectors triggered
The calculated score of the risk for this violation
Username as on the integration
User email as on the integration, may be empty
Next page cursor, omitted if end of results reached
Fetch a list of violations for a period
Unix timestamp in seconds, filters records created ≥ the value, defaults to -90 days UTC
Unix timestamp in seconds, filters records created < the value, defaults to end of the current day UTC
Unix timestamp in seconds, filters records updated > the value
The maximum number of records to be returned in the response
Cursor for getting the next page of results
Successful response
How many remaining requests you can make within the next second before being throttled
How many remaining requests you can make within the next quota period
When the current quota period expires
The violation id
Unix timestamp when the violation was created
Unix timestamp when the violation was updated
Possible actions for the violation
The link to the resource on the integration
The channel name in case of a message in a channel
Type of location
User name
ID - user
Link to message
Members for the location
Count of members for the location
ID - channel
Name of workspace
Name of item
Type of item
Archived status
Unix timestamp
Unix timestamp
List of labels
Name of space
Key of space
Link of space
Parent page
Name of author
Email of author
Link of author name
Link to resource
ID - Confluence internal
ID - Confluence user
Version of item
ID - parent page
Version of parent page
ID of file
The name of the file
Type of file
File size
Link to file
Permissions
User list shared with - external
User list shared with - internal
Available for viewers to download
File owner
In trash
Unix timestamp, when the file was created
Unix timestamp, when the file was updated
Drive name
Updated by user
Name of project
Ticket number
Type of project
ID for the issue
Link to project
Link to ticket
Link to comment
Link to attachment
Branch on which violation occurred
Name of the organization or username in case of an individual account
Name of the repository
Email of the user who pushed the changes to GitHub
Username of the user who pushed the changes to GitHub
Unix timestamp
Boolean to check if the repo is private or public
Path of the file on which violation occurred
Permalink to the version of the file where sensitive content was identified
Owner of the repository
Link to the repository
Name of the Salesforce organization
ID of the record
Name of the object
Attachment or Object
ID of the user
Salesforce username of the author
Unix timestamp when the object was last updated
Fields of the Object
File Type
Link to the attachment
Name of the attachment
Link to the object
Status of the ticket
Title of the ticket
Ticket requested by
Group the ticket is assigned to
Agent the ticket is assigned to
User role
ID of the ticket
Followers of the ticket
Tags for the ticket
Unix timestamp
Unix timestamp
Location
Sub-location
ID - ticket comment
ID - ticket group
Link to the ticket group
ID - ticket agent
Link - ticket agent
Ticket event
Role of the user
Name of the attachment
Link for the attachment
Page creator
Page update by
Workspace name
Link to workspace
ID of the page
Title of the page
Unix timestamp
Unix timestamp
Private page link
Public page link
Externally shared state
ID of the attachment
Page URL where the extension is launched
Specific location on the page
Browser type
Remediation comment from the user
Name of the team containing the channel where the message was sent
ID of the tenant
Domain name of the tenant
ID of the team containing the channel where the message was sent
Visibility of the team containing the channel where the message was sent
Web URL of the team containing the channel where the message was sent
ID of the channel where the message was sent
Name of the channel where the message was sent
Type of the channel where the message was sent
Web URL of the channel where the message was sent
ID of the message
Unix timestamp
Unix timestamp
Sender of the chat message
ID of the user who sent the message
Principal name of the user who sent the message
Attachment details
ID of the attachment present in the message
Name of the attachment present in the message
URL of the attachment present in the message
Importance of the sent message
ID of the chat conversation
Type of the chat conversation (one-on-one, group, meeting)
Topic or subject of the chat conversation
ID of the user participating in the chat conversation
email address of the chat participant
display name of the chat participant
ID of the tenant
Domain name of the tenant
ID of the drive item
Name of the drive item
URL of the drive item
Mime type of the drive item
Size of the drive item in bytes
Path to the drive item relative to the root of the drive
ID of the user who created the drive item
Email of the user who last updated the drive item
ID of the user who last updated the drive item
Name of the user who last updated the drive item
Unix timestamp when the drive item was created
Unix timestamp when the drive item was last updated
Name of the special folder if drive item is inside one
ID of the drive where the drive item is present
Name of user who owns the drive where the drive item is present
Email of user who owns the drive where the drive item is present
ID of user who owns the drive where the drive item is present
Domain of the company where email was sent from
User Name who sent the email
Email of the sender
Recipients of the Email
Recipients mentioned in the CC field of the Email
Recipients mentioned in the BCC field of the Email
Subject of the email
Unix timestamp of when email was sent
ThreadID of the email
Name of the attachment
Type of attachment
The name of the file
The file mime type
The link to the resource on the integration
Policies violated
Detection rules triggered
Detectors triggered
The calculated score of the risk for this violation
Username as on the integration
User email as on the integration, may be empty
Next page cursor, omitted if end of results reached
Get findings for a specific violation
The UUID of the violation
Cursor for getting the next page of results
Number of findings to fetch in one page (max 1000)
Successful response
How many remaining requests you can make within the next second before being throttled
How many remaining requests you can make within the next quota period
When the current quota period expires
The id of the findings
The id of the detector that was triggered
The sub detector id in case the detector uses a combination of detectors
The likelihood of the detection
The redacted sensitive data
Data preceding the sensitive data
Data after the sensitive data
Start point for a range
End point for a range
Start point for a range
End point for a range
Additional details about the key
Metadata/sub-location of the finding in the resource. For example - title or description for a Jira ticket.
The annotation id, if present
Next page cursor, omitted if end of results reached
Fetch a violation by ID
The UUID of the violation to fetch
Successful response
How many remaining requests you can make within the next second before being throttled
How many remaining requests you can make within the next quota period
When the current quota period expires
The violation id
Unix timestamp when the violation was created
Unix timestamp when the violation was updated
Possible actions for the violation
The link to the resource on the integration
The channel name in case of a message in a channel
Type of location
User name
ID - user
Link to message
Members for the location
Count of members for the location
ID - channel
Name of workspace
Name of item
Type of item
Archived status
Unix timestamp
Unix timestamp
List of labels
Name of space
Key of space
Link of space
Parent page
Name of author
Email of author
Link of author name
Link to resource
ID - Confluence internal
ID - Confluence user
Version of item
ID - parent page
Version of parent page
ID of file
The name of the file
Type of file
File size
Link to file
Permissions
User list shared with - external
User list shared with - internal
Available for viewers to download
File owner
In trash
Unix timestamp, when the file was created
Unix timestamp, when the file was updated
Drive name
Updated by user
Name of project
Ticket number
Type of project
ID for the issue
Link to project
Link to ticket
Link to comment
Link to attachment
Branch on which violation occurred
Name of the organization or username in case of an individual account
Name of the repository
Email of the user who pushed the changes to GitHub
Username of the user who pushed the changes to GitHub
Unix timestamp
Boolean to check if the repo is private or public
Path of the file on which violation occurred
Permalink to the version of the file where sensitive content was identified
Owner of the repository
Link to the repository
Name of the Salesforce organization
ID of the record
Name of the object
Attachment or Object
ID of the user
Salesforce username of the author
Unix timestamp when the object was last updated
Fields of the Object
File Type
Link to the attachment
Name of the attachment
Link to the object
Status of the ticket
Title of the ticket
Ticket requested by
Group the ticket is assigned to
Agent the ticket is assigned to
User role
ID of the ticket
Followers of the ticket
Tags for the ticket
Unix timestamp
Unix timestamp
Location
Sub-location
ID - ticket comment
ID - ticket group
Link to the ticket group
ID - ticket agent
Link - ticket agent
Ticket event
Role of the user
Name of the attachment
Link for the attachment
Page creator
Page update by
Workspace name
Link to workspace
ID of the page
Title of the page
Unix timestamp
Unix timestamp
Private page link
Public page link
Externally shared state
ID of the attachment
Page URL where the extension is launched
Specific location on the page
Browser type
Remediation comment from the user
Name of the team containing the channel where the message was sent
ID of the tenant
Domain name of the tenant
ID of the team containing the channel where the message was sent
Visibility of the team containing the channel where the message was sent
Web URL of the team containing the channel where the message was sent
ID of the channel where the message was sent
Name of the channel where the message was sent
Type of the channel where the message was sent
Web URL of the channel where the message was sent
ID of the message
Unix timestamp
Unix timestamp
Sender of the chat message
ID of the user who sent the message
Principal name of the user who sent the message
Attachment details
ID of the attachment present in the message
Name of the attachment present in the message
URL of the attachment present in the message
Importance of the sent message
ID of the chat conversation
Type of the chat conversation (one-on-one, group, meeting)
Topic or subject of the chat conversation
ID of the user participating in the chat conversation
email address of the chat participant
display name of the chat participant
ID of the tenant
Domain name of the tenant
ID of the drive item
Name of the drive item
URL of the drive item
Mime type of the drive item
Size of the drive item in bytes
Path to the drive item relative to the root of the drive
ID of the user who created the drive item
Email of the user who last updated the drive item
ID of the user who last updated the drive item
Name of the user who last updated the drive item
Unix timestamp when the drive item was created
Unix timestamp when the drive item was last updated
Name of the special folder if drive item is inside one
ID of the drive where the drive item is present
Name of user who owns the drive where the drive item is present
Email of user who owns the drive where the drive item is present
ID of user who owns the drive where the drive item is present
Domain of the company where email was sent from
User Name who sent the email
Email of the sender
Recipients of the Email
Recipients mentioned in the CC field of the Email
Recipients mentioned in the BCC field of the Email
Subject of the email
Unix timestamp of when email was sent
ThreadID of the email
Name of the attachment
Type of attachment
The name of the file
The file mime type
The link to the resource on the integration
Policies violated
Detection rules triggered
Detectors triggered
The calculated score of the risk for this violation
Username as on the integration
User email as on the integration, may be empty
Note
Internal only endpoint. This will change once Nightfall introduces CRUD API's for policies.
To prevent misuse and ensure the stability of our platform, we enforce a rate limit on an API Key and endpoint basis, similar to the way many other APIs enforce rate limits.
When operating under our Free plan, accounts and their corresponding API Keys have a rate limit of 5 requests per second on average, with support for bursts of 15 requests per second. If you upgrade to a paid plan – the Enterprise plan – this rate increases to a limit of 10 requests per second on average and bursts of 50 requests per second.
| Plan | Requests Per Second (Avg) | Burst |
|---|---|---|
The Nightfall API follows standard practices and conventions to signal when these rate limits have been exceeded.
Successful requests return a header X-Rate-Limit-Remaining with the integer number of requests remaining before errors will be returned to the client.
When your application exceeds the rate limit for a given API endpoint, the Nightfall API will return an HTTP response code of 429 "Too Many Requests.” If your use case requires increased rate limiting, please reach out to support@nightfall.ai.
Additionally, these unsuccessful requests return the number of seconds to wait before retrying the request in a Retry-After Header.
Your Request Rate Limiting throttles how frequently you can make requests to the API. You can monitor your rate limit usage via the `X-Rate-Limit-Remaining` header, which tells you how many remaining requests you can make within the next second before being throttled.
Your Quota limits how many requests you can make within a given period. Your current remaining quota and the end of your current quota period are denoted by the following response headers.
| Response Headers | Type | Description |
|---|---|---|
For the free plan, we allow 5 requests per second and 10000 requests in a day.
Free
5
15
Enterprise
10
50
X-Quota-Remaining
string
The requests remaining in your quota for this period. Will be reset to the amount specified in your billing plan at the end of your quota cycle.
X-Quota-Period-End
datetime
The date and time at which your quota will be reset, encoded as a string in the RFS-3339 format.
Return a list of Github repositories that Nightfall has access to. Each Github repository includes details like whether the repository is getting monitored or not, the last scanned time the Nightfall ran the scan against the applicable policies.
The maximum number of records to be returned in the response
Cursor for getting the next page of results
Successful response
How many remaining requests you can make within the next second before being throttled
How many remaining requests you can make within the next quota period
When the current quota period expires
the list of repositories being scanned
The GitHub repository ID
The name of the repository
Whether the repo is private
The URL of the repository
Unix timestamp, the last scan time of any file/commit in the repository. Omitted if not scanned yet.
Whether the repository is covered by a policy
GitHub username in case of a personal account and organization name in case of an organization
Next page cursor, omitted if end of results reached
Update a policy user scope, define inclusion/exclusion rule for users using user emails. Only supports gDrive policies, separates internal or external users based on google domains registered in Nightfall.
The UUID of the policy to update
user emails to be added in inclusion setting, supports both internal & external users
user emails to be added in exclusion setting, supports both internal & external users
user emails to be removed in inclusion setting, supports both internal & external users
user emails to be removed in exclusion setting, supports both internal & external users
Successful response (processed immediately)
How many remaining requests you can make within the next second before being throttled
How many remaining requests you can make within the next quota period
When the current quota period expires
a list of all included user identifiers (emails or id's) in the policy
a list of all excluded user identifiers (emails or id's) in the policy