Cloakrr API Reference

The Cloakrr API enables programmatic document redaction at scale. Integrate directly with your on-prem or cloud systems to process sensitive documents automatically.

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer clk_live_xxxxxxxxxxxxxxxxxxxxxxxx

API keys are scoped to organizations and can be created in your dashboard settings.

Rate Limits

60 requests per minute per API key
Rate limit headers are included in every response:
- X-RateLimit-Limit: Max requests per window
- X-RateLimit-Remaining: Requests remaining
- X-RateLimit-Reset: Unix timestamp when limit resets

Endpoints

Synchronous Redaction

POST /api/v1/redact

Process a single document synchronously. Best for small files (under 10MB) requiring immediate results.

Request:

curl -X POST https://your-domain.com/api/v1/redact \
  -H "Authorization: Bearer clk_live_xxx" \
  -F "file=@document.pdf" \
  -F "framework=hipaa" \
  -F "method=redact"

Parameters:

Field	Type	Required	Description
`file`	File	Yes	Document to process
`framework`	String	No	`hipaa`, `pii`, `pci-dss`, `gdpr` (default: `pii`)
`method`	String	No	`redact` or `anonymize` (default: `redact`)

Response: Binary file with custom headers:

X-Cloakrr-Items-Detected: Number of sensitive items found
X-Cloakrr-Items-Processed: Number of items redacted
X-Cloakrr-Credits-Used: Credits consumed

Scan Only (Detection)

POST /api/v1/scan

Scan a document for sensitive data without processing. Returns detected items as JSON.

Request:

curl -X POST https://your-domain.com/api/v1/scan \
  -H "Authorization: Bearer clk_live_xxx" \
  -F "file=@document.pdf" \
  -F "framework=pii"

Response:

{
  "success": true,
  "file": {
    "name": "document.pdf",
    "type": "application/pdf",
    "size": 245678,
    "pageCount": 5
  },
  "framework": "pii",
  "items": [
    {
      "id": "item_abc123",
      "type": "ssn",
      "category": "identifier",
      "value": "12****89",
      "confidence": 0.95,
      "location": {
        "startIndex": 1234,
        "endIndex": 1245,
        "pageNumber": 2
      }
    }
  ],
  "summary": {
    "totalItems": 15,
    "byCategory": { "identifier": 5, "personal": 10 },
    "byType": { "ssn": 3, "name": 7, "email": 5 }
  },
  "processingTimeMs": 1250
}

Batch Jobs (Async)

POST /api/v1/jobs

Create an async batch job for processing multiple documents.

Request:

curl -X POST https://your-domain.com/api/v1/jobs \
  -H "Authorization: Bearer clk_live_xxx" \
  -F "files=@doc1.pdf" \
  -F "files=@doc2.docx" \
  -F "files=@doc3.xlsx" \
  -F "framework=hipaa" \
  -F "method=anonymize" \
  -F "webhookUrl=https://your-server.com/webhook"

Response:

{
  "success": true,
  "jobId": "job_abc123xyz",
  "status": "pending",
  "estimatedCredits": 15,
  "documentCount": 3,
  "statusUrl": "/api/v1/jobs/job_abc123xyz"
}

GET /api/v1/jobs

List recent jobs for your organization.

Query Parameters:

limit (default: 20, max: 100)
offset (default: 0)

GET /api/v1/jobs/{jobId}

Get job status and results.

Response (completed):

{
  "success": true,
  "id": "job_abc123xyz",
  "status": "completed",
  "progress": 100,
  "documents": [...],
  "result": {
    "totalItemsDetected": 45,
    "totalItemsProcessed": 45,
    "totalCreditsUsed": 15,
    "documents": [
      {
        "originalName": "doc1.pdf",
        "processedName": "doc1_redacted.pdf",
        "downloadUrl": "/api/v1/jobs/job_abc123/download?documentId=xxx",
        "itemsProcessed": 12
      }
    ]
  },
  "createdAt": "2026-01-03T10:00:00Z",
  "completedAt": "2026-01-03T10:02:30Z",
  "expiresAt": "2026-01-04T10:02:30Z"
}

