API design refresh: /v1/detect+sanitize -> /api/find+replace (0.5.0)

[jstjoe]

Summary

Two breaking renames on top of #18/#19, in successive commits:

1. Endpoint terminology — /v1/detect -> /v1/find ("Find sensitive data") and /v1/sanitize -> /v1/replace ("Replace sensitive data"). Internal schemas, response field sanitized_text -> replaced_text, tags, internal helpers all follow.
2. Drop URL versioning — paths move from /v1/* to /api/*. Pre-1.0; nobody outside this repo consumes the API yet. When the contract stabilizes the plan is header-based date-string versioning in the style of Stripe (API-Version: 2026-05-13).

info.version bumped 0.4.0 -> 0.5.0 across the two commits (one per breaking change).

New endpoint surface

Method	Path	Purpose
POST	/api/find	Find sensitive data. Returns spans, no rewriting.
POST	/api/replace	Find + replace each span under chosen mode.
GET	/api/detectors	List registered detector backends.
GET	/api/health	Liveness probe.

Old /v1/* paths return 404. No aliases.

Notable touches

• api/src/opf_api/main.py — app.include_router(prefix=\"/api\"), FastAPI tags Find / Replace / Meta, versioning section in info.description calls out the planned API-Version header.
• api/src/opf_api/routes.py — find + replace handlers, internal _run_find + _FindInput.
• api/src/opf_api/schemas.py — FindRequest / FindResponse / ReplaceRequest / ReplaceResponse / ReplacedSpan / ReplaceMode; field renamed sanitized_text -> replaced_text.
• api/tests/test_routes.py — every test renamed + repointed at /api/*.
• docs/guides/replace-modes.md — renamed from sanitize-modes.md; content updated.
• docs/token-vault-setup.md — points at /api/replace (label_token mode).
• docs/api/openapi.json — regenerated; version: 0.5.0, paths /api/find, /api/replace, /api/detectors, /api/health.

Notebook (notebooks/pii_detector_comparison.ipynb) imports source and never hits HTTP — unaffected.

Versioning narrative (now in spec + overview guide)

The API is pre-1.0. info.version is the only version surface today. Each breaking change to request or response shape lands as a minor bump pre-1.0. URL paths stay unversioned (/api/...); future header API-Version: 2026-05-13 will pin clients to a release date once the contract is stable.

Test plan

• uv run --package opf-api opf-api-export-openapi --out /tmp/fresh regenerates; diff against committed spec is empty
• uvicorn opf_api.main:app boots; /api/health, /api/detectors, /scalar, /docs, /redoc, /openapi.json -> 200; /v1/* -> 404
• pytest api/tests/test_routes.py — 21/21 passing (all rewritten for /api/*)
• CI OpenAPI spec freshness job passes on latest push
• After merge, Pages site at https://jstjoe.github.io/local-privacy/ reflects new endpoints

🤖 Generated with Claude Code

[jstjoe]

@claude quick review please?

[claude]

Claude finished @jstjoe's task in 2m 17s —— View job

---

Code Review

• Read CLAUDE.md and gather context
• Diff the PR changes
• Review core API files (routes.py, schemas.py, main.py)
• Review tests
• Review docs/openapi spec
• Post findings

---

Overall: LGTM. The rename is clean and thorough. No missed references on the API surface, tests all updated, spec regenerated, docs in sync. A few minor notes:

Stale comment in api/Dockerfile:53

# Bake OPF checkpoint into the image so first /v1/redact doesn't pay the

References the old /v1/redact path. Should be updated to /api/replace (or just drop the path reference entirely since the comment's substance is about eager-loading the checkpoint, not the route name). Fix this →

warning field is always None

Both find() (routes.py:198) and replace() (routes.py:312) hardcode warning=None. The field exists in FindResponse and ReplaceResponse with a description but is never populated. This predates this PR — just noting it as a cleanup opportunity whenever the field gets actual use or gets removed.

Overlapping span replacement on skipped spans

In replace(), detected_spans includes all spans (including ones whose text was skipped due to overlap in replaced_text). Each skipped span still has a populated replacement field even though that replacement was never spliced in. This is documented in the route description ("they still appear in detected_spans") and is pre-existing behaviour — but a client that trusts replacement as ground truth for what happened could be surprised. Worth documenting more explicitly in the field description eventually, or adding a replaced: bool flag to ReplacedSpan.

Everything else looks good

• All /v1/ → /api/ and sanitize/detect → replace/find renames are complete and consistent across source, tests, spec, and docs.
• The only other /v1/ hits in the repo are Skyflow's own management API path in vault_tokens.py:129 and token-vault-setup.md — both correct and intentional.
• ReplaceRequest correctly inherits from FindRequest; _FindInput Protocol is used for both handlers via _run_find.
• Version 0.5.0 (jumping from 0.3.0 in the diff) is coherent: two successive minor bumps land in one PR, as the commit history shows.
• docs/guides/sanitize-modes.md is gone; replace-modes.md exists with updated content; README and cross-references all point at the new name.

[jstjoe]

Thanks @claude, review again?

[claude]

Claude finished @jstjoe's task in 1m 57s —— View job

---

Code Review (re-review)

• Check new commits since last review
• Review new changes in detail
• Post findings

---

Both items flagged in the last review were shipped in follow-on commits — clean responses.

b18c276 — Dockerfile comment ✓
Reworded to "first request" instead of patching the stale path. Better than just s/redact/replace — won't strand again on the next rename.

e77cc8c — replaced: bool on ReplacedSpan ✓
The implementation is correct and the cursor logic is a faithful mirror of splice_pieces:

• routes.py checks s["start"] >= cursor and advances only on inclusion.
• splice_pieces checks s["start"] < cursor to skip (semantically identical).

Both agree on the start == cursor edge case (keep the span). The flag is in the required list in both JSON and YAML specs, version bumped to 0.6.0, and the new test test_replace_overlapping_spans_flag_and_splice covers the two-span overlap scenario end-to-end.

One minor note on label_number numbering: when a span is overlapped and dropped, the renderer still ran for it (all spans in rendered_pairs get rendered before the flag walk). So a dropped span consumes a number — a later "Anderson" in the same request would get [PERSON_3] even though [PERSON_2] never appeared in replaced_text. Clients can infer this from replaced=false, but it may surprise people. Not a bug, just worth noting in a follow-up comment on the label_number row in the mode table if it ever becomes a support question.

The warning=None from last review is still hardcoded — but that was flagged as pre-existing, and is unchanged here.

Overall: LGTM. The rename is complete, the overlap transparency is solid, and the replaced flag gives clients a clean reconstruction path. Ready to merge.