# Protecto AI Documentation

## Documentation

- [Overview](https://docs.protecto.ai/introduction/overview.md): Protecto is an API-first data protection platform that helps engineering teams identify, tokenize, mask, and safely handle sensitive data across applications, data pipelines, and GenAI workflows.
- [Why Protecto](https://docs.protecto.ai/introduction/why-protecto.md): The common data protection problems that Protecto solves, and what makes its approach different from alternatives.
- [Key Capabilities](https://docs.protecto.ai/introduction/key-capabilities.md): Complete overview of Protecto's APIs — from core tokenization and masking to async processing, data discovery, and governance.
- [Trial vs Paid Features](https://docs.protecto.ai/introduction/trial-vs-paid.md): What's available on the Protecto trial and what requires a paid subscription.
- [Quickstart](https://docs.protecto.ai/getting-started/quickstart.md): Make your first Protecto API call in under 5 minutes — create an account, get a token, mask sensitive data, and unmask it.
- [Use Cases](https://docs.protecto.ai/use-cases/overview.md): Real-world patterns for protecting sensitive data across applications, AI pipelines, logs, analytics, and CRM systems using Protecto.
- [Protect PII in GenAI / LLM Prompts](https://docs.protecto.ai/use-cases/genai-llm-prompts.md): Auto-detect and mask sensitive data before sending text to an LLM, then optionally restore original values after the model responds.
- [Redact Sensitive Data in Logs](https://docs.protecto.ai/use-cases/redact-logs.md): Mask log lines before writing them so sensitive data is never stored in application logs, with optional unmasking for authorized debugging.
- [Mask PII in Analytics & BI Pipelines](https://docs.protecto.ai/use-cases/analytics-bi-pipelines.md): Tokenize sensitive fields at ingestion time so data warehouses and BI dashboards never hold raw PII, with policy-controlled unmasking for authorized re-identification.
- [AI Agent for CRM Support With PII Protection](https://docs.protecto.ai/use-cases/crm-support.md): Mask CRM fields before your AI support agent processes them, then unmask only in explicitly authorized workflows.
- [Detect and Tag Internal Customer IDs as Custom PII](https://docs.protecto.ai/use-cases/custom-pii-detection.md): Configure Protecto to recognize your internal identifiers—like Customer IDs—as first-class PII types using custom tag detection endpoints.
- [Core Concepts](https://docs.protecto.ai/core-concepts/overview.md): The foundational ideas behind Protecto — tokenization, masking, policies, and permissions. Understanding these concepts helps you design integrations correctly and predict behavior.
- [Tokenization Basics](https://docs.protecto.ai/core-concepts/tokenization-basics.md): How Protecto replaces sensitive values with secure, deterministic tokens — and why this is different from encryption.
- [Detection vs Masking](https://docs.protecto.ai/core-concepts/detection-vs-masking.md): Detection and masking are two logically separate steps in Protecto. Understanding the difference helps you choose the right API mode and predict behavior.
- [Auto-Detect and Mask](https://docs.protecto.ai/core-concepts/auto-detect-mask.md): The default masking mode for free-form text — Protecto scans input, detects sensitive entities by policy, and returns a masked version with entity tags.
- [Tokens vs Formats](https://docs.protecto.ai/core-concepts/tokens-vs-formats.md): Two masking strategies — tokens replace values entirely, formats preserve the structure while masking the content. Both are deterministic and reversible.
- [Entity Tags](https://docs.protecto.ai/core-concepts/entity-tags.md): How Protecto wraps masked values in typed entity tags — preserving semantic meaning, enabling downstream parsing, and supporting both built-in and custom PII.
- [Unmasking](https://docs.protecto.ai/core-concepts/unmasking.md): Unmasking restores original values from tokens. It is always explicit, always permission-controlled, and never automatic.
- [Policies](https://docs.protecto.ai/core-concepts/policies.md): A policy defines how tokenization behaves — what gets detected, how it is masked, whether it can be unmasked, and what additional signals are returned.
- [Anonymization vs Pseudonymization](https://docs.protecto.ai/core-concepts/anonymization-vs-pseudonymization.md): The structural difference between irreversible and reversible masking — and how Protecto enforces this distinction through policy configuration.
- [Namespaces and Permissions](https://docs.protecto.ai/core-concepts/namespaces-permissions.md): How Protecto uses namespaces as isolation boundaries and permissions to enforce least-privilege access for sensitive operations.
- [Custom PII (Custom Tags)](https://docs.protecto.ai/core-concepts/custom-pii.md): How to extend Protecto's detection to cover internal identifiers — customer IDs, account numbers, and other organization-specific sensitive data.
- [Toxicity Detection](https://docs.protecto.ai/core-concepts/toxicity-detection.md): How Protecto analyzes text for harmful content and returns structured safety scores — without modifying or blocking data.
- [Synchronous vs Asynchronous Processing](https://docs.protecto.ai/core-concepts/sync-vs-async.md): The two execution models in Protecto — when to use real-time synchronous APIs versus background asynchronous APIs, and how to choose between them.

## API Reference

- [Authentication & Authorization](https://docs.protecto.ai/authentication/overview.md): Protecto uses token-based authentication for all API access. Every request is authenticated and authorized server-side before any masking or unmasking occurs.
- [API Tokens & Headers](https://docs.protecto.ai/authentication/api-tokens.md): How to obtain your Protecto bearer token and include it correctly in every API request.
- [Permissions & Scopes](https://docs.protecto.ai/authentication/permissions-scopes.md): How Protecto evaluates what operations your token is authorized to perform after authentication succeeds.
- [Token Expiry & Rotation](https://docs.protecto.ai/authentication/token-expiry-rotation.md): How Protecto API token lifetimes work and best practices for rotating tokens safely.
- [Authentication Errors](https://docs.protecto.ai/authentication/auth-errors.md): How to identify and resolve Protecto authentication and authorization failures.
- [Masking APIs](https://docs.protecto.ai/masking-apis/overview.md): Overview of all Protecto masking endpoints — from explicit token-based masking to auto-detection of PII in free-form text.
- [Mask with Token](https://docs.protecto.ai/masking-apis/mask-with-token.md): Mask known sensitive values by explicitly specifying the token type. Use when you already know the data type and don't need structure preservation.
- [Mask with Format](https://docs.protecto.ai/masking-apis/mask-with-format.md): Mask sensitive values while preserving the structure of the original — such as phone number punctuation or email domain format.
- [Scan for Personal Data Entities](https://docs.protecto.ai/masking-apis/pii-identification.md): Identify personal data elements — names, email addresses, phone numbers, and more — within free-form text without masking the original values.
- [Identify and Mask (Auto-Detect)](https://docs.protecto.ai/masking-apis/identify-and-mask.md): Automatically detect and mask all PII in free-form text. Entity types, tokens, and detection rules are all driven by your active policy.
- [Mask with Policy](https://docs.protecto.ai/masking-apis/mask-with-policy.md): Apply a named policy to masking requests to control entity detection scope, anonymization vs pseudonymization, and custom entity wrappers.
- [Mask with Attributes](https://docs.protecto.ai/masking-apis/mask-with-attributes.md): Attach custom metadata key-value pairs to masked values for downstream tracking, auditing, or contextual reference.
- [Prefix & Suffix Behavior](https://docs.protecto.ai/masking-apis/prefix-suffix-behavior.md): How Protecto wraps masked values in entity tags, and how to customize prefix and suffix strings through policy metadata.
- [Masking Errors & Limits](https://docs.protecto.ai/masking-apis/errors-limits.md): All error responses, HTTP status codes, and payload limits for Protecto Masking APIs.
- [Unmasking APIs](https://docs.protecto.ai/unmasking-apis/overview.md): Reverse tokenized values back to their original sensitive content. Unmasking is a privileged operation governed by permissions and policies.
- [Unmask](https://docs.protecto.ai/unmasking-apis/unmask-with-token.md): Restore original sensitive values from tokenized text. The API resolves all embedded entity tokens automatically — no token_name required.
- [Unmask with Policy](https://docs.protecto.ai/unmasking-apis/unmask-with-policy.md): Apply a named policy during unmasking to control re-identification behavior and enforce governance rules.
- [Toxicity in Unmask API](https://docs.protecto.ai/unmasking-apis/toxicity-in-unmask.md): Toxicity scores are returned alongside unmasked values when the unmask API runs toxicity analysis on the restored content.
- [Unmasking Errors](https://docs.protecto.ai/unmasking-apis/errors.md): All error responses and HTTP status codes for the Protecto Unmasking API.
- [Async APIs](https://docs.protecto.ai/async-apis/overview.md): Submit large masking or unmasking jobs for background processing and poll for results using a tracking ID.
- [Mask Async](https://docs.protecto.ai/async-apis/mask-async.md): Submit a masking job for background processing and receive a tracking ID to poll for results.
- [Unmask Async](https://docs.protecto.ai/async-apis/unmask-async.md): Submit an unmask job for background processing and receive a tracking ID to poll for results.
- [Async Status Tracking](https://docs.protecto.ai/async-apis/async-status.md): Poll the status of an async mask or unmask job using a tracking ID, and retrieve results when the job completes.
- [Async Status Lifecycle](https://docs.protecto.ai/async-apis/status-lifecycle.md): Understand the lifecycle of Protecto async jobs — from PENDING through SUCCESS, FAILED, or PURGED.
- [Supported Data Types](https://docs.protecto.ai/supported-data-types/overview.md): What data Protecto accepts, how entities, formats, and token types work together, and how to send values correctly.
- [PII, PHI & Financial Entities](https://docs.protecto.ai/supported-data-types/pii-phi-pci-entities.md): Complete reference of all supported PII, PHI, and financial entities with descriptions, examples, and masked output.
- [Token Types](https://docs.protecto.ai/supported-data-types/token-types.md): How token types control the shape and structure of masked output — choosing the right token type for your data and downstream requirements.
- [Supported Formats](https://docs.protecto.ai/supported-data-types/formats.md): Complete list of format names for structure-preserving masking — use these exact strings in the format field of masking requests.
- [Character Encoding](https://docs.protecto.ai/supported-data-types/character-encoding.md): UTF-8 encoding requirements for Protecto API requests and how to handle international characters and Unicode text.
- [Toxicity Detection](https://docs.protecto.ai/toxicity-detection/overview.md): How Protecto automatically analyzes text for harmful content during masking and unmasking, returning structured safety scores.
- [Scoring System](https://docs.protecto.ai/toxicity-detection/scoring-system.md): How Protecto's toxicity scores are calculated, what the scale means, and how to set thresholds for your application.
- [Toxicity Categories](https://docs.protecto.ai/toxicity-detection/categories.md): The six toxicity categories Protecto reports — what each measures and how to use them in your moderation and safety workflows.
- [Toxicity Score Examples](https://docs.protecto.ai/toxicity-detection/examples.md): Real examples showing how different types of language score across toxicity categories — to help calibrate your thresholds.
- [Toxicity in Mask API](https://docs.protecto.ai/toxicity-detection/in-mask-api.md): How toxicity analysis appears in Identify and Mask (Auto-detect) responses alongside masked entity data.
- [Toxicity in Unmask API](https://docs.protecto.ai/toxicity-detection/in-unmask-api.md): How toxicity analysis appears in Unmask API responses — auditing restored content for safety compliance.
- [Data Scanning](https://docs.protecto.ai/data-scanning/overview.md): Discover, classify, and validate personal data across structured data sources — without masking. Data Scanning runs asynchronously and requires a paid subscription.
- [Submit Data Scan](https://docs.protecto.ai/data-scanning/submit-scan.md): Submit an asynchronous data scan job for one or more objects. Returns a tracking ID to check scan progress.
- [Scan Status](https://docs.protecto.ai/data-scanning/scan-status.md): Check the execution status of one or more submitted data scan jobs using their tracking IDs.
- [List Scan Objects](https://docs.protecto.ai/data-scanning/list-scan-objects.md): List objects available for scanning under a data source — filter by database, schema, or list all objects.
- [Scan Details](https://docs.protecto.ai/data-scanning/scan-details.md): Fetch column-level PII detection results with ML confidence scores for a scanned data source object.
- [Update Scan Conclusions](https://docs.protecto.ai/data-scanning/update-conclusions.md): Adjust the confidence threshold used to classify columns as PII — globally or for a specific data source object.
- [Update & Delete Detected Entities](https://docs.protecto.ai/data-scanning/update-delete-entities.md): Manually correct ML-detected PII results — override incorrect detections or remove false positives at the column level.
- [Custom PII & Tag Management](https://docs.protecto.ai/custom-pii/overview.md): Define, configure, and manage custom PII tags for business-specific identifiers — customer IDs, order references, and other internal sensitive data.
- [Identify Custom PII](https://docs.protecto.ai/custom-pii/identify-custom-pii.md): Detect occurrences of a configured custom PII tag within input texts and return their positions.
- [Create or Update Custom Tags](https://docs.protecto.ai/custom-pii/create-update-tags.md): Register a new custom PII tag and configure the identification endpoint Protecto will call to detect it.
- [Configure Identification Endpoints](https://docs.protecto.ai/custom-pii/configure-identification-endpoints.md): Requirements and contract for the customer-hosted endpoint Protecto calls to detect custom PII in text.
- [Configure Whitelist Endpoints](https://docs.protecto.ai/custom-pii/configure-whitelist-endpoints.md): Reduce false positives for custom PII detection by providing a known-valid values endpoint.
- [Retrieve Tag Details](https://docs.protecto.ai/custom-pii/retrieve-tag-details.md): Fetch the full configuration of a custom PII tag including masking behavior and endpoint settings.
- [Delete Custom Tags](https://docs.protecto.ai/custom-pii/delete-tags.md): Remove a custom PII tag and all its associated configuration from the namespace.
- [Error Response Format](https://docs.protecto.ai/errors-limits/error-format.md): The consistent JSON error structure returned by all Protecto API failures.
- [HTTP Status Codes](https://docs.protecto.ai/errors-limits/http-status-codes.md): HTTP status codes used by Protecto APIs and what each means for your integration.
- [Masking Errors](https://docs.protecto.ai/errors-limits/masking-errors.md): Common error messages from the Mask API, what causes them, and how to fix them.
- [Unmasking Errors](https://docs.protecto.ai/errors-limits/unmasking-errors.md): Common error messages from the Unmask API, what causes them, and how to fix them.
- [Rate Limits](https://docs.protecto.ai/errors-limits/rate-limits.md): How Protecto rate limits apply per namespace and subscription tier, and how to handle 429 responses.
- [Payload Limits](https://docs.protecto.ai/errors-limits/payload-limits.md): Size and content constraints on Protecto API requests and how to work within them.
- [Retry Behavior](https://docs.protecto.ai/errors-limits/retry-behavior.md): How Protecto handles internal retries, and recommended client retry strategies for each error type.

## Admin APIs

- [Policy Management](https://docs.protecto.ai/policy-management/overview.md): Create and manage named policies that control how Protecto detects, masks, and treats sensitive data across your namespace.
- [Create Policy](https://docs.protecto.ai/policy-management/create-policy.md): Create a new named policy in the namespace with default entity metadata.
- [List Policies](https://docs.protecto.ai/policy-management/list-policies.md): Return all policy names available in the namespace.
- [View Policy Metadata](https://docs.protecto.ai/policy-management/view-policy-metadata.md): Retrieve entity-level metadata for a policy — which entities are anonymizable, pseudonymizable, or excluded.
- [Update Entity Categories](https://docs.protecto.ai/policy-management/update-entity-categories.md): Move entities between anonymizable, pseudonymizable, and excluded groups within a policy.
- [Update Prefixes & Suffixes](https://docs.protecto.ai/policy-management/update-prefixes-suffixes.md): Customize the prefix and suffix used to wrap masked entity values in auto-detect masking output.
- [Delete Policy](https://docs.protecto.ai/policy-management/delete-policy.md): Permanently delete a policy and all its associated metadata from the namespace.
- [Reporting & Auditing](https://docs.protecto.ai/reporting/overview.md): Visibility into API usage, data access patterns, and full audit trails for compliance, security reviews, and governance.
- [User Namespace Summary](https://docs.protecto.ai/reporting/user-namespace-summary.md): API usage per user within a namespace — call counts, success rates, and login times over a date range.
- [Namespace Summary](https://docs.protecto.ai/reporting/namespace-summary.md): Aggregated API usage counts for a single namespace, grouped by API type and status.
- [All Namespace Summary](https://docs.protecto.ai/reporting/all-namespace-summary.md): API usage counts across all namespaces visible to the admin — for platform-level monitoring and tenant usage overview.
- [Audit Logs](https://docs.protecto.ai/reporting/audit-logs.md): Full audit-level detail for every API request in a namespace — used for compliance audits, security investigations, and forensic analysis.
- [Data Deletion & Retention](https://docs.protecto.ai/data-deletion/overview.md): Admin APIs for enforcing data retention policies — delete stored token mappings and audit records after a defined retention window.
- [Delete Personal Data Mappings](https://docs.protecto.ai/data-deletion/delete-personal-data.md): Delete stored text-to-token mappings older than a specific date or duration to enforce GDPR right-to-erasure and retention policies.
- [Delete Audit Records](https://docs.protecto.ai/data-deletion/delete-audit-records.md): Delete audit log records older than a specific date or duration to enforce log retention policies.
- [Track Deletion Jobs](https://docs.protecto.ai/data-deletion/track-deletion-jobs.md): Monitor the status and outcome of asynchronous data deletion jobs using their tracking IDs.
- [Super Admin APIs](https://docs.protecto.ai/super-admin/overview.md): Manage namespaces, namespace user tokens, and high-impact administrative jobs using the Master API Key.
- [Create Namespace User Token](https://docs.protecto.ai/super-admin/create-namespace-token.md): Create an authentication token for a user within a namespace. If the namespace does not exist, it is created asynchronously.
- [Fetch Token Details](https://docs.protecto.ai/super-admin/fetch-token-details.md): Retrieve metadata for a specific namespace user token — permissions, validity dates, and namespace.
- [List Auth Tokens](https://docs.protecto.ai/super-admin/list-auth-tokens.md): List all namespace user tokens across the system, with optional filtering by namespace.
- [Deactivate Auth Token](https://docs.protecto.ai/super-admin/deactivate-token.md): Immediately revoke a namespace user token — use when credentials are compromised or a user's access should be removed.
- [Delete Namespace](https://docs.protecto.ai/super-admin/delete-namespace.md): Delete an entire namespace including all data, tokens, and metadata. This operation is irreversible and runs asynchronously.
- [Track Namespace Jobs](https://docs.protecto.ai/super-admin/track-namespace-jobs.md): Monitor the status of asynchronous namespace creation and deletion jobs.

## Resources

- [Privacy Vault](https://docs.protecto.ai/release-notes/vault.md): Track Vault-specific changes across versions, including masking, tokenization, policies, async workflows, and admin improvements. Use these notes to understand behavior changes before upgrading or adopting new features.
- [GPTGuard](https://docs.protecto.ai/release-notes/gpt-guard.md): Review the latest GPT Guard changes so you can plan upgrades, validate new capabilities, and understand impact on your deployment.
- [Release Notes](https://docs.protecto.ai/release-notes/version-history.md): Version history for the Protecto API platform — new features, improvements, and changes by release.
- [Deployment Options](https://docs.protecto.ai/deployment/overview.md): Protecto supports SaaS and on-premises deployments. Both expose identical APIs — the difference is where Protecto runs and who operates it.
- [SaaS Deployment](https://docs.protecto.ai/deployment/saas.md): Protecto SaaS — fully hosted and operated by Protecto. The fastest way to get started with zero infrastructure overhead.
- [On-Premises Deployment](https://docs.protecto.ai/deployment/on-premises.md): Run Protecto inside your own infrastructure or private cloud for full data residency control and air-gapped environments.