CloakBioGuard API

API Documentation

Protect photos from facial recognition at scale. Simple REST API with async processing.

Authentication

All API v1 requests require an API key passed via the X-API-Key header.

curl https://api.cloakbioguard.com/v1/health \
  -H "X-API-Key: bsk_your_api_key"

Endpoints

GET/v1/health

Health check. No authentication required.

Response

{ "status": "ok", "version": "1.0.0" }
POST/v1/protect

Submit a photo for protection. Returns a job ID for async polling. Optionally include a webhook_url to receive a POST callback when the job completes.

curl -X POST https://api.cloakbioguard.com/v1/protect \
  -H "X-API-Key: bsk_your_api_key" \
  -F "file=@headshot.jpg" \
  -F "webhook_url=https://your-server.com/hooks/bioshield"

Response

{
  "job_id": "abc-123-def",
  "status": "processing",
  "backend": "default",
  "webhook_url": "https://your-server.com/hooks/bioshield"
}
GET/v1/status/:job_id

Check the status of a protection job.

curl https://api.cloakbioguard.com/v1/status/abc-123-def \
  -H "X-API-Key: bsk_your_api_key"

Response

{
  "job_id": "abc-123-def",
  "status": "completed",
  "created_at": 1708646400.0,
  "completed_at": 1708646412.0,
  "download_url": "/v1/download/abc-123-def"
}
GET/v1/download/:job_id

Download the protected image. Only available after job completes.

curl -O https://api.cloakbioguard.com/v1/download/abc-123-def \
  -H "X-API-Key: bsk_your_api_key"

Response

Binary PNG image data
POST/v1/batch-protect

Submit up to 20 photos for batch protection.

curl -X POST https://api.cloakbioguard.com/v1/batch-protect \
  -H "X-API-Key: bsk_your_api_key" \
  -F "files=@photo1.jpg" \
  -F "files=@photo2.jpg" \
  -F "files=@photo3.jpg"

Response

{
  "jobs": [
    { "job_id": "job-1", "status": "processing" },
    { "job_id": "job-2", "status": "processing" },
    { "job_id": "job-3", "status": "processing" }
  ]
}

Webhooks

When submitting a job via POST /v1/protect, you can include a webhook_url form field. When the job completes (or fails), CloakBioGuard will POST a JSON payload to your URL:

// On success:
{
  "job_id": "abc-123-def",
  "status": "completed",
  "download_url": "/v1/download/abc-123-def"
}

// On failure:
{
  "job_id": "abc-123-def",
  "status": "failed",
  "error": "No face detected"
}

Webhook delivery is best-effort with a 10-second timeout. We recommend still polling /v1/status as a fallback.

Backends

CloakBioGuard uses a pluggable backend architecture. The active protection algorithm is returned in job responses. Query available backends:

curl https://api.cloakbioguard.com/v1/backends

# Response: { "active": "default", "available": ["default"] }

Currently powered by our internal cloaking backend. Additional backends will be added as new protection algorithms emerge.

Rate Limits

Default rate limit is 100 requests per day per API key. Contact us for higher limits. Rate-limited responses return HTTP 429.

Error Handling

401

Missing or invalid API key

404

Job not found

422

No face detected in the image

429

Rate limit exceeded

500

Internal server error

Pricing

API pricing is metered per protected image:

  • 1–1,000/month: $0.99/photo
  • 1,001–10,000/month: $0.69/photo
  • 10,001+/month: $0.49/photo

Enterprise plans with custom SLAs available. Contact sales@cloakbioguard.com.