GET /api/v1/jobs/{jobId}/download

Download processed files.

Query Parameters:

documentId (optional): Download specific document

DELETE /api/v1/jobs/{jobId}

Cancel a pending job.

Usage Statistics

GET /api/v1/usage

Get API usage statistics for your organization.

Response:

{
  "success": true,
  "organization": {
    "id": "org_xxx",
    "name": "Acme Corp"
  },
  "credits": {
    "available": 850,
    "used": 150,
    "total": 1000
  },
  "jobs": {
    "last30Days": {
      "completed": 45,
      "failed": 2,
      "total": 47,
      "creditsUsed": 150
    }
  }
}

Error Handling

All errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human readable description"
}

Common Error Codes:

Code	Status	Description
`unauthorized`	401	Invalid or missing API key
`rate_limit_exceeded`	429	Too many requests
`insufficient_credits`	402	Not enough credits
`file_too_large`	413	File exceeds size limit
`service_unavailable`	503	Processing service temporarily down

Webhooks

Set a webhookUrl when creating jobs to receive notifications:

Event: job.completed

{
  "event": "job.completed",
  "jobId": "job_abc123",
  "result": { ... },
  "timestamp": "2026-01-03T10:02:30Z"
}

Event: job.failed

{
  "event": "job.failed",
  "jobId": "job_abc123",
  "error": "Error description",
  "timestamp": "2026-01-03T10:02:30Z"
}

Supported File Types

Type	Extensions	Method
PDF	`.pdf`	Native + OCR fallback
Word	`.docx`	Native
Excel	`.xlsx`, `.xls`, `.csv`	Native
PowerPoint	`.pptx`	Native
Images	`.jpg`, `.png`, `.webp`	OCR

Code Examples

Python

import requests

api_key = "clk_live_xxx"
headers = {"Authorization": f"Bearer {api_key}"}

# Sync redaction
with open("document.pdf", "rb") as f:
    response = requests.post(
        "https://your-domain.com/api/v1/redact",
        headers=headers,
        files={"file": f},
        data={"framework": "hipaa", "method": "redact"}
    )
    
with open("document_redacted.pdf", "wb") as out:
    out.write(response.content)

Node.js

const FormData = require("form-data");
const fs = require("fs");

const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));
form.append("framework", "hipaa");

const response = await fetch("https://your-domain.com/api/v1/redact", {
  method: "POST",
  headers: { "Authorization": "Bearer clk_live_xxx" },
  body: form,
});

const buffer = await response.arrayBuffer();
fs.writeFileSync("document_redacted.pdf", Buffer.from(buffer));

cURL Batch Processing

# Create batch job
JOB_ID=$(curl -s -X POST https://your-domain.com/api/v1/jobs \
  -H "Authorization: Bearer clk_live_xxx" \
  -F "files=@doc1.pdf" \
  -F "files=@doc2.pdf" \
  -F "framework=pii" | jq -r '.jobId')

# Poll for completion
while true; do
  STATUS=$(curl -s https://your-domain.com/api/v1/jobs/$JOB_ID \
    -H "Authorization: Bearer clk_live_xxx" | jq -r '.status')
  
  if [ "$STATUS" = "completed" ]; then
    echo "Job complete!"
    break
  fi
  
  sleep 5
done

# Download results
curl -s https://your-domain.com/api/v1/jobs/$JOB_ID/download \
  -H "Authorization: Bearer clk_live_xxx"

Cloakrr API Reference

The Cloakrr API enables programmatic document redaction at scale. Integrate directly with your on-prem or cloud systems to process sensitive documents automatically.

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer clk_live_xxxxxxxxxxxxxxxxxxxxxxxx

API keys are scoped to organizations and can be created in your dashboard settings.

