Skip to content
Australian Privacy Score
  • About
  • API
  • Methodology

API Reference

RESTful JSON API. Analyse privacy posture in your app, run compliance checks, or build trust signals.

Getting Started

Request a free API key — it arrives via email instantly. No OAuth, no approval queue.

Authentication & Rate Limits

Include your API key in the Authorization header as a Bearer token. Public endpoints work without a key but are subject to IP-based rate limits.

TierLimit
Public (no key)60 requests / minute per IP
Free API key1,000 requests / day
Key provisioning5 requests / hour per IP

Every /api/v1/* response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers (RFC 9331). When the limit is exceeded the API returns 429 with an additional Retry-After header indicating seconds until reset.

Request
# Authenticated request
curl https://privacy.theucu.com/api/v1/entities/commbank/claims \
  -H "Authorization: Bearer aps_your_api_key"

# Rate limit exceeded — 429 response
{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry in 60 seconds.",
  "status": 429
}

Endpoints

GET /api/v1/healthGET /api/v1/entitiesGET /api/v1/entities/{slug}GET /api/v1/entities/{slug}/claimsGET /api/v1/entities/{slug}/historyGET /api/v1/sectors/{category}

Your first call

Request
curl https://privacy.theucu.com/api/v1/entities/commbank \
  -H "Authorization: Bearer aps_your_api_key"
GET/api/v1/healthPublic

Returns the current health status of the API. Public endpoint, no authentication required. Useful for uptime monitoring.

Request
curl https://privacy.theucu.com/api/v1/health
Response
{
  "status": "ok",
  "version": "v1"
}
GET/api/v1/entitiesPublic

Search for entities by name or alias. Returns a list of matching entities with their latest privacy grade. Public endpoint.

Parameters

qstringoptional

Search query — matches entity name and known aliases.

categorystringoptional

Filter by sector category (e.g., "Banking & Finance", "Health & Wellness").

limitintegeroptional

Maximum number of results (1–50, default 20).

Request
curl "https://privacy.theucu.com/api/v1/entities?q=commbank"
Response
[
  {
    "slug": "commbank",
    "name": "CommBank",
    "category": "Banking & Finance",
    "latest_grade": "B"
  }
]
GET/api/v1/entities/{slug}Public

Retrieve full details for a single entity: latest score, grade, consumer summary, top headline findings (top 5 claims by confidence), and last scan date. Public endpoint.

Parameters

slugstringrequired

URL-safe entity identifier (e.g., "commbank"). Obtain from the search endpoint.

Request
curl https://privacy.theucu.com/api/v1/entities/commbank
Response
{
  "slug": "commbank",
  "name": "CommBank",
  "category": "Banking & Finance",
  "latest_score": 76,
  "grade": "B",
  "headline_findings": [
    {
      "dimension": "third_party_sharing",
      "claim_type": "named_service_provider",
      "claim_value": {
        "provider_name": "Microsoft",
        "service_type": "artificial intelligence capabilities",
        "purpose": "support AI capabilities"
      },
      "confidence": 0.98,
      "app_reference": "APP 6.2"
    }
  ],
  "consumer_summary": "Basic acknowledgment of children's privacy with 14-year age threshold for parental access.",
  "privacy_policy_url": "https://www.commbank.com.au/support/privacy.html",
  "last_scan_date": "2026-04-19T08:26:53Z",
  "last_changed_date": "2026-04-19T08:26:53Z",
  "scan_id": "0193abcd-1234-7890-abcd-1234567890ab",
  "logo_url": "https://www.commbank.com.au/content/dam/commbank-assets/about-us/commbank-logo.svg",
  "archive_snapshot_date": null
}
GET/api/v1/entities/{slug}/claimsAuth required

Retrieve all structured privacy claims extracted from the entity's latest scan. Returns claim type, dimension, confidence score, and source text. Requires an API key.

Parameters

slugstringrequired

Entity slug (obtain from the search endpoint).

Request
curl https://privacy.theucu.com/api/v1/entities/commbank/claims \
  -H "Authorization: Bearer aps_your_api_key"
Response
[
  {
    "dimension": "third_party_sharing",
    "claim_type": "named_service_provider",
    "claim_value": {
      "provider_name": "Microsoft",
      "service_type": "artificial intelligence capabilities",
      "purpose": "support AI capabilities"
    },
    "confidence": 0.98,
    "app_reference": "APP 6.2",
    "source_text": "We use Microsoft to support our AI capabilities..."
  },
  {
    "dimension": "third_party_sharing",
    "claim_type": "government_law_enforcement_sharing",
    "claim_value": {
      "purpose": "comply with legislative or regulatory obligations",
      "consent_required": false,
      "legal_basis": "legislative or regulatory obligations"
    },
    "confidence": 0.97,
    "app_reference": "APP 6.2",
    "source_text": "We may share information with regulatory and government bodies..."
  }
]
GET/api/v1/entities/{slug}/historyAuth required

Retrieve the full score trajectory for an entity across all completed scans, in descending date order. Each scan includes dimension-level scores and rationale. Requires an API key.

Parameters

slugstringrequired

Entity slug.

Request
curl https://privacy.theucu.com/api/v1/entities/commbank/history \
  -H "Authorization: Bearer aps_your_api_key"
Response
[
  {
    "scan_date": "2026-04-19T08:26:53Z",
    "scan_type": "scheduled",
    "overall_score": 76,
    "grade": "B",
    "dimension_scores": [
      {
        "dimension": "transparency_clarity",
        "score": 8.5,
        "rationale": "Clear language used throughout"
      },
      {
        "dimension": "third_party_sharing",
        "score": 6.0,
        "rationale": "Named service providers disclosed; broader sharing categorical"
      }
    ]
  },
  {
    "scan_date": "2026-01-15T11:02:19Z",
    "scan_type": "scheduled",
    "overall_score": 71,
    "grade": "C",
    "dimension_scores": []
  }
]
GET/api/v1/sectors/{category}Public

Retrieve privacy statistics for an entire sector: average score, entity count, best and worst performers, and ADM readiness rate. Public endpoint. Note: if multiple entities are tied for best or worst, one is returned deterministically.

Parameters

categorystringrequired

Sector category name, URL-encoded (e.g., "Banking%20%26%20Finance").

Request
curl "https://privacy.theucu.com/api/v1/sectors/Banking%20%26%20Finance"
Response
{
  "category": "Banking & Finance",
  "average_score": 68,
  "entity_count": 6,
  "best": {
    "slug": "commbank",
    "name": "CommBank",
    "score": 76
  },
  "worst": {
    "slug": "westpac",
    "name": "Westpac",
    "score": 37
  },
  "adm_readiness": 0.33
}

Error Reference

StatusError codeWhen
400bad_requestInvalid query parameters or slug format
401unauthorizedMissing or invalid API key on authenticated endpoint
404not_foundEntity or sector not found. Includes "Did you mean…?" suggestion for slugs.
429rate_limitedRequest rate limit exceeded
500internal_errorUnexpected server-side error
Error response format
{
  "error": "unauthorized",
  "message": "Missing or invalid API key",
  "status": 401
}

All endpoints are versioned under /api/v1/ with backwards compatibility guarantees.