API Reference

Base API Endpoint

https://api.policydiff.org/v1

Integrate our deterministic change monitoring engine into your application through the following endpoints. All requests require anAuthorization: Bearer <YOUR_API_KEY> header.

1. Authentication & Safety

Authenticate requests by including your API key in the Authorization header. For critical requests, we recommend using Idempotency Keys.

Security Warning: Backend Calls Only

The PolicyDiff API cannot be called directly from a browser. Client-side calls are currently blocked by CORS policies to protect your private API key from being exposed in the network tab. Always proxy your requests through a secure backend server.

Note: We are actively developing a secure, token-based architecture to support direct browser-side calls in the future. Stay tuned for updates!

Authorization: Bearer pd_live_...
Idempotency-Key: "uu-id-string-here"

Safely Retry Requests

Ever send a request, have the connection time out, and wonder, "Did it go through?" Retrying without an idempotency key risks duplicate operations and wasted quota.

1. Generate a Unique Key: Send a unique string (e.g., UUID) in theIdempotency-Key header for POST requests.
2. Deterministic Processing: The first time we see the key, we process the request and save the result.
3. Safe Retries: Subsequent requests with the same key will return the cached result immediately without performing a new analysis.

2. Asynchronous Monitoring

The recommended workflow. Submit URLs and receive job IDs immediately. Poll for results without tying up connections.

POST /v1/monitor

Submits a single URL for background analysis.

{
  "url": "https://example.com/privacy"
}

POST /v1/monitor/batch

Submits up to 20 URLs in a single call.

{
  "batch_id": "b2c3d4e5-...",
  "jobs": [
    { "url": "...", "job_id": "c1b2..." }
  ]
}

GET /v1/jobs/:id

Retrieves the status and result of a job.

{
  "status": "COMPLETED",
  "result": {
    "risk_level": "HIGH",
    "changes": [
      {
        "section": "data sharing",
        "details": [/* diff details */]
      }
    ]
  }
}

3. Synchronous Monitoring

POST /v1/check

Real-time check with immediate blocking response.

Optional Query Param

?min_interval=60 /* return cache if checked within 60m */

4. Account Management

GET /v1/usage

Returns usage metrics and quota details.

{
  "quota_limit": 500,
  "quota_remaining": 482,
  "reset_date": "2026-04-01T00:00:00Z"
}

5. Engine Metadata Explained

Every response includes a set of metadata flags and counters that provide insight into the deterministic matching process.

content_isolation

"success" | "failed" — Indicates if the process of isolating policy content from noise (nav, footers, ads) was successful. This confirms the operation completed without structural errors.

isolation_drift

boolean — Triggered when the engine detects a shift in how content is being isolated. This suggests there was a "drift" detected in the content isolation process, implying a deviation from an expected state.

numeric_override_triggered

boolean — Indicates that a specific rule or condition forced a particular outcome based on numerical values, bypassing standard text matching logic.

Technical Note: For maximum change detection precision, our engine normalizes all currency values to their smallest unit (e.g., $699.00 is represented as 69900). This eliminates ambiguity caused by varying decimal separators or currency symbols.

fuzzy_match_count

integer — The number of times a "fuzzy match" occurred. A fuzzy match finds approximate matches when content is not identical (e.g., matching "color" with "colour").

low_confidence_fuzzy_match_count

integer — Counts approximate matches that were made with low confidence, meaning the system was not very sure about the accuracy of the match.

fuzzy_collision_count

integer — Indicates the number of "fuzzy collisions," occurring when the algorithm finds multiple equally plausible approximate matches for a single item.

title_rename_count

integer — Counts how many times a title was automatically adjusted or standardized during the process.

6. Error Codes

Code	Description
INVALID_URL	The provided URL format is invalid.
PAGE_ACCESS_BLOCKED	Target site blocked our scraper (403/WAF).
TIMEOUT	Target site did not respond in time.
QUOTA_EXCEEDED	Monthly API call limit reached for your tier.