Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Firewall for AI DLP APIs enables developers to write custom code to sanitize data anywhere–RAG data sets, analytics data stores, data pipelines, and unsupported SaaS applications.
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 bytes of data you're permitted to scan 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 |
|---|---|---|
Creates a new file upload session. If this operation returns successfully, the ID returned as part of the response object shall be used to refer to the file in all subsequent upload and scanning operations.
the number of bytes representing the size of the file to-be-uploaded.
Success
a UUID to uniquely identify a particular file upload
the size of the file in bytes
the number of bytes to upload in each chunk upload request
an RFC2045 media type that describes the underlying content type
Upload all bytes contained in the request body to the file identified by the ID in the path parameter.
a file ID returned from a previous file creation request
The numeric offset at which the bytes contained in the body should be written. This offset must be a multiple of the chunk size returned when the file upload was created.
The payload bytes to upload; the size of the request body must exactly match the chunkSize that was returned when the file upload was created.
Success
Validates that all bytes of the file have been uploaded, and that the content type is supported by Nightfall.
a file ID returned from a previous file creation request
Success
a UUID to uniquely identify a particular file upload
the size of the file in bytes
the number of bytes to upload in each chunk upload request
an RFC2045 media type that describes the underlying content type
Provide a list of arbitrary string data, and scan each item with the provided detectors to uncover sensitive information. Returns a list equal in size to the number of provided string payloads. The item at each list index will be a list of all matches for the provided detectors, or an empty list if no occurrences are found.
A list of UUIDs referring to policies to use to scan the request payload. Policies can be built in the Nightfall Dashboard. Maximum 1.
A policy UUID.
Policy can contain a list of pre-configured detection rule UUID's and/or a list of inline detection rules with which to scan the request payload. At least one list must be non-empty.
A list of UUIDs referring to detection rules to use to scan the request payload. Detection rules can be built in the Nightfall dashboard. Maximum 20.
A detection rule UUID.
A list of inline detection rule definitions to use to scan the request payload. Maximum 20.
An optional name for the detection rule.
Supported values ALL or ANY. Applies a logical "AND" or "OR" (respectively) to the list of detectors to decide when a finding should be surfaced.
A list of detectors the request payload should be scanned against.
The minimum number of findings required in order for this detector to be reported.
The confidence level of a finding.
The UUID of a pre-existing detector to use. If this value is provided, all below fields are ignored.
The display name for this detector's findings in the response.
The type of detector.
The name for a Nightfall detector.
The regex object for the regex detector, context rules, and exclusion rules.
The regex pattern to match on.
The case sensitivity for the regex pattern.
The WordList object for wordList detector and exclusion rules.
A list of words for wordList.
The case sensitivity for words in the wordList. If false, ignore the case of findings.
A list of context rules.
The regex object for the regex detector, context rules, and exclusion rules.
The regex pattern to match on.
The case sensitivity for the regex pattern.
The object containing the length of characters before and after finding to evaluate context.
The number of leading characters to include as context before the finding itself.
The number of trailing characters to include as context after the finding itself.
The object containing the confidence level to adjust findings to.
The confidence level of a finding.
A list of exclusion rules.
The type of match for a pattern.
The type of exclusion rule.
The regex object for the regex detector, context rules, and exclusion rules.
The regex pattern to match on.
The case sensitivity for the regex pattern.
The WordList object for wordList detector and exclusion rules.
A list of words for wordList.
The case sensitivity for words in the wordList. If false, ignore the case of findings.
A config that determines how a finding will be redacted. Must contain exactly one of [maskConfig, infoTypeSubstitutionConfig, substitutionConfig, cryptoConfig].
A config that masks a sensitive finding. e.g. '4242-4242-4242-4242' can be configured to be redacted to '####-####-####-4242'.
The UTF-8 character used to mask a finding. If not provided, we will mask with an asterisk "*". Other examples include "#", "X", "🙅🏽", "🙈", etc.
A list of characters that will not be masked. For example, you could set this field to ["-","@"] to preserve formatting context that is typically present in credit cards or emails (e.g. --- versus *********, or ***************** versus @).
A character that will not be masked. e.g. "-"
The number of characters that will be left unmasked. For instance, if you want to mask all but the last 4 digits of a credit card number, set this value to 4 so that the redacted finding would look like ***************4242.
Determines if masking is applied left to right (/1984) instead of right to left (01/01). By default, this value is false.
A config that substitutes a sensitive finding with the name of the NIGHTFALL_DETECTOR that triggered it. This config is only valid for detector's with detectorType NIGHTFALL_DETECTOR. e.g. '4242-4242-4242-4242' can be configured to be redacted to '[CREDIT_CARD_NUMBER]'.
A config that substitutes a sensitive finding with the configured substitutionPhrase. If no substitutionPhrase is configured, it will substitute the finding with an empty string. For example, 'my cc is 4242-4242-4242-4242' can be configured to be redacted to 'my cc is <oh no!🙈>'
The value that will replace a sensitive finding. e.g. '<oh no!🙈>'
A config that will encrypt a sensitive finding with the provided PEM formatted public key using RSA encryption.
The PEM formatted public key block that will be used to encrypt findings. Currently, only RSA encryption is supported.
Here's an example PEM formatted public key block:
-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAydYMwOYUGyBXDgHkzv19 YR/dYQES4kYTMUps39qv/amNDywz4nsBDvCUqUvcN3nEpplHlYGH5ShSeA4G/Fcm RqynSLVyFPZat/8E7n+EeHsgihFrr8oDWo5UBjCwRinTrC0m11q/5SeNzwVCWkf9 x40u94QBz13dQoa9yPwaZBX5uBzyH86R7yeZHpad2cLq0ltpmJ3j5UfsFilkOb3J B60TNpNDdfabprot/y30CEnDDOgAXGtV1m0AhQpQjKRnkUs39DntqSbS+i0Ugbyq zEGNUkeR1WsotXekW4KnbWA7k6S8SfkO27vnTSY5b9g/KKaOdysn5YaWJPfTVT/n ywIDAQAB -----END PUBLIC KEY-----
Determines if the response object will contain the un-redacted sensitive finding that was triggered by the scan. Defaults to false.
The scope to run the detector over. Setting any detector to File will cause it to run against the file name.
The number of bytes to include as before / after context when a finding is returned. Maximum 40.
A config that determines how a finding will be redacted. Must contain exactly one of [maskConfig, infoTypeSubstitutionConfig, substitutionConfig, cryptoConfig].
A config that masks a sensitive finding. e.g. '4242-4242-4242-4242' can be configured to be redacted to '####-####-####-4242'.
The UTF-8 character used to mask a finding. If not provided, we will mask with an asterisk "*". Other examples include "#", "X", "🙅🏽", "🙈", etc.
A list of characters that will not be masked. For example, you could set this field to ["-","@"] to preserve formatting context that is typically present in credit cards or emails (e.g. --- versus *********, or ***************** versus @).
A character that will not be masked. e.g. "-"
The number of characters that will be left unmasked. For instance, if you want to mask all but the last 4 digits of a credit card number, set this value to 4 so that the redacted finding would look like ***************4242.
Determines if masking is applied left to right (/1984) instead of right to left (01/01). By default, this value is false.
A config that substitutes a sensitive finding with the name of the NIGHTFALL_DETECTOR that triggered it. This config is only valid for detector's with detectorType NIGHTFALL_DETECTOR. e.g. '4242-4242-4242-4242' can be configured to be redacted to '[CREDIT_CARD_NUMBER]'.
A config that substitutes a sensitive finding with the configured substitutionPhrase. If no substitutionPhrase is configured, it will substitute the finding with an empty string. For example, 'my cc is 4242-4242-4242-4242' can be configured to be redacted to 'my cc is <oh no!🙈>'
The value that will replace a sensitive finding. e.g. '<oh no!🙈>'
A config that will encrypt a sensitive finding with the provided PEM formatted public key using RSA encryption.
The PEM formatted public key block that will be used to encrypt findings. Currently, only RSA encryption is supported.
Here's an example PEM formatted public key block:
-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAydYMwOYUGyBXDgHkzv19 YR/dYQES4kYTMUps39qv/amNDywz4nsBDvCUqUvcN3nEpplHlYGH5ShSeA4G/Fcm RqynSLVyFPZat/8E7n+EeHsgihFrr8oDWo5UBjCwRinTrC0m11q/5SeNzwVCWkf9 x40u94QBz13dQoa9yPwaZBX5uBzyH86R7yeZHpad2cLq0ltpmJ3j5UfsFilkOb3J B60TNpNDdfabprot/y30CEnDDOgAXGtV1m0AhQpQjKRnkUs39DntqSbS+i0Ugbyq zEGNUkeR1WsotXekW4KnbWA7k6S8SfkO27vnTSY5b9g/KKaOdysn5YaWJPfTVT/n ywIDAQAB -----END PUBLIC KEY-----
Determines if the response object will contain the un-redacted sensitive finding that was triggered by the scan. Defaults to false.
A configuration object that allows clients to specify where alerts should be delivered when findings are discovered as part of a scan. These alerts are delivered asynchronously to the provided platforms.
Contains the configuration required to allow clients to send asynchronous alerts to a Slack workspace when findings are detected. In order to use this alert destination, you must first authenticate Nightfall to your Slack workspace under the Settings menu on the Nightfall Dashboard. Alerts are only sent if findings are detected.
The name of the Slack conversation to which alerts should be sent. Currently, Nightfall supports sending alerts to public channels, formatted like "#general".
Contains the configuration required to allow clients to send an asynchronous email message when findings are detected. Alerts are only sent if findings are detected.
The email address to which alerts should be sent.
Contains the configuration required to allow clients to send a webhook event to an external URL when findings are detected. When findings are detected, an alert is always sent to the webhook, even when there are no findings.
The URL to which alerts should be sent. This URL must (1) use the HTTPS scheme, (2) be able to accept requests made with the POST verb, and (3) respond with a 200 status code upon receipt of the event.
Contains the configuration required to allow clients to send a SIEM events to an external URL when findings are detected. When findings are detected, an alert is always sent to the webhook, even when there are no findings.
The URL to which alerts should be sent. This URL must (1) use the HTTPS scheme, (2) be able to accept requests made with the POST verb, and (3) respond with a 200 status code upon receipt of the event.
Sensitive header key value pairs to include in the SIEM request. Used for adding sensitive content like authentication tokens.
Header key value pairs to include in the SIEM request.
The text sample(s) you wish to scan. This data is passed as a string list, so you may choose to segment your text into multiple items for better granularity. The aggregate size of your text (summed across all items in the list) must not exceed 500 KB for any individual request, and the number of items in that list may not exceed 50,000.
A collection of strings to scan.
Success
A list of all findings that were detected in the request payload. Each item in the list is a list of all findings that occurred at the corresponding list index from the input payload.
The string that triggered a match during the scan.
The redacted version of finding. This key is omitted if no redactionConfig was configured the detector that triggered the match.
The sequence of bytes that occurred directly prior to the matched finding. The number of bytes is usually equal to the requested number from the request config, but it could be smaller if the finding occurs near the beginning of the payload. This key is omitted if no context was requested.
The sequence of bytes that occurred directly after the matched finding. The number of bytes is usually equal to the requested number from the request config, but it could be smaller if the finding occurs near the end of the payload. This key is omitted if no context was requested.
Metadata describing the detector that matched the finding.
The display name of the detector that matched the finding.
The UUID of the detector that matched the finding. This UUID can be looked up in the Nightfall dashboard.
Optional metadata describing the subdetector that matched the finding.
The display name of the subdetector that matched the finding.
The UUID of the subdetector that matched the finding. This UUID can be looked up in the Nightfall dashboard.
The confidence level of a finding.
The location of the finding in the corresponding original input payload string.
The index of the fragment's starting byte.
The index of the fragment's ending byte.
The index of the fragment's starting codepoint character.
The index of the fragment's ending codepoint character.
The location of the redacted finding in the corresponding redactedPayload string.
The index of the fragment's starting byte.
The index of the fragment's ending byte.
The index of the fragment's starting codepoint character.
The index of the fragment's ending codepoint character.
A list containing the the redacted version of each string in the input payload. If no redactions were applied, the corresponding string will be empty.
Free
5
15
Enterprise
10, more by request
50, more by request
X-Quota-Remaining
string
The bytes 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.
Triggers a scan of the file identified by the provided fileID. As the underlying file might be arbitrarily large, this scan is conducted asynchronously. Results from the scan are delivered to the webhook URL provided in the request payload.
a file ID returned from a previous file creation request
the UUID of the Detection Policy to be used with this scan. Exactly one of this field or "policy" should be provided.
A list of pre-existing detection rule UUIDs to scan a file against. These UUIDs can be fetched from the Nightfall Dashboard.
A list of inlined detection rule definitions to scan a file against.
An optional name for the detection rule.
Supported values ALL or ANY. Applies a logical "AND" or "OR" (respectively) to the list of detectors to decide when a finding should be surfaced.
A list of detectors the request payload should be scanned against.
The minimum number of findings required in order for this detector to be reported.
The confidence level of a finding.
The UUID of a pre-existing detector to use. If this value is provided, all below fields are ignored.
The display name for this detector's findings in the response.
The type of detector.
The name for a Nightfall detector.
The regex object for the regex detector, context rules, and exclusion rules.
The regex pattern to match on.
The case sensitivity for the regex pattern.
The WordList object for wordList detector and exclusion rules.
A list of words for wordList.
The case sensitivity for words in the wordList. If false, ignore the case of findings.
A list of context rules.
The regex object for the regex detector, context rules, and exclusion rules.
The regex pattern to match on.
The case sensitivity for the regex pattern.
The object containing the length of characters before and after finding to evaluate context.
The number of leading characters to include as context before the finding itself.
The number of trailing characters to include as context after the finding itself.
The object containing the confidence level to adjust findings to.
The confidence level of a finding.
A list of exclusion rules.
The type of match for a pattern.
The type of exclusion rule.
The regex object for the regex detector, context rules, and exclusion rules.
The regex pattern to match on.
The case sensitivity for the regex pattern.
The WordList object for wordList detector and exclusion rules.
A list of words for wordList.
The case sensitivity for words in the wordList. If false, ignore the case of findings.
A config that determines how a finding will be redacted. Must contain exactly one of [maskConfig, infoTypeSubstitutionConfig, substitutionConfig, cryptoConfig].
A config that masks a sensitive finding. e.g. '4242-4242-4242-4242' can be configured to be redacted to '####-####-####-4242'.
The UTF-8 character used to mask a finding. If not provided, we will mask with an asterisk "*". Other examples include "#", "X", "🙅🏽", "🙈", etc.
A list of characters that will not be masked. For example, you could set this field to ["-","@"] to preserve formatting context that is typically present in credit cards or emails (e.g. --- versus *********, or ***************** versus @).
A character that will not be masked. e.g. "-"
The number of characters that will be left unmasked. For instance, if you want to mask all but the last 4 digits of a credit card number, set this value to 4 so that the redacted finding would look like ***************4242.
Determines if masking is applied left to right (/1984) instead of right to left (01/01). By default, this value is false.
A config that substitutes a sensitive finding with the name of the NIGHTFALL_DETECTOR that triggered it. This config is only valid for detector's with detectorType NIGHTFALL_DETECTOR. e.g. '4242-4242-4242-4242' can be configured to be redacted to '[CREDIT_CARD_NUMBER]'.
A config that substitutes a sensitive finding with the configured substitutionPhrase. If no substitutionPhrase is configured, it will substitute the finding with an empty string. For example, 'my cc is 4242-4242-4242-4242' can be configured to be redacted to 'my cc is <oh no!🙈>'
The value that will replace a sensitive finding. e.g. '<oh no!🙈>'
A config that will encrypt a sensitive finding with the provided PEM formatted public key using RSA encryption.
The PEM formatted public key block that will be used to encrypt findings. Currently, only RSA encryption is supported.
Here's an example PEM formatted public key block:
-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAydYMwOYUGyBXDgHkzv19 YR/dYQES4kYTMUps39qv/amNDywz4nsBDvCUqUvcN3nEpplHlYGH5ShSeA4G/Fcm RqynSLVyFPZat/8E7n+EeHsgihFrr8oDWo5UBjCwRinTrC0m11q/5SeNzwVCWkf9 x40u94QBz13dQoa9yPwaZBX5uBzyH86R7yeZHpad2cLq0ltpmJ3j5UfsFilkOb3J B60TNpNDdfabprot/y30CEnDDOgAXGtV1m0AhQpQjKRnkUs39DntqSbS+i0Ugbyq zEGNUkeR1WsotXekW4KnbWA7k6S8SfkO27vnTSY5b9g/KKaOdysn5YaWJPfTVT/n ywIDAQAB -----END PUBLIC KEY-----
Determines if the response object will contain the un-redacted sensitive finding that was triggered by the scan. Defaults to false.
The scope to run the detector over. Setting any detector to File will cause it to run against the file name.
A configuration object that allows clients to specify where alerts should be delivered when findings are discovered as part of a scan. These alerts are delivered asynchronously to the provided platforms.
Contains the configuration required to allow clients to send asynchronous alerts to a Slack workspace when findings are detected. In order to use this alert destination, you must first authenticate Nightfall to your Slack workspace under the Settings menu on the Nightfall Dashboard. Alerts are only sent if findings are detected.
The name of the Slack conversation to which alerts should be sent. Currently, Nightfall supports sending alerts to public channels, formatted like "#general".
Contains the configuration required to allow clients to send an asynchronous email message when findings are detected. Alerts are only sent if findings are detected.
The email address to which alerts should be sent.
Contains the configuration required to allow clients to send a webhook event to an external URL when findings are detected. When findings are detected, an alert is always sent to the webhook, even when there are no findings.
The URL to which alerts should be sent. This URL must (1) use the HTTPS scheme, (2) be able to accept requests made with the POST verb, and (3) respond with a 200 status code upon receipt of the event.
Contains the configuration required to allow clients to send a SIEM events to an external URL when findings are detected. When findings are detected, an alert is always sent to the webhook, even when there are no findings.
The URL to which alerts should be sent. This URL must (1) use the HTTPS scheme, (2) be able to accept requests made with the POST verb, and (3) respond with a 200 status code upon receipt of the event.
Sensitive header key value pairs to include in the SIEM request. Used for adding sensitive content like authentication tokens.
Header key value pairs to include in the SIEM request.
A config that determines how a finding will be redacted. Must contain exactly one of [maskConfig, infoTypeSubstitutionConfig, substitutionConfig, cryptoConfig].
A config that masks a sensitive finding. e.g. '4242-4242-4242-4242' can be configured to be redacted to '####-####-####-4242'.
The UTF-8 character used to mask a finding. If not provided, we will mask with an asterisk "*". Other examples include "#", "X", "🙅🏽", "🙈", etc.
A list of characters that will not be masked. For example, you could set this field to ["-","@"] to preserve formatting context that is typically present in credit cards or emails (e.g. --- versus *********, or ***************** versus @).
A character that will not be masked. e.g. "-"
The number of characters that will be left unmasked. For instance, if you want to mask all but the last 4 digits of a credit card number, set this value to 4 so that the redacted finding would look like ***************4242.
Determines if masking is applied left to right (/1984) instead of right to left (01/01). By default, this value is false.
A config that substitutes a sensitive finding with the name of the NIGHTFALL_DETECTOR that triggered it. This config is only valid for detector's with detectorType NIGHTFALL_DETECTOR. e.g. '4242-4242-4242-4242' can be configured to be redacted to '[CREDIT_CARD_NUMBER]'.
A config that substitutes a sensitive finding with the configured substitutionPhrase. If no substitutionPhrase is configured, it will substitute the finding with an empty string. For example, 'my cc is 4242-4242-4242-4242' can be configured to be redacted to 'my cc is <oh no!🙈>'
The value that will replace a sensitive finding. e.g. '<oh no!🙈>'
A config that will encrypt a sensitive finding with the provided PEM formatted public key using RSA encryption.
The PEM formatted public key block that will be used to encrypt findings. Currently, only RSA encryption is supported.
Here's an example PEM formatted public key block:
-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAydYMwOYUGyBXDgHkzv19 YR/dYQES4kYTMUps39qv/amNDywz4nsBDvCUqUvcN3nEpplHlYGH5ShSeA4G/Fcm RqynSLVyFPZat/8E7n+EeHsgihFrr8oDWo5UBjCwRinTrC0m11q/5SeNzwVCWkf9 x40u94QBz13dQoa9yPwaZBX5uBzyH86R7yeZHpad2cLq0ltpmJ3j5UfsFilkOb3J B60TNpNDdfabprot/y30CEnDDOgAXGtV1m0AhQpQjKRnkUs39DntqSbS+i0Ugbyq zEGNUkeR1WsotXekW4KnbWA7k6S8SfkO27vnTSY5b9g/KKaOdysn5YaWJPfTVT/n ywIDAQAB -----END PUBLIC KEY-----
Determines if the response object will contain the un-redacted sensitive finding that was triggered by the scan. Defaults to false.
Determines if a redacted version of the file will be returned, if available for the mime type. Current supported mime types are CSV and TSV. Defaults to false.
A string containing arbitrary metadata. Callers may opt to use this to help identify their input file upon receiving a webhook response. Maximum length 10 KB.
Success
a UUID to uniquely identify a particular file upload
message indicating that file scanning has been initiated