Skip to content

REST API

Philter Workspace exposes a JSON-over-HTTP API under /api/v1. The API surface is split into two categories that authenticate differently. A few paths sit outside both: the unauthenticated health and metrics endpoints.

Every POST, PUT, PATCH, and DELETE under /api/v1 requires Content-Type: application/json, including requests with an empty body, and returns 415 Unsupported Media Type without it.

Authentication

Philter API keys

Programmatic callers authenticate with a Philter API key that holds Philter's users:read scope, sent on every request:

Authorization: Bearer <philter-api-key>

Philter Workspace checks the key with Philter and runs the request as the Philter user that owns it, with that person's Philter Workspace role and groups. Philter Workspace has no API keys of its own. See API keys for how the key is checked and cached.

Status Meaning
401 Unauthorized No key, or Philter does not accept the key, or its user is deactivated.
403 Forbidden The key does not hold users:read, or the user's role does not allow the call.
503 Service Unavailable Philter could not check the key: it was unreachable, answered with a server error, or rate limited the check.

Programmatic (Bearer-only)

These endpoints are intended for scripts, integrations, and downstream consumers. They accept only a Philter API key: session cookies are explicitly stripped by the security filter chain so a logged-in admin's browser session cannot be CSRF'd into reaching them. The Bearer-only set is small and stable:

Method Path
POST /api/v1/ingest
POST /api/v1/search
POST /api/v1/documents/{id}/finalize
GET /api/v1/documents/{id}/audit

Session-allowed (browser-UI shared)

