API Reference

The PiiBlur API lets you detect and redact PII from images and videos programmatically. Upload media, choose which PII categories to redact, and download the processed result.

To get started, create an API key in your dashboard.

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from the API section of your dashboard.

bash

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

Base URL

All endpoints are relative to:

https://piiblur.com/api/v1

Rate Limits

Rate limits vary by plan. When exceeded, the API returns 429 Too Many Requests.

Plan	Requests / minute
Free	60
Starter	120
Pro	300
Scale	1,000
Enterprise	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit — Maximum requests per minute
X-RateLimit-Remaining — Requests remaining in current window
X-RateLimit-Reset — Unix timestamp when the window resets

Errors

The API uses standard HTTP status codes. Errors include a JSON body with an error field.

json

{
  "error": "Monthly image quota exceeded"
}

Status	Description
200	Success
201	Created
204	No content
400	Bad request
401	Unauthorized — invalid or missing API key
404	Not found
422	Validation error
429	Rate limit or quota exceeded
500	Internal server error

POST /media/redact

Upload a file and start redaction in a single request.

Parameters

Name	Type	Required	Description
`file`	file	Required	The image or video file to redact
`pii_categories`	string[]	Required	PII types to detect. Values: heads, license_plates, screens, writing, street_signs, id_cards, passports, credit_cards, name_badges, qr_codes, barcodes, documents, tattoos
`obfuscation_type`	string	Optional	blur (default) or pixelation

Request

bash

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

Response

json

{
  "media_id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "status": "queued"
}

Max file size 1 GB. Supported formats: jpg, jpeg, png, webp, mp4, mov, webm. Video max duration 10 minutes.

GET /media/{mediaId}

Get the status and details of a media file. Pass the media ID as a path parameter.

Request

bash

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

Response

json

{
  "media_id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "status": "completed",
  "original_filename": "photo.jpg",
  "media_type": "image",
  "pii_categories": ["heads", "license_plates"],
  "obfuscation_type": "blur",
  "error_message": null,
  "created_at": "2026-03-17T10:30:00+00:00",
  "processed_at": "2026-03-17T10:30:15+00:00",
  "download_url": "https://piiblur.com/api/v1/media/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/download"
}

The download_url field is only present when status is completed. Download requires authentication with your API key.

GET /media/{mediaId}/download

Download the processed (redacted) file. Returns the file as a streamed response.

Request

bash

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

Response

Returns the file binary with appropriate Content-Type and Content-Disposition headers. Returns 404 if the media is not yet processed.

GET /media/{mediaId}/original

Download the original (unprocessed) file. Returns the file as a streamed response.

Request

bash

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

Response

Returns the file binary with appropriate Content-Type and Content-Disposition headers. Returns 404 if the original file has been deleted.

By default, original files are deleted immediately after processing completes. You can configure the retention period in your dashboard settings.

GET /media

List media files with optional filters. Results are paginated with 20 items per page.

Parameters

Name	Type	Required	Description
`status`	string	Optional	Filter by status (queued, processing, completed, failed, quota_exceeded)
`media_type`	string	Optional	Filter by type (image or video)
`page`	integer	Optional	Page number

Request

bash

curl "https://piiblur.com/api/v1/media?status=completed&page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "data": [
    {
      "media_id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "status": "completed",
      "original_filename": "photo.jpg",
      "media_type": "image",
      "created_at": "2026-03-17T10:30:00+00:00"
    }
  ],
  "current_page": 1,
  "last_page": 5,
  "per_page": 20,
  "total": 98
}

DELETE /media/{mediaId}

Delete a media file and its associated storage. Pass the media ID as a path parameter.

Request

bash

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

Response

Returns 204 No Content on success.

GET /usage

Get current billing period usage and limits.

Request

bash

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

Response

json

{
  "plan": "pro",
  "period_start": "2026-03-01",
  "period_end": "2026-03-31",
  "images": {
    "used": 1250,
    "limit": 25000
  },
  "video_minutes": {
    "used": 45,
    "limit": 60
  }
}

Webhooks

Webhooks notify your server when media processing completes, fails, or when the original source file is deleted. Configure webhook endpoints in the API section of your dashboard.

Events

Event	Description
media.processed	Media has been successfully processed and is ready for download
media.failed	Media processing failed
media.source_deleted	Original source file has been deleted

Signature Verification

Each webhook request includes an X-PiiBlur-Signature header containing an HMAC-SHA256 signature of the request body. Verify the signature to ensure the request originated from PiiBlur.

text

X-PiiBlur-Signature: sha256=HMAC_SHA256(payload, secret)

The secret is displayed once when you create a webhook in the dashboard. Store it securely.

Payload: media.processed

json

{
  "event": "media.processed",
  "media_id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "status": "completed",
  "processed_at": "2026-03-17T10:30:15+00:00",
  "download_url": "https://piiblur.com/api/v1/media/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/download"
}

Payload: media.failed

json

{
  "event": "media.failed",
  "media_id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "status": "failed",
  "processed_at": null,
  "error_message": "Processing failed"
}

Payload: media.source_deleted

json

{
  "event": "media.source_deleted",
  "media_id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "deleted_at": "2026-03-17T10:30:15+00:00"
}

The download_url in the media.processed payload requires authentication with your API key to download the file.