API overview - privacytracker

The privacytracker HTTP API lives under app/api/** in the Next.js bundle. Every endpoint is a thin wrapper over a helper in lib/. Public request and response shapes are stable. The interactive endpoint pages with Try it support are auto-generated from openapi.yaml — see the API Reference sidebar for per-endpoint detail. This page covers the cross-cutting concerns: authentication, CSRF, rate-limiting, and how to recognise the response shapes.

Base URL

http://localhost:3000

Self-hosted users should substitute their own base URL (and host header — see the CSRF section). The OpenAPI spec defaults to localhost; change the Server dropdown in the playground to match your deployment.

Authentication

Three layers. Only the middle one is confined to mutations — reads pass the host allowlist like everything else, and on a network-exposed instance a list of sensitive read paths needs the admin token too.

Host allowlist (always on, every method)

Before any other check, a request whose effective Host isn’t allowlisted is rejected — GET included:

{ "error": "Host not allowed" }

with status 400. The allowlist defaults to loopback; operators extend it with PRIVACYTRACKER_ALLOWED_HOSTS. If your integration talks to the instance under a hostname the operator hasn’t listed, every call fails here regardless of method or credentials.

Same-origin CSRF check (always on, mutations)

Every mutating verb (POST, PUT, PATCH, DELETE) under /api/ checks that the Origin header matches the request host, unless the request carries a valid admin token instead. Browser requests from your installed UI satisfy this automatically; cross-origin or curl-from-a-different-host calls won’t.Failed CSRF returns 403:

{ "error": "Cross-origin mutation rejected" }

From curl, set the header explicitly:

curl -X POST http://localhost:3000/api/reset \
  -H "Origin: http://localhost:3000"

If you’re behind a reverse proxy, the proxy must forward the original Host header. See Troubleshooting → Reverse-proxy CSRF rejection.

Admin token (optional, opt-in)

When AUDITOR_ADMIN_TOKEN is set in the environment, destructive routes (POST /api/reset, DELETE /api/apps, POST /api/settings, DELETE /api/wayback/import-all, etc.) require the token on top of the CSRF check. Verification uses crypto.timingSafeEqual. Missing or wrong token returns 401:

{ "error": "Admin token required" }

Failed attempts are recorded in the audit_log table with requester IP + user agent.

curl -X POST http://localhost:3000/api/reset \
  -H "Origin: http://localhost:3000" \
  -H "X-Auditor-Admin-Token: $AUDITOR_ADMIN_TOKEN"

Reads are gated too on a network-exposed instance. Once the operator sets PRIVACYTRACKER_NETWORK_EXPOSED, lists a non-loopback host, or binds to a specific non-loopback IP, GET requests under these prefixes also need the token:

/api/ai/debug-log
/api/backup/
/api/deployment/
/api/desktop/diagnostics
/api/diagnostics/
/api/export
/api/import/

Without it they return 401 { "error": "Admin token required for non-local API access" }. This is the usual cause of a surprise 401 on GET /api/backup/export from a LAN integration.Two of those reads don’t wait for exposure. GET /api/backup/export and GET /api/ai/debug-log check adminTokenConfigured() || isNetworkExposed() in the handler itself, so they return 401 { "error": "Admin token required" } as soon as AUDITOR_ADMIN_TOKEN is set — on a loopback-only install too.Cookie sessions. POST /api/auth/admin-token/login with { "token": "..." } exchanges the token for an 8-hour HttpOnly pt_admin_token cookie, which every gated route accepts in place of the header. POST /api/auth/admin-token/logout clears it; GET /api/auth/admin-token/status returns { configured, unlocked }. Login and logout enforce same-origin themselves and login is capped at 5 attempts per minute; status is a read, so neither its handler nor the CSRF layer origin-checks it — it still has to clear the host allowlist, and it never returns the token. Prefer the header for scripted callers; the cookie exists so the browser UI never holds the raw secret in JavaScript.The token is a single shared secret — there’s no built-in user/account system in privacytracker. The intent is to gate destructive routes when the app is exposed beyond a single-user trusted boundary (e.g., self-hosted on a LAN).

Conventions

A handful of patterns hold across every endpoint:

apps.id is Apple’s numeric track ID, extracted from /id<digits>/ in the App Store URL — not a UUID. Snapshots, privacy rows, and notifications all key off it.
Timestamps are Unix milliseconds, not seconds and not ISO-8601. JavaScript Date.now()-shaped.
Errors are { "error": "<message>" } with the appropriate 4xx / 5xx status. The message is human prose, not a stable machine code — switch on the status, not the string. A few routes add structured fields alongside it (POST /api/backup/restore sends code: "untrusted_backup" on a 409); those are documented per-endpoint.
Streamed responses (POST /api/wayback/import-all?stream=1) emit NDJSON with a kind field per line — batch-start, app-start, target, app-done, summary.
Mutation routes returning 409 mean a mutex is held by another in-flight run. Wait or check GET /api/tasks/active to see what’s running.

Rate limiting

A 429 from privacytracker has two possible causes, and they need different handling. privacytracker’s own limiter. Most routes are rate-limited per client IP. Some denials carry a Retry-After header in seconds — honour it when it’s there, but don’t depend on it. A clear majority of the 429 paths set it — 33 of the 56 rate-limited routes: all 23 behind the shared mutation guard, plus 10 direct callers such as /api/scrape, /api/search, and the token login. The rest return a bare 429 — including POST /api/reset and POST /api/backup/restore in the table below — so fall back to the route’s own window when the header is absent. Representative limits:

Route	Limit
`POST /api/scrape`	30 / minute
`POST /api/search`	60 / minute
`POST /api/reset`	30 / 10 minutes
`POST /api/backup/restore`	3 / 10 minutes
`POST /api/auth/admin-token/login`	5 / minute

Note that unless the operator sets PRIVACYTRACKER_TRUST_PROXY, forwarded-IP headers are ignored and every caller shares one bucket per route — so a busy sibling integration can consume your budget. Apple’s 429, on the iTunes Search API and apps.apple.com, is the slower one. It surfaces through the bulk runners rather than as an HTTP status on your call:

The runner bails out of its loop on the first 429.
A partial: rateLimited activity row is written.
State and mutex are cleared cleanly, so the next 30-minute scheduler tick can retry fresh.

Tell them apart by where the 429 lands, not by Retry-After — the internal limiter sets that header on some routes only. An internal denial arrives as an HTTP 429 on the call you just made and clears within that route’s own window (under a minute for /api/scrape). If you’re seeing repeated partial: rateLimited in the activity log with no 429 on your own requests, that’s Apple, and the useful response is to slow the schedule rather than retry.

Backup bundle format

GET /api/backup/export and POST /api/backup/restore use a versioned JSON envelope carrying an integer version (currently 1) — the bundle format version, not the app version. The canonical implementation is lib/backup.ts. A bundle from an older format restores into a newer release; a newer one is refused outright rather than misparsed. Envelopes are HMAC-signed with a key unique to the install that exported them. A bundle from a different install fails verification and gets 409 { "error": "...", "code": "untrusted_backup", "signaturePresent": true }. To restore it anyway, pass ?allowUntrusted=1 or the header x-allow-untrusted-backup: 1. There is no confirm parameter — the RESTORE typing step is browser-side only. Private annotations (visibility = 'private') are unconditionally excluded from audit-bundle exports at the SQL level. There is no force-include path.

Pagination

GET /api/apps supports opt-in pagination for large fleets. Without parameters it returns the complete fleet as a bare JSON array — stable for existing consumers, but the response grows linearly with the fleet (~0.7 KB per app). Passing limit (1–500, plus an optional offset) switches the response to an envelope:

{ "apps": [...], "total": 5000, "limit": 500, "offset": 0 }

Pages are ordered by app name (then id), so offsets are deterministic across requests. Add meta=grid to bundle the per-app maps the apps grid renders (profile badges, user verdicts, pending-change breakdown, device links), scoped to the returned page. For installs tracking more than ~1,000 apps, prefer the paginated form — it’s what the app’s own grid uses.

Calling the API from another app

Three patterns are common:

curl -s "http://localhost:3000/api/apps?limit=500" | jq '.apps[] | {id, name, changeCount}'

curl -X POST http://localhost:3000/api/scrape \
  -H "Content-Type: application/json" \
  -H "Origin: http://localhost:3000" \
  --data '{"urls":["https://apps.apple.com/us/app/spotify-music-and-podcasts/id324684580"]}'

const res = await fetch("http://localhost:3000/api/apps?limit=500");
const { apps, total } = await res.json();

await fetch("http://localhost:3000/api/scrape", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Origin": "http://localhost:3000",
  },
  body: JSON.stringify({
    urls: ["https://apps.apple.com/us/app/spotify-music-and-podcasts/id324684580"],
  }),
});

import httpx

async with httpx.AsyncClient(base_url="http://localhost:3000") as c:
    apps = (await c.get("/api/apps", params={"limit": 500})).json()["apps"]

    await c.post(
        "/api/scrape",
        headers={"Origin": "http://localhost:3000"},
        json={"urls": ["https://apps.apple.com/us/app/spotify-music-and-podcasts/id324684580"]},
    )

Full route map

The OpenAPI spec covers the public-contract surface — the routes integrators most commonly hit. The complete route map (including dev-only and internal routes) is in the Architecture overview and the underlying app/api/*/route.ts files in the source tree:

Group	Where in the source
Apps, scrape, search, changelog	`app/api/{apps,search,scrape,changelog}/route.ts`
Backup, snapshots, audit bundle	`app/api/backup/**/route.ts`, `app/api/{import,export}/audit-bundle/route.ts`
AI, policy versions, debug log	`app/api/{ai,policy}/**/route.ts`
Focus, flags, profile, prefs	`app/api/{focus,feature-flags,privacy-profile,accessibility-profile,preferences}/**/route.ts`
Notes, verdicts, notifications	`app/api/{annotations,verdicts,notifications}/**/route.ts`
Bulk task status	`app/api/tasks/active/route.ts`, `app/api/{sync,wayback,policy}/**/route.ts`
Stats, charts	`app/api/stats/**/route.ts`
Devices, device menu, device actions	`app/api/{devices,device-scope,device-sync,device-actions}/**/route.ts`
Health, deployment, admin	`app/api/{health,ready,deployment,admin,reset,dev}/**/route.ts`
Admin-token sessions	`app/api/auth/admin-token/{login,logout,status}/route.ts`

​Base URL

​Authentication

​Conventions

​Rate limiting

​Backup bundle format

​Pagination

​Calling the API from another app

​Full route map