Rate Limits

60 requests per minute per API key
Rate limit headers are included in every response:
- X-RateLimit-Limit: Max requests per window
- X-RateLimit-Remaining: Requests remaining
- X-RateLimit-Reset: Unix timestamp when limit resets

Endpoints

Synchronous Redaction

POST /api/v1/redact

Process a single document synchronously. Best for small files (under 10MB) requiring immediate results.

Request:

curl -X POST https://your-domain.com/api/v1/redact \
  -H "Authorization: Bearer clk_live_xxx" \
  -F "file=@document.pdf" \
  -F "framework=hipaa" \
  -F "method=redact"

Parameters:

Field	Type	Required	Description
`file`	File	Yes	Document to process
`framework`	String	No	`hipaa`, `pii`, `pci-dss`, `gdpr` (default: `pii`)
`method`	String	No	`redact` or `anonymize` (default: `redact`)

Response: Binary file with custom headers:

X-Cloakrr-Items-Detected: Number of sensitive items found
X-Cloakrr-Items-Processed: Number of items redacted
X-Cloakrr-Credits-Used: Credits consumed

Scan Only (Detection)

POST /api/v1/scan

Scan a document for sensitive data without processing. Returns detected items as JSON.

Request:

curl -X POST https://your-domain.com/api/v1/scan \
  -H "Authorization: Bearer clk_live_xxx" \
  -F "file=@document.pdf" \
  -F "framework=pii"

Response:

{
  "success": true,
  "file": {
    "name": "document.pdf",
    "type": "application/pdf",
    "size": 245678,
    "pageCount": 5
  },
  "framework": "pii",
  "items": [
    {
      "id": "item_abc123",
      "type": "ssn",
      "category": "identifier",
      "value": "12****89",
      "confidence": 0.95,
      "location": {
        "startIndex": 1234,
        "endIndex": 1245,
        "pageNumber": 2
      }
    }
  ],
  "summary": {
    "totalItems": 15,
    "byCategory": { "identifier": 5, "personal": 10 },
    "byType": { "ssn": 3, "name": 7, "email": 5 }
  },
  "processingTimeMs": 1250
}

Batch Jobs (Async)

POST /api/v1/jobs

Create an async batch job for processing multiple documents.

Request:

curl -X POST https://your-domain.com/api/v1/jobs \
  -H "Authorization: Bearer clk_live_xxx" \
  -F "files=@doc1.pdf" \
  -F "files=@doc2.docx" \
  -F "files=@doc3.xlsx" \
  -F "framework=hipaa" \
  -F "method=anonymize" \
  -F "webhookUrl=https://your-server.com/webhook"

Response:

{
  "success": true,
  "jobId": "job_abc123xyz",
  "status": "pending",
  "estimatedCredits": 15,
  "documentCount": 3,
  "statusUrl": "/api/v1/jobs/job_abc123xyz"
}

GET /api/v1/jobs

List recent jobs for your organization.

Query Parameters:

limit (default: 20, max: 100)
offset (default: 0)

GET /api/v1/jobs/{jobId}

Get job status and results.

Response (completed):

{
  "success": true,
  "id": "job_abc123xyz",
  "status": "completed",
  "progress": 100,
  "documents": [...],
  "result": {
    "totalItemsDetected": 45,
    "totalItemsProcessed": 45,
    "totalCreditsUsed": 15,
    "documents": [
      {
        "originalName": "doc1.pdf",
        "processedName": "doc1_redacted.pdf",
        "downloadUrl": "/api/v1/jobs/job_abc123/download?documentId=xxx",
        "itemsProcessed": 12
      }
    ]
  },
  "createdAt": "2026-01-03T10:00:00Z",
  "completedAt": "2026-01-03T10:02:30Z",
  "expiresAt": "2026-01-04T10:02:30Z"
}

GET /api/v1/jobs/{jobId}/download

Download processed files.

Query Parameters:

documentId (optional): Download specific document

