Skip to content

REST API Quickstart

Prereqs: any HTTP client · Zotniq API key Time to first call: ~30 seconds

The Zotniq REST API is the wire protocol behind the Python SDK. Use it directly from any language, from curl in a shell, or from a service that can't add the Python SDK as a dependency.

Full endpoint surface: API Reference.

1. Get an API key

Log in to app.zotniq.ai → Settings → API Keys. Copy the key. It looks like zot_sk_....

Never commit it. Load it from an environment variable or your secrets manager.

export ZOTNIQ_API_KEY=zot_sk_...

2. First call

curl -X POST https://api.zotniq.ai/api/preflight/text \
  -H "X-Zotniq-API-Key: $ZOTNIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Contact [email protected] about SSN 123-45-6789",
    "destination": "AI_TOOL"
  }'

3. What you should see

{
  "preflight_id": "pf_...",
  "decision": "ALLOWED_WITH_MASKING",
  "summary": "Content allowed after masking EMAIL, SSN",
  "detected": [
    { "type": "EMAIL", "count": 1, "sample": "b***@example.com" },
    { "type": "SSN",   "count": 1, "sample": "XXX-XX-6789" }
  ],
  "masked_content": "Contact b***@example.com about SSN XXX-XX-6789",
  "policy_version": "1.0",
  "created_at": "2026-08-26T10:30:00Z"
}

Forward masked_content to the AI tool. Never the original.

If the payload contains PHI, decision becomes "BLOCKED" and masked_content is null. Do not forward — surface the summary to the user or route to a human reviewer.

4. Decision reference

Decision Meaning Action
ALLOWED No sensitive data detected Forward the original text.
ALLOWED_WITH_MASKING Sensitive data masked Forward masked_content.
BLOCKED Policy match; do not send Log summary; surface to user.

Every request lands in your team's audit trail. View it in the Zotniq dashboard or export via GET /api/audit.

Troubleshooting

401 Unauthorized

X-Zotniq-API-Key header is missing or the key is invalid. Confirm the header name (case-sensitive) and that the key hasn't been rotated.

422 Validation Error

Missing required fields. text and destination are both required; destination must be one of AI_TOOL, VENDOR, CUSTOMER.

429 Rate Limited

Back off using the retry_after field in the response body, or the standard X-RateLimit-Reset header. See Authentication → Rate Limits.

Next