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 - Firewall for AI Platform

PreviousNightfall PlaygroundNextRate Limits for Firewall APIs

Last updated 6 days ago

Was this helpful?

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.

Complete File Upload

post

Validates that all bytes of the file have been uploaded, and that the content type is supported by Nightfall.

Authorizations
Path parameters
fileIdstring · uuidRequired

a file ID returned from a previous file creation request

Responses
200
Success
application/json
400
Invalid request payload
application/json
401
Authentication failure
application/json
404
Invalid File ID
application/json
409
File Upload in Incorrect State
application/json
429
Rate Limit Exceeded or Monthly Quota Exceeded
application/json
500
Internal Nightfall Error
application/json
post
POST /v3/upload/{fileId}/finish HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "fileSizeBytes": 1,
  "chunkSize": 1,
  "mimeType": "text"
}
  • POSTScan Plain Text
  • POSTInitiate File Upload
  • PATCHUpload File Chunk
  • POSTComplete File Upload
  • POSTScan Uploaded File

Scan Plain Text

post

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.

Authorizations
Body

The request body of the /v3/scan endpoint

policyUUIDsstring[]Optional

A list of UUIDs referring to policies to use to scan the request payload. Policies can be built in the Nightfall Dashboard. Maximum 1.

payloadstring[]Optional

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.

Responses
200
Success
application/json
400
Invalid request payload
application/json
401
Authentication failure
application/json
422
Unprocessable request payload
application/json
429
Rate Limit Exceeded or Monthly Quota Exceeded
application/json
500
Internal Nightfall Error
application/json
post
POST /v3/scan HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1595

{
  "policyUUIDs": [
    "text"
  ],
  "policy": {
    "detectionRuleUUIDs": [
      "text"
    ],
    "detectionRules": [
      {
        "name": "text",
        "logicalOp": "ANY",
        "detectors": [
          {
            "minNumFindings": 1,
            "minConfidence": "VERY_UNLIKELY",
            "detectorUUID": "text",
            "displayName": "text",
            "detectorType": "NIGHTFALL_DETECTOR",
            "nightfallDetector": "AMERICAN_BANKERS_CUSIP_ID",
            "regex": {
              "pattern": "text",
              "isCaseSensitive": true
            },
            "wordList": {
              "values": [
                "text"
              ],
              "isCaseSensitive": true
            },
            "contextRules": [
              {
                "regex": {
                  "pattern": "text",
                  "isCaseSensitive": true
                },
                "proximity": {
                  "windowBefore": 1,
                  "windowAfter": 1
                },
                "confidenceAdjustment": {
                  "fixedConfidence": "VERY_UNLIKELY"
                }
              }
            ],
            "exclusionRules": [
              {
                "matchType": "PARTIAL",
                "exclusionType": "REGEX",
                "regex": {
                  "pattern": "text",
                  "isCaseSensitive": true
                },
                "wordList": {
                  "values": [
                    "text"
                  ],
                  "isCaseSensitive": true
                }
              }
            ],
            "redactionConfig": {
              "maskConfig": {
                "maskingChar": "text",
                "charsToIgnore": [
                  "text"
                ],
                "numCharsToLeaveUnmasked": 1,
                "maskLeftToRight": true
              },
              "infoTypeSubstitutionConfig": {},
              "substitutionConfig": {
                "substitutionPhrase": "text"
              },
              "cryptoConfig": {
                "publicKey": "text"
              },
              "removeFinding": true
            },
            "scope": "Content"
          }
        ]
      }
    ],
    "contextBytes": 1,
    "defaultRedactionConfig": {
      "maskConfig": {
        "maskingChar": "text",
        "charsToIgnore": [
          "text"
        ],
        "numCharsToLeaveUnmasked": 1,
        "maskLeftToRight": true
      },
      "infoTypeSubstitutionConfig": {},
      "substitutionConfig": {
        "substitutionPhrase": "text"
      },
      "cryptoConfig": {
        "publicKey": "text"
      },
      "removeFinding": true
    },
    "alertConfig": {
      "slack": {
        "target": "text"
      },
      "email": {
        "address": "text"
      },
      "url": {
        "address": "text"
      },
      "siem": {
        "address": "text",
        "sensitiveHeaders": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "plainTextHeaders": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      }
    }
  },
  "payload": [
    "text"
  ]
}
{
  "findings": [
    [
      {
        "finding": "text",
        "redactedFinding": "text",
        "beforeContext": "text",
        "afterContext": "text",
        "detector": {
          "name": "text",
          "uuid": "123e4567-e89b-12d3-a456-426614174000",
          "subdetector": {
            "name": "text",
            "uuid": "123e4567-e89b-12d3-a456-426614174000"
          }
        },
        "confidence": "VERY_UNLIKELY",
        "location": {
          "byteRange": {
            "start": 1,
            "end": 1
          },
          "codepointRange": {
            "start": 1,
            "end": 1
          }
        },
        "redactedLocation": {
          "byteRange": {
            "start": 1,
            "end": 1
          },
          "codepointRange": {
            "start": 1,
            "end": 1
          }
        }
      }
    ]
  ],
  "redactedPayload": [
    "text"
  ]
}

