PiiBlur

If your application accepts user-uploaded photos, fleet footage, claim documentation, or any other visual media, redaction belongs in the upload pipeline. Faces, license plates, documents, screens, and badges often appear in files that were never meant to expose personal data.

This guide covers the PiiBlur REST API: uploading media, checking status, downloading results, setting up webhooks, and building a batch pipeline. All examples use cURL to stay language-agnostic. For the full endpoint reference, see the API documentation. For narrower examples, see the Face Blur API, License Plate Blur API, Image Redaction API, and Video Redaction API pages.

Authentication and Base URL

Every request requires a Bearer token. Generate an API key from the API section of your PiiBlur dashboard.

curl -X GET https://piiblur.com/api/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response confirms your key and returns current usage and plan limits. All endpoints live under https://piiblur.com/api/v1/.

Uploading Media for PII Redaction

Submit an image or video with a multipart POST request. Specify at least one PII category to redact.

curl -X POST https://piiblur.com/api/v1/media/redact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "categories[]=heads" \
  -F "categories[]=license_plates"

The response returns a public media object with a queued status:

{
    "id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "status": "queued",
    "filename": "photo.jpg",
    "media_type": "image",
    "categories": ["heads", "license_plates"],
    "redaction_method": "blur",
    "file_size_bytes": 482391,
    "duration_seconds": null,
    "created_at": "2026-03-11T14:30:00+00:00",
    "processed_at": null,
    "failed_at": null
}

Specify the redaction method - blur or pixelation - per request:

curl -X POST https://piiblur.com/api/v1/media/redact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "categories[]=heads" \
  -F "categories[]=documents" \
  -F "redaction_method=pixelation"

Images process in seconds. Video processing time depends on duration and resolution.

Checking Job Status

Poll the status endpoint to check completion:

curl -X GET https://piiblur.com/api/v1/media/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H "Authorization: Bearer YOUR_API_KEY"

A completed job returns a download_url:

{
    "id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "status": "completed",
    "filename": "photo.jpg",
    "media_type": "image",
    "categories": ["heads", "license_plates"],
    "redaction_method": "blur",
    "file_size_bytes": 482391,
    "duration_seconds": null,
    "created_at": "2026-03-11T14:30:00+00:00",
    "processed_at": "2026-03-11T14:30:04+00:00",
    "failed_at": null,
    "download_url": "https://piiblur.com/api/v1/media/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/download"
}

The download_url field appears only after processing completes.

Downloading Redacted Output

Fetch the redacted file with a GET request to the download URL:

curl -X GET https://piiblur.com/api/v1/media/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o redacted_photo.jpg

Downloads require your API key. Store the redacted file in your own storage as part of your pipeline.

Using Webhooks Instead of Polling

Polling works for simple integrations, but webhooks suit production systems better. Register a webhook endpoint in the dashboard, and PiiBlur POSTs to it when a job completes, fails, or when the original source file is deleted.

Configure webhook endpoints in the API section of your dashboard. Webhooks are team-level, not passed per upload request.

Webhook payloads include an event ID, timestamp, event name, media ID, status, and a nested media object that uses the same public fields as the media status endpoint. Completed redacted media includes an authenticated media.download_url. Verify the X-PiiBlur-Signature header to confirm the request originated from PiiBlur. Signature verification details are in the API documentation.

For a production architecture with idempotency keys, event deduplication, download workers, and retry queues, see How to Build a Webhook-Based Redaction Pipeline.

Building a Batch Processing Pipeline

Most production workloads process many files, not one at a time. A batch pipeline submits jobs in parallel and collects results via webhooks.

The workflow:

Queue files. Your application collects files - from user uploads, a storage bucket, or a scheduled scan - and places them in a processing queue.
Submit jobs in parallel. POST each file to the media endpoint. The API accepts concurrent requests within your plan's rate limits.
Receive webhook callbacks. As each job completes, PiiBlur sends the result to your webhook endpoint.
Store redacted output. Your webhook handler downloads the redacted file and writes it to storage.
Handle failures. If a job fails, use the failed webhook status to trigger retries or manual review.

This pattern scales to any volume. A pipeline processing 10,000 images per day follows the same logic as one processing 10 - only concurrency and queue management differ.

For high-throughput integrations, see the API documentation for per-plan rate limits and response headers.

Choosing PII Categories for Your Use Case

PiiBlur detects 13 PII categories: heads, license plates, screens, writing, street signs, ID cards, passports, credit cards, name badges, QR codes, barcodes, documents, and tattoos. Not every use case requires all of them.

Select categories based on your data, review criteria, and privacy program:

User-uploaded photos - heads and documents are usually the priority
Street-level imagery - heads, license plates, and street signs
Fleet dashcam footage - heads, license plates, and screens
Real estate photography - heads, screens, and name badges
Healthcare facility footage - heads, ID cards, name badges, and documents

Specifying only the categories you need keeps processing fast and avoids over-redaction.

For large batch workflows, category selection also affects cost - fewer categories mean faster processing and lower per-image compute.

Error Handling

The API returns standard HTTP status codes. Handle these in your integration:

401 - invalid or expired API key
409 - idempotency key reused with a different payload, or a matching request is still in progress
422 - validation error (missing file, unsupported format, invalid category, or video over 10 minutes)
429 - quota or rate limit exceeded; rate-limit responses include Retry-After
500 - server error; retry with exponential backoff

All JSON errors use the standard { "error": ..., "request_id": ... } envelope. Check the response status before assuming success, and log the request_id with the response body to aid debugging.

Review Gates

Not every completed job should go straight to publication. Add a review gate when media is destined for public release, legal disclosure, healthcare, education, law enforcement, or any workflow involving children or vulnerable people.

For lower-risk internal workflows, sample completed outputs instead of reviewing everything. Track misses by source type and category. If reviewers repeatedly find plates in night footage or screen text in office walkthroughs, make that a workflow rule rather than a reviewer memory test.

Use the automated redaction QA checklist as a starting point for review policy.

Pricing and Rate Limits

PiiBlur's free tier includes 100 images and 5 minutes of video per month - enough to build and test your integration. Paid plans start at $49/month and scale to $499/month for high-volume operations. Each tier increases rate limits and monthly quotas.

Full plan details are on the pricing page.

Start Building

The fastest way to evaluate the API: process a few of your own images. Grab an API key from the dashboard, run the upload cURL example above, and inspect the output. Then wire up webhooks, build your batch queue, and deploy. The API documentation covers every endpoint, parameter, and response format.