The remaining /api/v1/** endpoints are used by Philter Workspace's own web UI and accept either a Philter API key or the browser's session cookie. Cross-origin abuse is blocked by the browser's same-origin policy plus the absence of a permissive CORS configuration. Endpoints in this category are called out below per-section.

Health and metrics

Philter Workspace serves three unauthenticated paths for monitoring: /api/health, /actuator/health, and /actuator/prometheus. All three accept GET only. They are reachable before any credential exists so a container runtime, load balancer, uptime monitor, or Prometheus scraper can call them.

GET /api/health

The health endpoint every Philterd product exposes. It sits outside /api/v1 because it is not a versioned business endpoint.

{
  "status": "UP",
  "applicationVersion": "1.0.0-SNAPSHOT"
}

status is Philter Workspace's aggregate health, so a broken dependency is visible here rather than being masked by the fact that the process still answers. UP returns 200; any other status returns 503 with that status in the body, so a monitor that reads only the status code still sees the fault.

These contribute to the aggregate:

Component Reports DOWN when
MongoDB the database does not answer a ping
Full text search (fullTextSearch) full text search is enabled and its backend cannot be used: the embedded index cannot be opened, or the OpenSearch cluster does not answer
Disk space free space on the data partition is nearly exhausted
Valkey the session store does not answer

One caveat on timing: when MongoDB itself is unreachable, the health endpoints answer 503 only after the MongoDB driver's server-selection timeout (30 seconds by default), because that is how long the driver waits before it declares the server unusable. Monitors with a shorter timeout see the request time out, which they should also treat as unhealthy. Add ?serverSelectionTimeoutMS=5000 to spring.mongodb.uri if you want a faster answer, keeping in mind it applies to every Philter Workspace query, not just health.

A deployment that runs with full text search turned off is not marked down for its search backend. One that leaves it on with a backend it cannot use is: search and indexing are degraded, so fix the backend, or turn the feature off under Admin → General. See Full text search.

applicationVersion is the build version recorded in the jar at package time. It reads unknown when Philter Workspace runs from classes built outside Maven (an IDE, for example), where no build metadata file exists.

The response names no component behind the status and carries no deployment or document state, but it does disclose the running build version to anyone who can reach the port. Keep Philter Workspace's port on an internal network, or block the path at your reverse proxy if you do not want that version visible.

GET /actuator/health

Spring Boot Actuator's own view of the same aggregate, for tooling that already speaks Actuator:

{
  "status": "UP"
}

200 when the status is UP, 503 when it is DOWN. It carries no applicationVersion, so monitoring that wants the running version should call /api/health instead. Per-component detail is switched off, so an unauthenticated caller never learns which dependency is down or what address it sits at; read the application log for that.

GET /actuator/prometheus

Metrics in Prometheus text exposition format, for a scrape config:

# HELP jvm_memory_used_bytes The amount of used memory
# TYPE jvm_memory_used_bytes gauge
jvm_memory_used_bytes{area="heap",id="G1 Eden Space"} 1.34217728E8
http_server_requests_seconds_count{method="GET",status="200",uri="/api/health"} 42.0

The metrics are JVM gauges and HTTP request counts and timings. Request URIs appear as route templates (/documents/{id}), never as the concrete paths a reviewer visited, and no document text, entity value, or user identity is exported.

Scraping it does disclose how Philter Workspace is being used: request volumes, error rates, and which routes are exercised. Treat the endpoint as internal, and block /actuator at your reverse proxy if your scraper does not need it.

Health and prometheus are the only Actuator endpoints Philter Workspace exposes. Everything else Actuator can serve, including env, configprops, beans, loggers, and heapdump, returns 404, as do the /actuator links page and the per-component paths under /actuator/health/.

Document ingestion

POST /api/v1/ingest

Bearer-only. Submit a plain-text document. Ingestion is asynchronous: the document is persisted in PENDING and placed on the redaction queue. A background worker runs Philter in arrival order; once redaction completes, the document moves to REVIEW_REQUIRED (PII detected with low-confidence spans), AUDIT_REQUIRED (eligible for auto-approval but sampled for review per the batch's audit sampling rate), or AUTO_APPROVED.

Request body:

{
  "batchId":  "string",
  "name":     "string",
  "text":     "string",
  "priority": 2,
  "caseMetadata": {
    "caseNumber": "1:26-cv-01234",
    "caseType":   "civil",
    "filer":      "Acme Dental LLC",
    "feeStatus":  "paid",
    "ifp":        false
  }
}

caseMetadata is optional; see Case metadata for its fields. Invalid metadata is refused with 400 and a body of {"error": "...", "problems": [...]}, before anything is stored.

priority is optional. It accepts an integer in 1..3 (1 Low, 2 Normal, 3 High); omitting it or sending null defaults to Normal. The value is stored on the document and surfaced as a chevron icon on the Document Queue. It does not affect ingest ordering — redaction still runs oldest-first.

Status Meaning
202 Accepted; body {"taskId": "..."}. Redaction runs asynchronously.
400 batchId does not exist (or required fields missing/invalid, including priority outside 1..3).
403 Caller does not have access to that batch.
409 Batch is closed; body includes "closed": true.

The returned taskId is the document's id. Poll GET /api/v1/documents/{id}/spans or GET /api/v1/queue to track its progress out of PENDING.

A SHA-512 hash of the submitted text (UTF-8 bytes) is recorded on the document at ingest time — see Security · Document content integrity.

GET /api/v1/documents/{id}/case-metadata

Session-allowed. A document's case metadata, and the policy Philter last reported redacting it with:

{
  "caseMetadata": {"caseNumber": "1:26-cv-01234", "caseType": "civil", "filer": "Acme Dental LLC",
                   "feeStatus": "paid", "ifp": false},
  "appliedPolicyName": "civil-filings",
  "appliedPolicyVersion": 3
}

caseMetadata is null when the document has none. 404 if the document is missing or the caller cannot see it.

PUT /api/v1/documents/{id}/case-metadata

Session-allowed. Replaces the document's case metadata with the body, an object with the case metadata fields; {} clears it. Requires Content-Type: application/json. The change is audited as DOCUMENT_CASE_METADATA_UPDATE and does not redact the document again.

Response: {"changed": true, "caseMetadata": {...}}. 400 with error and problems for invalid values, 409 if the document is finalized, is still waiting to be redacted (PENDING or PROCESSING), or changed while the request was saved, and 404 if the document is missing or the caller cannot see it.

Triage

GET /api/v1/queue

Session-allowed. List documents the caller can see, paged by sort field.

Query param Default Meaning
page 0 Zero-indexed page (negative values are clamped to 0)
size 10 Page size, clamped to the range [1, 100]
batchId — Filter to one batch
status — Filter to one status
filename — Substring match on filename, case-insensitive
myGroupsOnly false Admin opt-in: restrict admins to their own groups
sort riskScore One of riskScore, status, batchId, filename, priority
dir desc asc or desc

size is hard-capped at 100 — values above that are silently lowered, and values below 1 are raised to 1. Page through larger result sets with successive page values rather than a larger size.

Non-admins are always restricted to their groups; the myGroupsOnly parameter only affects admin callers.

Response is a Spring Page<Map> shape:

{
  "content": [
    {
      "id": "string",
      "filename": "string",
      "status": "PENDING|REVIEW_REQUIRED|AUDIT_REQUIRED|AUTO_APPROVED|APPROVED|REJECTED|FAILED",
      "riskScore": 0.0,
      "batchId": "string",
      "batchName": "string",
      "lowRisk": false,
      "documentThreshold": 0.25,
      "priority": 2
    }
  ],
  "totalElements": 0,
  "totalPages": 0,
  "number": 0,
  "size": 10
}

lowRisk is true when the document's risk score is at or below its batch's documentThreshold. It is always false for documents with no risk score: those not yet redacted (PENDING, PROCESSING) and those never redacted (FAILED, SKIPPED). It is a risk indicator only and approves nothing; status is the document's stored status. It replaced the autoApproved flag, which was true for documents that were not approved.

GET /api/v1/batches

Session-allowed. List batches the caller can target. Honors the same myGroupsOnly query param. Returns a JSON array of {id, name, label}. Batch names are unique only within a group, so label is the name followed by the batch's group in parentheses when another batch in the response has the same name, and the name alone otherwise.

Documents

GET /api/v1/documents/{id}/spans

Session-allowed. Return every Span row in the document. Useful for building a custom review client or for reconciling the redactor's output with downstream systems.

404 if the document doesn't exist or the caller lacks group access.

POST /api/v1/documents/{documentId}/spans

Session-allowed. Manually create a span at an explicit character range. Used by the review UI when a reviewer highlights uncovered PII; the API is also available to clients.

{ "type": "ssn", "start": 42, "end": 53 }

type is validated against the PII types list. The new span is persisted with confidence: 1.0, status: APPROVED, and manuallyCreated: true.

Status Meaning
200 Returns the saved Span JSON.
400 Missing/invalid type, start, or end; range exceeds the text.
404 Document not found or caller lacks access.
409 Document is in a terminal state and cannot be edited.

POST /api/v1/documents/{id}/finalize

Bearer-only. Finalize an approved document, exactly as the review page's Finalize button does. The response is the redacted text: the document's text with each approved span replaced by its type in double angle brackets, such as <<SSN>>. On success the document is FINALIZED, the redacted text is kept on the document so a later download still works even if a finalization policy clears the source text, a certificate of redaction is issued, DOCUMENT_FINALIZE is recorded in the audit log with via set to api, and the batch's finalization policy is applied. When the document's batch has a destination, the redacted text is then delivered to it in the background (see Delivering finalized documents).

The request has no body but requires Content-Type: application/json.

{ "finalizedText": "string" }
Status Meaning
200 Returns { "finalizedText": "..." } and the document is now FINALIZED.
404 Document not found, or the caller lacks group access.
415 The Content-Type: application/json header is missing.
409 Document is not in APPROVED, another person holds its review lock, or its source text is unavailable (e.g. cleared by a finalization policy on a prior pass) and cannot be re-finalized.

GET /api/v1/documents/{id}/audit

Bearer-only. Return a redaction audit trail — every span on the document with its text, type, confidence, and current status. Useful for after-the-fact review or compliance reporting.

[
  { "text": "...", "type": "ssn", "confidence": 0.92, "status": "APPROVED" }
]

404 if the document doesn't exist or the caller lacks group access.

GET /api/v1/documents/{id}/history

Session-allowed. Return the full audit history for a document — document-level events and all span events — as a JSON array sorted newest first. Powers the Audit Log popup on the Document Queue.

Restricted to ROLE_ADMIN or ROLE_AUDITOR. Returns 403 for any other caller because the history includes raw PII span text.

Each element:

{
  "timestamp": "2026-05-01T12:00:00Z",
  "actor":     "<mongodb-user-id>",
  "action":    "SPAN_UPDATE",
  "resourceType": "Span",
  "resourceId":   "...",
  "details":   {}
}

The actor field defaults to the MongoDB user ID. Pass ?resolveActors=true to receive the user's email address instead — this parameter requires ROLE_ADMIN or ROLE_AUDITOR and returns 403 otherwise.

GET /api/v1/documents/{id}/history.csv

Session-allowed. Download the document's full audit history (document-level events plus all events on its spans) as a CSV, sorted newest first. Powers the Download button on the Document Queue's Audit Log popup. See Audit log for the column list.

Restricted to ROLE_ADMIN or ROLE_AUDITOR. Returns 403 for any other caller. The CSV deliberately omits PII text — span entries include spanCharacterStart, spanCharacterEnd, and spanPage instead. The actor column contains the actor's email address (the CSV is admin/auditor-only, so email exposure is appropriate).

GET /api/v1/documents/{id}/ledger

Session-allowed. The document's chains in Philter's ledger, read with Philter Workspace's API key: chains (each with philterDocumentId, state, verified, hashChainValid, signaturesValid, signedEntries, unsignedEntries, validationError, entries, entriesTruncated, and summary) and entries (without original values, replacements, or filenames). Restricted to ROLE_ADMIN or ROLE_AUDITOR; 403 otherwise. Audited as PHILTER_LEDGER_READ. See Audit trail with Philter's ledger.

GET /api/v1/documents/{id}/audit-trail

Session-allowed. The document's audit trail: its Philter Workspace events and its ledger entries, oldest first, with how each chain verified. format is csv (the default) or json. Restricted to ROLE_ADMIN or ROLE_AUDITOR; 403 otherwise. Audited as AUDIT_TRAIL_EXPORT.

GET /api/v1/documents/{id}/certificate

Session-allowed. Return the redaction certificate for a finalized document — a JSON object summarising the document hash, finalize timestamp, and span counts. Powers the Certificate popup on the Document Queue. The caller must have group access to the document; 404 is returned if the document doesn't exist or the caller lacks access.

GET /api/v1/documents/{id}/comments

Session-allowed. Return reviewer comments left on the document, oldest first.

[
  { "id": "...", "userEmail": "user@example.com",
    "timestamp": "2026-05-04T13:00:00Z", "text": "..." }
]

POST /api/v1/documents/{id}/comments

Session-allowed. Add a comment to the document. The request body is a JSON object with a single text string (max 4 000 characters; surrounding whitespace is trimmed). Returns the saved comment in the same shape the GET above produces.

{ "text": "..." }

Spans

PATCH /api/v1/spans/{id}

Session-allowed. Update a span's status, type, or boundaries. Any span change (this one, creating, deleting, resetting, or Redact All Like This) is refused with 409 while another person holds the document's review lock, and clears the approvals the document has so far, audited as DOCUMENT_APPROVALS_CLEARED.

{
  "status":        "APPROVED|REJECTED|PENDING|NEEDS_SECOND_OPINION",
  "type":          "ssn",
  "reason":        "...",
  "exemptionCode": "...",
  "adjudicate":    true,
  "start":         12,
  "end":           24
}
Field Required Notes
status optional One of the allowed statuses. Sending none of status, type, or start and end returns 400.
type optional New PII type; validated against the PII types list.
reason optional Required when overturning another reviewer's prior APPROVED decision (changing status away from APPROVED while the prior approval was recorded by a different actor). Returns 409 OVERTURN_REASON_REQUIRED otherwise. Recorded in the audit trail.
exemptionCode optional Free-form string applied only when the new status is APPROVED. Cleared automatically when the span moves out of APPROVED.
start, end optional Move the span to characters [start, end) of the document's original text (adjusting boundaries). Sent together, and accept the span: status must be absent or APPROVED. 400 for a range outside the text or covering only whitespace; 409 for a range overlapping another span, or for a span in a PDF. The span records where it was detected (originalCharacterStart, originalCharacterEnd), adjusted, adjustedBy, and adjustedAt; the move is audited as SPAN_ADJUST.
adjudicate optional true makes the change an approver's final decision on the span (adjudication). Requires an approver of the document's group or an administrator, and a status of APPROVED or REJECTED. Sets adjudicatedBy and adjudicatedAt, and is audited as SPAN_ADJUDICATE.

Returns the updated Span object.

409 if the parent document is in a terminal state, if another person holds its review lock, or if an overturn is attempted without a reason. 400 if adjudicate is sent without a status of APPROVED or REJECTED. 403 if adjudicate is sent by someone who is not an approver of the document's group, or if anyone other than such an approver changes a span that has adjudicatedBy set; an approver's change to such a span is a new adjudication. The same 403 applies to reset, DELETE, and redact-like on an adjudicated span, and redact-like leaves other adjudicated spans unchanged and counts them in adjudicatedSkipped.

DELETE /api/v1/spans/{id}

Session-allowed. Hard-delete a span. Only manually-created spans can be deleted — for spans the redactor produced, flip status to REJECTED instead.

{ "id": "...", "deleted": true }

400 if the span was redactor-created. 409 if the parent document is terminal.

POST /api/v1/spans/{id}/redact-like

Session-allowed. Find every other occurrence of the source span's text in the parent document and approve each match with the source span's PII type. New Span rows are created where matches don't already have one; existing spans at exact ranges are flipped to APPROVED and aligned to the source type. Overlapping non-exact matches are skipped to avoid duplicate spans.

Requires Content-Type: application/json (the request body itself is ignored; the JSON content type is enforced as a CSRF defence so cross-site form posts can't trigger this endpoint).

Response:

{ "created": 0, "approved": 0, "adjudicatedSkipped": 0, "limitReached": false, "limit": 500 }

created is the number of new spans inserted. approved is the number of existing spans flipped to approved. adjudicatedSkipped is the number of matching spans an approver adjudicated, which are left unchanged.

One call creates or approves at most limit (500) spans. limitReached is true when it stopped with occurrences left, some of which may be ones it would skip; calling it again continues, since a match that is already a person's approval with the source's type is skipped and not counted.

400 if the source span has empty text, or with {"message": "..."} if its text is shorter than 3 characters after trimming. 404 if the span or its document is missing.

POST /api/v1/spans/{id}/rule

Session-allowed. Make a detection rule from the span: NEVER ("Don't flag this again") from a refused detected span, or ALWAYS ("Always flag this") from a span added by hand. Allowed whatever the document's status. Requires Content-Type: application/json.

Request:

{ "kind": "NEVER" }

Response:

{ "status": "ACTIVE", "message": "Rule confirmed: Philter will never flag this value in documents redacted from now on." }

status is ACTIVE when the caller may confirm rules and the rule was written to Philter, or PROPOSED when it waits for confirmation. 409 with a message when no rule was made: the span is not eligible, the value is too long or ends in :fuzzy, the other kind of rule exists for the value, or Philter refused the change. 404 if the span or its document is missing.

POST /api/v1/spans/{id}/reset

Session-allowed. Revert a span back to its previous status. The intended use is "I clicked Approve / Reject by mistake" — the endpoint moves a span out of its terminal state and back into review. The optional JSON body {"originalStatus": "PENDING|REVIEW_REQUIRED"} selects the target status; an empty body falls back to the span's prior status as recorded in the audit log.

Requires Content-Type: application/json. Returns the updated Span JSON.

404 if the span doesn't exist or the caller lacks group access. 409 if the parent document is in a terminal state.

GET /api/v1/spans/{id}/history

Session-allowed. Return the audit history for a single span as a JSON array sorted newest first. Accessible to any authenticated user with group access to the span's parent document.

[
  {
    "timestamp":    "2026-05-01T12:00:00Z",
    "actor":        "<mongodb-user-id>",
    "action":       "SPAN_UPDATE",
    "resourceType": "Span",
    "resourceId":   "...",
    "details":      {}
  }
]

The actor field defaults to the MongoDB user ID of the actor to avoid leaking email addresses to other reviewers. Pass ?resolveActors=true to receive email addresses instead — this parameter requires ROLE_ADMIN or ROLE_AUDITOR and returns 403 otherwise.

404 if the span doesn't exist or the caller lacks group access.

POST /api/v1/search

Bearer-only. Full-text search across the full-text index of ingested documents. Each document is indexed at ingest time with its filename, batch, status, and full original text.

The query is sent in a JSON body, with Content-Type: application/json, so it stays out of URLs, where proxy and load-balancer access logs would record it.

{ "q": "string", "offset": 0, "size": 10 }
Field Default Meaning
q None Match query (required, runs against the text). A blank query is answered with 400.
offset 0 First hit to return
size 10 Max hits per page (capped at 100)

GET /api/v1/search?q=… was removed: it is answered with 405, Allow: POST, and an error message saying to use POST, and the query is not run.

Response:

{
  "query": "...",
  "offset": 0,
  "size": 10,
  "total": 42,
  "hits": [
    {
      "id": "...",
      "batchId": "...",
      "filename": "...",
      "status": "AUTO_APPROVED",
      "highlights": ["… <em>match</em> snippet …"]
    }
  ]
}

Results are pre-filtered to batches the caller can access. Non-admin callers only see hits from their own group's batches; total reflects that filtered count, not the full index size. Inaccessible hits are silently excluded — they are never returned as placeholder rows.

If the search backend cannot be used, a query returns an empty result set rather than failing the request — search is best-effort.

LLM-as-a-Judge

These endpoints proxy a configured Ollama instance to provide an LLM second opinion on the redactor's output. Configuration lives under Admin → LLM-as-a-Judge (see LLM-as-a-Judge, which also covers HTTPS for an instance on another machine).

PII leaves Philter Workspace on every call

Both explain and second-opinion send the full unredacted document text and all PII span values to Ollama. Each call is recorded in the audit log as DOCUMENT_PII_SENT_TO_LLM before the HTTP request is sent, so the entry exists even if Ollama is unreachable. Ollama must be deployed with request-body logging disabled (OLLAMA_DEBUG=0) to prevent PII from appearing in Ollama's logs.

GET /api/v1/ollama/{instanceId}/models

Session-allowed. List the models installed on a configured Ollama instance.

{ "instanceId": "...", "instanceName": "...", "models": ["llama3", "mistral"] }

404 if the instance id is unknown. 502 if Ollama is unreachable.

POST /api/v1/documents/{documentId}/explain

Session-allowed. Ask the LLM to explain the PII risk in a document.

{ "instanceId": "...", "model": "llama3" }

Response:

{ "instanceName": "...", "model": "llama3", "response": "..." }

POST /api/v1/spans/{spanId}/second-opinion

Session-allowed. Ask the configured Second Opinion default Ollama instance/model whether the named span is genuinely PII or a likely false positive. The instance and model are chosen from the LLM-as-a-Judge defaults — the request body is empty but the Content-Type: application/json header is required (CSRF defence).

{ "instanceName": "...", "model": "...",
  "sourceText": "...", "sourceType": "ssn",
  "response": "..." }

400 if no Second Opinion default is configured.

Policies

These endpoints list the policies batches can use, those of the Philter user that owns PHILTER_WORKSPACE_PHILTER_API_KEY, for the batch dialogs. The framework gates them to ROLE_ADMIN or ROLE_AUDITOR for reads — non-admin callers get 403.

GET /api/v1/policies

Session-allowed. List the policies in Philter Workspace's Philter that PHILTER_WORKSPACE_PHILTER_API_KEY can use.

Response:

{ "policies": ["claims", "..."] }

502 when Philter is unreachable.

GET /api/v1/policies/content

Session-allowed. Fetch the JSON content of one named policy from Philter.

Query param Required Meaning
name yes Policy name; restricted to letters, digits, hyphens, and underscores (1–64 chars).

Response:

{ "name": "claims", "content": "{ ...JSON policy... }" }

content is Philter's policy JSON as a string, returned verbatim.

400 for malformed names (the regex check rejects path-traversal attempts). 404 when Philter has no such policy. 502 when Philter is unreachable.

Browser-only internal endpoints

The following paths exist under /api/v1/** but are intended only for the in-page JavaScript that drives the review UI. They are session-callable, do nothing harmful in isolation, and are documented here purely so that traffic from philter-workspace's own UI doesn't look surprising in HTTP logs:

Path Purpose
POST /api/v1/review/{documentId}/pulse Sliding-expiry heartbeat sent every ~30 s by the review page so the document's pessimistic edit lock doesn't expire while the reviewer is still on the page. Operates on the caller's own lock only.
POST /api/v1/review/{documentId}/release navigator.sendBeacon'd when the reviewer leaves the page. Releases the caller's own lock.
GET /api/v1/review/{documentId}/similar Backs the "Find similar documents" button on the review page. Returns up to 10 hits filtered to the caller's accessible batches.

There's no programmatic-API reason to call these — use PATCH /spans/{id} and POST /search instead.

Errors

Error responses have a JSON body with at least an error field describing the issue. Status codes follow the table per endpoint above.