API Reference

POST /v1/scan

Scan a file for metadata findings. Returns a scan report without modifying the file.

Request:

POST /v1/scan
Content-Type: multipart/form-data
Authorization: Bearer purgit_live_xxx

| Field | Type | Required | Description | |-------|------|----------|-------------| | file | binary | Yes | The file to scan | | policy | string | No | Policy name (strict, standard, minimal, legal, healthcare). Default: standard |

curl example:

curl -X POST https://api.purgit.io/v1/scan \
  -H "Authorization: Bearer $PURGIT_API_KEY" \
  -F "file=@contract.pdf" \
  -F "policy=legal"

Response (200):

{
  "data": {
    "reportId": "rpt_01HX7K9M...",
    "createdAt": "2026-03-06T14:23:11Z",
    "file": {
      "name": "contract.pdf",
      "size": 1048576,
      "format": "pdf",
      "hash": "sha256:a1b2c3d4..."
    },
    "policy": {
      "name": "legal",
      "version": "1.2.0"
    },
    "summary": {
      "totalFindings": 5,
      "bySeverity": {
        "critical": 0,
        "high": 2,
        "medium": 2,
        "low": 1,
        "info": 0
      },
      "autoFixable": 4,
      "requiresReview": 1
    },
    "findings": [
      {
        "ruleId": "PDF-META-001",
        "severity": "high",
        "autofix": true,
        "field": "Author",
        "value": "Jane Smith",
        "path": "/Info/Author",
        "description": "PDF Author field contains personal name",
        "recommendation": "Remove Author field before sharing externally"
      }
    ]
  },
  "requestId": "req_01HX7K9M..."
}

POST /v1/sanitize

Sanitize a file by removing all auto-fixable metadata findings. Returns the clean file as a binary download.

Request:

POST /v1/sanitize
Content-Type: multipart/form-data
Authorization: Bearer purgit_live_xxx

| Field | Type | Required | Description | |-------|------|----------|-------------| | file | binary | Yes | The file to sanitize | | policy | string | No | Policy name. Default: standard | | verify | boolean | No | Run a verification rescan after sanitization. Default: true |

curl example:

curl -X POST https://api.purgit.io/v1/sanitize \
  -H "Authorization: Bearer $PURGIT_API_KEY" \
  -F "file=@contract.pdf" \
  -F "policy=standard" \
  -o contract-clean.pdf

Response (200):

Returns the sanitized file as a binary download with headers:

Content-Type: application/pdf
Content-Disposition: attachment; filename="contract-clean.pdf"
X-Purgit-Report-Id: rpt_01HX7K9M...
X-Purgit-Findings-Removed: 5
X-Purgit-Verification: passed

Use the X-Purgit-Report-Id header to retrieve the full scan report via the reports endpoint.

GET /v1/reports/

Retrieve a stored scan report by its ID. Reports are retained for 30 days on Free tier and 90 days on Pro/Team.

Request:

GET /v1/reports/rpt_01HX7K9M...
Authorization: Bearer purgit_live_xxx

curl example:

curl https://api.purgit.io/v1/reports/rpt_01HX7K9M... \
  -H "Authorization: Bearer $PURGIT_API_KEY"

Response (200):

{
  "data": {
    "reportId": "rpt_01HX7K9M...",
    "createdAt": "2026-03-06T14:23:11Z",
    "file": {
      "name": "contract.pdf",
      "size": 1048576,
      "format": "pdf",
      "hash": "sha256:a1b2c3d4..."
    },
    "policy": {
      "name": "standard",
      "version": "1.2.0"
    },
    "summary": {
      "totalFindings": 7,
      "bySeverity": { "critical": 0, "high": 2, "medium": 3, "low": 1, "info": 1 },
      "autoFixable": 5,
      "requiresReview": 2
    },
    "findings": [ ... ],
    "verification": {
      "status": "verified",
      "residualFindings": 0,
      "verifiedAt": "2026-03-06T14:23:14Z"
    }
  },
  "requestId": "req_01HX8..."
}

GET /v1/policies

List all available scan policies with their rule counts and descriptions.

Request:

GET /v1/policies
Authorization: Bearer purgit_live_xxx

curl example:

curl https://api.purgit.io/v1/policies \
  -H "Authorization: Bearer $PURGIT_API_KEY"

Response (200):

{
  "data": [
    {
      "name": "strict",
      "description": "All rules, all severities",
      "ruleCount": 93,
      "severityThreshold": "info"
    },
    {
      "name": "standard",
      "description": "All rules, medium+ severity",
      "ruleCount": 71,
      "severityThreshold": "medium"
    },
    {
      "name": "minimal",
      "description": "Critical and high severity only",
      "ruleCount": 23,
      "severityThreshold": "high"
    },
    {
      "name": "legal",
      "description": "Legal-profession-specific rules",
      "ruleCount": 58,
      "severityThreshold": "medium"
    },
    {
      "name": "healthcare",
      "description": "HIPAA-focused rules (GPS, dates, device IDs)",
      "ruleCount": 47,
      "severityThreshold": "medium"
    }
  ],
  "requestId": "req_01HX8..."
}

POST /v1/verify

Verify that a previously sanitized file has no remaining findings. Equivalent to running a scan and checking for zero findings.

Request:

POST /v1/verify
Content-Type: multipart/form-data
Authorization: Bearer purgit_live_xxx

| Field | Type | Required | Description | |-------|------|----------|-------------| | file | binary | Yes | The sanitized file to verify | | policy | string | No | Policy to verify against. Default: standard |

curl example:

curl -X POST https://api.purgit.io/v1/verify \
  -H "Authorization: Bearer $PURGIT_API_KEY" \
  -F "file=@contract-clean.pdf"

Response (200):

{
  "data": {
    "status": "verified",
    "residualFindings": 0,
    "policy": "standard",
    "verifiedAt": "2026-03-06T14:23:14Z",
    "file": {
      "name": "contract-clean.pdf",
      "hash": "sha256:e5f6g7h8..."
    }
  },
  "requestId": "req_01HX8..."
}

If findings remain:

{
  "data": {
    "status": "partial",
    "residualFindings": 2,
    "findings": [ ... ],
    "policy": "standard",
    "verifiedAt": "2026-03-06T14:23:14Z"
  },
  "requestId": "req_01HX8..."
}

GET /v1/health

Public health check endpoint. No authentication required.

curl example:

curl https://api.purgit.io/v1/health

Response (200):

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-03-06T14:23:11Z"
}

Next Steps

• Policies & Rules — Understand which rules each policy includes.
• Integrations — Code examples for Node.js, Python, GitHub Actions, and webhooks.