📚 API Documentation

PrivoNest is a developer-first AI Privacy Gateway with multilingual PII protection and API Security Preflight v1.0.5. The privacy engine exposes 37 production languages, 153 country profiles (52 strong-format + 101 baseline-contextual), document/OCR workflows, multiple transformation strategies and reversible tokenization. The security engine exposes 62 detector categories with AST/cross-file analysis, private dependency intelligence, baselines and SARIF reporting.

🔐 Authentication

Protected API routes require your PrivoNest API key in the request header. Get a key through the normal registration and verification flow.

X-API-Key: your-api-key-hereCopy

⚡ Quick Start

1. Get your key

Create an account, verify it, then copy the API key from the dashboard.

2. Protect text

import requests

r = requests.post(
    "https://privonest.cloud/v1/hide",
    headers={"X-API-Key": "YOUR_KEY"},
    json={
        "text": "My name is Ali Khan and email is ali@example.com",
        "language": "auto",
        "country": "PK",
        "strategy": "label"
    }
)
print(r.json()["result"])Copy

🔒 POST /v1/hide

Unified protection endpoint for text, JSON and supported files.

Multipart file

curl -X POST https://privonest.cloud/v1/hide   -H "X-API-Key: YOUR_KEY"   -F "file=@invoice.pdf"   -F "content_type=pdf"   -F "language=auto"   -F "strategy=redact"Copy

Binary results are returned as file_base64 with output media type and detection metadata.

🔓 POST /v1/reveal

Reverses only PrivoNest PV1 tokens created with strategy=tokenize.

r = requests.post(
    "https://privonest.cloud/v1/reveal",
    headers={"X-API-Key": "YOUR_KEY"},
    json={"text": "PV1.EMAIL....", "strict": True}
)Copy

🧭 POST /v1/infer

Explains automatic language and country activation before redaction.

{"text":"میرا CNIC 42101-1234567-1 ہے", "language":"auto"}

🧠 GET /v1/capabilities

No API key is required by the current route. Use this endpoint as the source of truth for exact runtime coverage: language count, country profile details, recognizer counts, document types, transformations, validators, OCR support and dependency status.

curl https://privonest.cloud/v1/capabilitiesCopy

🗄️ POST /v1/scan/database

Database scanning is available only when the deployment enables ALLOW_DATABASE_SCANNING. Use dry_run=true first. The endpoint can select tables, set row limits and optionally transform writable string fields.

💚 Health

Liveness reports engine status; readiness can additionally verify the database depending on deployment settings.

🌍 37 Production Languages

The engine constant currently contains all languages below. Explicit codes can be provided, or auto can infer relevant languages.

🪪 Country Coverage: 52 Strong-Format Profiles

The supplied pii_patterns.json explicitly marks 52 country profiles as strong-format and 101 as baseline-contextual, for 153 total profiles. Strong-format means the profile contains country-specific format rules and metadata; it does not mean every identifier is covered or independently benchmarked. Use /v1/capabilities for the runtime tier, entity list and exact-local-ID readiness flag.

Open the dedicated country coverage page →

📄 Document & Data Types

Current capability output lists: text, JSON, PDF, DOCX, XLSX, CSV, image, email, DICOM and transcript. MIME aliases also cover SRT/VTT transcript-like inputs.

🛡️ Protection Strategies

🤖 Python SDK v1.0.5 STABLE

The v1.0.5 SDK combines the textual AI Privacy Guard with API Security Preflight. Automatic LLM-provider interception is text-focused; supported file/document privacy processing remains available through POST /v1/hide.

from openai import OpenAI
from privonest_guardrail import Guard

client = Guard().wrap(OpenAI())Copy

Open SDK guide · Download SDK source · SDK support form

🛡️ API Security Preflight v1.0.5

Use POST /v1/security/preflight-v7 or the privonest CLI to scan supported Python, JavaScript and TypeScript project source plus recognized dependency manifests/lockfiles. The current release exposes 62 detector categories, Python AST and cross-file route analysis, private dependency intelligence, stable fingerprints, suppressions, baseline comparison, policy gates and SARIF reporting. v1.0.5 also groups repeated symptoms into root-cause findings and applies conservative reachability-aware severity to exploitability-dependent code paths; reports retain affected fields/routes, original severity and raw-signal counts for explainability.

export PRIVONEST_API_KEY="YOUR_KEY"
privonest . --fail-on high
privonest . --sarif privonest.sarifCopy

Source privacy boundary: source scans are processed by the PrivoNest API Security Engine. The v1.0.5 scan route does not use external AI for source analysis and does not make live npm/PyPI lookups during customer scans.

Security endpoints

⚠️ Errors

📊 Privacy Credits & Limits

Plans are metered in Privacy Credits instead of raw HTTP-call count. The same wallet is shared by privacy operations and API Security Preflight; deep code scans intentionally consume more credits than small text calls. Defaults: text/JSON/transcript/CSV use 1 credit per 2,000 input characters (minimum 1); DOCX/XLSX/email/other binary inputs use 1 credit per 64 KiB; PDF/image/DICOM use the binary credit amount ×2 because media/OCR processing is heavier. These thresholds are deployment-configurable and are published by /v1/capabilities. File upload limit remains deployment-configurable through MAX_UPLOAD_BYTES.

💳 Pricing

See the homepage pricing section for the current public plan presentation. For integration or higher-volume requirements, use the private contact form.