📚 API Documentation

PrivoNest is a easy-to-integrate AI Privacy Gateway with multilingual PII protection 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 Privacy Console adds application policies, scoped keys, a text gateway, metadata audit, testing and governance evidence. Open the new integration guide.

🔐 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

Requires a scoped application key with separate reveal permission. Accepts unexpired PV2 tokens belonging to that same company/app and subject. Old PV1 tokens are rejected. See migration and scoped protection guidance.

r = requests.post(
    "https://privonest.cloud/v1/reveal",
    headers={"X-API-Key": "YOUR_APP_REVEAL_KEY"},
    json={"text": "PV2.v1.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.1.0

The SDK's AI Privacy Guard wraps your LLM calls automatically; 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

⚠️ Errors

📊 Privacy Credits & Limits

Plans are metered in Privacy Credits instead of raw HTTP-call count. The same wallet is shared across privacy operations; larger documents 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.

Easy integration with your existing workflow

For email, Drive and cloud content, your authorized application retrieves selected text, calls /v1/hide and forwards the successful protected result. Source permissions and extraction remain in your connector. Native mailbox/Drive sync and chatbot-website interception are not part of this release.

Use the included Guard adapters for supported OpenAI, Anthropic, Gemini, Ollama, LangChain and LlamaIndex calls. For RAG, evaluate protection before indexing and/or after retrieval. A local Ollama model still needs a configured PrivoNest endpoint when using the HTTP Guard SDK; the bundled local benchmark calls the engine directly instead.

import os
import requests

base = os.environ["PRIVONEST_BASE_URL"].rstrip("/")
response = requests.post(
    f"{base}/v1/hide",
    headers={"X-API-Key": os.environ["PRIVONEST_API_KEY"]},
    json={"content_type": "text", "strategy": "label",
          "text": "Reply to care@example.com about the appointment."},
    timeout=(5, 30),
)
response.raise_for_status()
print(response.json())

Inspect the returned content and metadata before forwarding. Do not forward the original sensitive input as a fallback when protection fails.

Application policies and supporting governance records

The Privacy Console contains registered applications, saved policies, scoped keys, configured provider gateway requests, activity metadata, vendor assessments, risk records and readiness evidence. It does not automatically discover every app or certify compliance.

POST /v1/chat/completions
X-API-Key: YOUR_SCOPED_GATEWAY_KEY
Content-Type: application/json

{
  "model": "YOUR_PROVIDER_ID/YOUR_ALLOWED_MODEL",
  "stream": false,
  "messages": [{"role": "user", "content": "Summarize this approved text."}],
  "max_tokens": 256
}

Configure the provider and exact model first. Follow the application policy guide or watch the integration walkthroughs.

Local engine evaluation

The updated source package includes run_local_benchmark.py, a held-out regional synthetic dataset, model download and quantization tools, and setup instructions. The runner imports the engine directly without Flask, PostgreSQL or Railway API calls. It records full input/output, entity errors, precision, recall, F1, exact-row accuracy and latency.

Test native scripts, mixed languages and Romanized writing separately. Coverage and benchmark results are not equal-accuracy guarantees across languages. Synthetic cases do not establish real-client accuracy; validate representative authorized client data separately.