DELETE /api/v1/jobs/{jobId}

Cancel a pending job.

Usage Statistics

GET /api/v1/usage

Get API usage statistics for your organization.

Response:

{
  "success": true,
  "organization": {
    "id": "org_xxx",
    "name": "Acme Corp"
  },
  "credits": {
    "available": 850,
    "used": 150,
    "total": 1000
  },
  "jobs": {
    "last30Days": {
      "completed": 45,
      "failed": 2,
      "total": 47,
      "creditsUsed": 150
    }
  }
}

Error Handling

All errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human readable description"
}

Common Error Codes:

Code	Status	Description
`unauthorized`	401	Invalid or missing API key
`rate_limit_exceeded`	429	Too many requests
`insufficient_credits`	402	Not enough credits
`file_too_large`	413	File exceeds size limit
`service_unavailable`	503	Processing service temporarily down

Webhooks

Set a webhookUrl when creating jobs to receive notifications:

Event: job.completed

{
  "event": "job.completed",
  "jobId": "job_abc123",
  "result": { ... },
  "timestamp": "2026-01-03T10:02:30Z"
}

Event: job.failed

{
  "event": "job.failed",
  "jobId": "job_abc123",
  "error": "Error description",
  "timestamp": "2026-01-03T10:02:30Z"
}

Supported File Types

Type	Extensions	Method
PDF	`.pdf`	Native + OCR fallback
Word	`.docx`	Native
Excel	`.xlsx`, `.xls`, `.csv`	Native
PowerPoint	`.pptx`	Native
Images	`.jpg`, `.png`, `.webp`	OCR

Code Examples

Python

import requests

api_key = "clk_live_xxx"
headers = {"Authorization": f"Bearer {api_key}"}

# Sync redaction
with open("document.pdf", "rb") as f:
    response = requests.post(
        "https://your-domain.com/api/v1/redact",
        headers=headers,
        files={"file": f},
        data={"framework": "hipaa", "method": "redact"}
    )
    
with open("document_redacted.pdf", "wb") as out:
    out.write(response.content)

Node.js

const FormData = require("form-data");
const fs = require("fs");

const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));
form.append("framework", "hipaa");

const response = await fetch("https://your-domain.com/api/v1/redact", {
  method: "POST",
  headers: { "Authorization": "Bearer clk_live_xxx" },
  body: form,
});

const buffer = await response.arrayBuffer();
fs.writeFileSync("document_redacted.pdf", Buffer.from(buffer));

cURL Batch Processing

# Create batch job
JOB_ID=$(curl -s -X POST https://your-domain.com/api/v1/jobs \
  -H "Authorization: Bearer clk_live_xxx" \
  -F "files=@doc1.pdf" \
  -F "files=@doc2.pdf" \
  -F "framework=pii" | jq -r '.jobId')

# Poll for completion
while true; do
  STATUS=$(curl -s https://your-domain.com/api/v1/jobs/$JOB_ID \
    -H "Authorization: Bearer clk_live_xxx" | jq -r '.status')
  
  if [ "$STATUS" = "completed" ]; then
    echo "Job complete!"
    break
  fi
  
  sleep 5
done

# Download results
curl -s https://your-domain.com/api/v1/jobs/$JOB_ID/download \
  -H "Authorization: Bearer clk_live_xxx"

API Reference

Cloakrr API Reference

Authentication

Rate Limits

Endpoints

Synchronous Redaction

Scan Only (Detection)

Batch Jobs (Async)

Usage Statistics

Error Handling

Webhooks

Supported File Types

Code Examples

Python

Node.js

cURL Batch Processing

On this page

API Reference

Cloakrr API Reference

Authentication

Rate Limits

Endpoints

Synchronous Redaction

Scan Only (Detection)

Batch Jobs (Async)

Usage Statistics

Error Handling

Webhooks

Supported File Types

Code Examples

Python

Node.js

cURL Batch Processing

On this page