Initiate File Upload

post

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.

Authorizations
Body
fileSizeBytesintegerOptional

the number of bytes representing the size of the file to-be-uploaded.

Responses
200
Success
application/json
400
Invalid request payload
application/json
401
Authentication failure
application/json
429
Rate Limit Exceeded or Monthly Quota Exceeded
application/json
500
Internal Nightfall Error
application/json
post
POST /v3/upload HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "fileSizeBytes": 1
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "fileSizeBytes": 1,
  "chunkSize": 1,
  "mimeType": "text"
}

Upload File Chunk

patch

Upload all bytes contained in the request body to the file identified by the ID in the path parameter.

Authorizations
Path parameters
fileIdstring · uuidRequired

a file ID returned from a previous file creation request

Header parameters
X-Upload-OffsetintegerRequired

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.

Body
anyOptional

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.

Responses
204
Success
400
Invalid request payload
application/json
401
Authentication failure
application/json
404
Invalid File ID
application/json
429
Rate Limit Exceeded or Monthly Quota Exceeded
application/json
500
Internal Nightfall Error
application/json
patch
PATCH /v3/upload/{fileId} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Upload-Offset: 1
Content-Type: application/octet-stream
Accept: */*

No content

Scan Uploaded File

post

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.

Authorizations
Path parameters
fileIdstring · uuidRequired

a file ID returned from a previous file creation request

Body
policyUUIDstring · uuidOptional

the UUID of the Detection Policy to be used with this scan. Exactly one of this field or "policy" should be provided.

requestMetadatastringOptional

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.

Responses
200
Success
application/json
400
Invalid request payload
application/json
401
Authentication failure
application/json
404
Invalid File ID
application/json
409
Incorrect File State
application/json
422
Unprocessable request payload
application/json
429
Rate Limit Exceeded or Monthly Quota Exceeded
application/json
500
Internal Nightfall Error
application/json
post
POST /v3/upload/{fileId}/scan HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1672

{
  "policyUUID": "123e4567-e89b-12d3-a456-426614174000",
  "policy": {
    "detectionRuleUUIDs": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "detectionRules": [
      {
        "name": "text",
        "logicalOp": "ANY",
        "detectors": [
          {
            "minNumFindings": 1,
            "minConfidence": "VERY_UNLIKELY",
            "detectorUUID": "text",
            "displayName": "text",
            "detectorType": "NIGHTFALL_DETECTOR",
            "nightfallDetector": "AMERICAN_BANKERS_CUSIP_ID",
            "regex": {
              "pattern": "text",
              "isCaseSensitive": true
            },
            "wordList": {
              "values": [
                "text"
              ],
              "isCaseSensitive": true
            },
            "contextRules": [
              {
                "regex": {
                  "pattern": "text",
                  "isCaseSensitive": true
                },
                "proximity": {
                  "windowBefore": 1,
                  "windowAfter": 1
                },
                "confidenceAdjustment": {
                  "fixedConfidence": "VERY_UNLIKELY"
                }
              }
            ],
            "exclusionRules": [
              {
                "matchType": "PARTIAL",
                "exclusionType": "REGEX",
                "regex": {
                  "pattern": "text",
                  "isCaseSensitive": true
                },
                "wordList": {
                  "values": [
                    "text"
                  ],
                  "isCaseSensitive": true
                }
              }
            ],
            "redactionConfig": {
              "maskConfig": {
                "maskingChar": "text",
                "charsToIgnore": [
                  "text"
                ],
                "numCharsToLeaveUnmasked": 1,
                "maskLeftToRight": true
              },
              "infoTypeSubstitutionConfig": {},
              "substitutionConfig": {
                "substitutionPhrase": "text"
              },
              "cryptoConfig": {
                "publicKey": "text"
              },
              "removeFinding": true
            },
            "scope": "Content"
          }
        ]
      }
    ],
    "alertConfig": {
      "slack": {
        "target": "text"
      },
      "email": {
        "address": "text"
      },
      "url": {
        "address": "text"
      },
      "siem": {
        "address": "text",
        "sensitiveHeaders": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "plainTextHeaders": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      }
    },
    "defaultRedactionConfig": {
      "maskConfig": {
        "maskingChar": "text",
        "charsToIgnore": [
          "text"
        ],
        "numCharsToLeaveUnmasked": 1,
        "maskLeftToRight": true
      },
      "infoTypeSubstitutionConfig": {},
      "substitutionConfig": {
        "substitutionPhrase": "text"
      },
      "cryptoConfig": {
        "publicKey": "text"
      },
      "removeFinding": true
    },
    "enableFileRedaction": true
  },
  "requestMetadata": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "message": "text"
}