PrivacyFlow Logo

API Reference

Every endpoint on the PrivacyFlow public API — health, verify, poll, send — plus rate limiting and credential scoping.

The PrivacyFlow public API is one HTTPS host with four endpoints. Base URL: https://privacyflow.app. All request and response bodies are JSON. Version prefix is /api/v1 (the v1 URL segment is stable; package version may move independently).

EndpointMethodAuthReturns
/api/v1/healthGETnone{status, version}
/api/v1/auth/verifyGETrequired{valid, appIds[]}
/api/v1/messages/pollGETrequired{messages[], count, queue}
/api/v1/messages/sendPOSTrequired{successfulMessages[], failedMessages[], totalAccepted, totalFailed}

Authentication

Three HTTP header methods, gated by credential type. Read Authentication for the full matrix, or Credentials for how credential types map to dashboard config.

Conventions

  • Content type. All POST bodies use application/json. GET requests have no body.
  • Timestamps. All timestamps are epoch milliseconds.
  • Message IDs. 32-character lowercase hex generated server-side via crypto.getRandomValues.
  • HTTPS only. Strict-Transport-Security is set on every response, including errors.
  • CORS. None. The API is server-to-server only.
  • Timeouts. Credential lookups time out at 30 seconds against the key store. HTTP read uses fetch defaults.

Common error shape

Every error returns JSON of the form:

{ "error": "human-readable message" }

See Errors & Rate Limits for the full status-code table.

Last updated:
Edit on GitHub