Skip to content

Developers

Philter's REST API is the integration surface for applications, data pipelines, and batch processing, and the only way to administer Philter, which has no built-in user interface. Policies, redaction workflows, users, and keys can all be managed as code.

The Developer Quick Start walks through creating a policy, redacting text, and redacting a PDF, with curl and Python examples.

API Integration

The API covers:

  • Redaction: redact text synchronously and PDFs asynchronously, and inspect what was detected with POST /api/explain.
  • Policy management: create, retrieve, and delete policies, with every save retained as an immutable version that can be compared and rolled back.
  • Contexts: manage contexts and their token-to-replacement entries, including export and import.
  • Lists: manage custom lists and always/never redact lists.
  • Evidence: query and export the redaction ledger, and set or release legal holds.
  • Administration: manage users, API keys, settings, and the audit log.
  • Re-identification: reverse a CRYPTO_REPLACE or FPE_ENCRYPT_REPLACE value with re-identification, which requires a reason that is recorded in the audit log.

See the API Reference for every endpoint, and Client SDKs for the Java SDK and for generating a client in other languages from the OpenAPI specification.

API Authentication

All API requests authenticate with an API key sent as a bearer token. The first key is seeded at startup from PHILTER_BOOTSTRAP_API_KEY; manage further keys with the API Keys API. See API Keys and Authentication.

Authorization: Bearer <YOUR_API_KEY>

GET /api/health, GET /api/signing-key, and GET /api/signing-key/{keyId} are the exceptions: they are served without authentication so load balancers can probe Philter and so verifiers can fetch the public signing keys. When PASSWORD_SIGN_IN_ENABLED=true, POST /api/sign-in and POST /api/sign-in/mfa are also served without an API key (they take a username and password); otherwise they return 404.

Interactive API Reference

Every running instance serves Swagger UI at /swagger-ui/index.html (for example, https://localhost:8080/swagger-ui/index.html), where you can explore each endpoint and issue test calls from the browser. The OpenAPI specification itself is at /v3/api-docs. Neither requires authentication.

Developer Guidelines

  • Restrict access. Put Philter behind firewall rules, security groups, or an ingress that limits API access to trusted clients. Philter itself does not filter by client address; that belongs at the network layer.
  • Handle error responses. Beyond 401 Unauthorized for a missing or invalid key, expect 403 Forbidden (the operation requires an administrator, the feature is disabled, or the API key lacks the required scope), 404 Not Found when you name another user with owner= and may not reach them (the API answers the same way whether or not that user exists, so the status cannot be used to discover accounts), 413 Payload Too Large and 415 Unsupported Media Type on redaction requests, 409 Conflict and 410 Gone when downloading an asynchronous document that is not finished or that failed, and 423 Locked when a legal hold blocks a deletion.
  • Use a separate context for development. A distinct context keeps test replacements out of your production data.
  • Validate against your own data. Detection is probabilistic, so measure a policy against representative documents before relying on it, and review the results.

Need Support?

See Support, or contact support@philterd.ai.