openapi.json

{
  "components": {
    "schemas": {
      "CanonicalLabel": {
        "description": "Canonical PII category. Every detector's raw output maps into this taxonomy.",
        "enum": [
          "PERSON",
          "EMAIL",
          "PHONE",
          "ADDRESS",
          "URL",
          "DATE",
          "ACCOUNT",
          "SECRET",
          "USERNAME",
          "DEMOGRAPHIC",
          "ORGANIZATION",
          "OCCUPATION",
          "MONEY",
          "VEHICLE",
          "PHYSICAL"
        ],
        "title": "CanonicalLabel",
        "type": "string"
      },
      "DetectorInfo": {
        "description": "One row in the detector registry.",
        "properties": {
          "categories": {
            "description": "Canonical categories this detector can produce.",
            "examples": [
              [
                "PERSON",
                "EMAIL",
                "PHONE"
              ]
            ],
            "items": {
              "$ref": "#/components/schemas/CanonicalLabel"
            },
            "title": "Categories",
            "type": "array"
          },
          "loaded": {
            "description": "`true` once the detector has been initialised. Flips on first use, or at startup if listed in `EAGER_LOAD`.",
            "examples": [
              true
            ],
            "title": "Loaded",
            "type": "boolean"
          },
          "name": {
            "description": "Registry key.",
            "examples": [
              "opf"
            ],
            "title": "Name",
            "type": "string"
          },
          "proxy": {
            "description": "`true` if the detector calls an external service (e.g. Skyflow).",
            "examples": [
              false
            ],
            "title": "Proxy",
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "categories",
          "loaded",
          "proxy"
        ],
        "title": "DetectorInfo",
        "type": "object"
      },
      "DetectorOptions": {
        "description": "Per-detector options namespace. Each key carries options for that one\ndetector. Only the entry matching the top-level `detector` is consulted \u2014\nother keys are accepted but ignored, so a client can carry one options\nblob across detector swaps without restructuring it.",
        "properties": {
          "opf": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/OpfOptions"
              },
              {
                "type": "null"
              }
            ],
            "description": "Options for the `opf` detector. Ignored by other detectors."
          }
        },
        "title": "DetectorOptions",
        "type": "object"
      },
      "DetectorsResponse": {
        "description": "Response from `/api/detectors`.",
        "examples": [
          {
            "default": "opf",
            "detectors": [
              {
                "categories": [
                  "PERSON",
                  "EMAIL"
                ],
                "loaded": false,
                "name": "gliner",
                "proxy": false
              },
              {
                "categories": [
                  "PERSON",
                  "EMAIL",
                  "PHONE"
                ],
                "loaded": true,
                "name": "opf",
                "proxy": false
              },
              {
                "categories": [
                  "PERSON",
                  "EMAIL"
                ],
                "loaded": false,
                "name": "skyflow",
                "proxy": true
              }
            ]
          }
        ],
        "properties": {
          "default": {
            "description": "Detector used when a request omits the `detector` field.",
            "examples": [
              "opf"
            ],
            "title": "Default",
            "type": "string"
          },
          "detectors": {
            "items": {
              "$ref": "#/components/schemas/DetectorInfo"
            },
            "title": "Detectors",
            "type": "array"
          }
        },
        "required": [
          "default",
          "detectors"
        ],
        "title": "DetectorsResponse",
        "type": "object"
      },
      "FindRequest": {
        "description": "Base request for `/api/find` \u2014 no text-rewriting fields.",
        "examples": [
          {
            "categories": [
              "EMAIL"
            ],
            "detector": "presidio",
            "text": "Email joe@example.com about the trip to Elgin, TX."
          }
        ],
        "properties": {
          "categories": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/CanonicalLabel"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Canonical categories to keep. Omit or set to `null` to keep every category the detector produces. An empty list `[]` is a deliberate \"match nothing\" filter and returns zero spans \u2014 use `null` if you mean \"no filter\". Values outside the canonical taxonomy are rejected with `422`.",
            "examples": [
              [
                "EMAIL",
                "PHONE"
              ]
            ],
            "title": "Categories"
          },
          "detector": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Detector name from `GET /api/detectors`. Omit to use the server's `DEFAULT_DETECTOR` (set via env, typically `opf`).",
            "examples": [
              "presidio",
              "opf",
              "gliner"
            ],
            "title": "Detector"
          },
          "options": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DetectorOptions"
              },
              {
                "type": "null"
              }
            ],
            "description": "Per-detector options namespace. The entry matching the top-level `detector` is consulted; other entries are accepted but ignored.",
            "examples": [
              {
                "opf": {
                  "decode_mode": "argmax"
                }
              }
            ]
          },
          "text": {
            "description": "Free-form text to scan for PII.",
            "examples": [
              "Email joe@example.com about the trip to Elgin, TX."
            ],
            "title": "Text",
            "type": "string"
          }
        },
        "required": [
          "text"
        ],
        "title": "FindRequest",
        "type": "object"
      },
      "FindResponse": {
        "description": "Response from `/api/find`.",
        "examples": [
          {
            "detected_spans": [
              {
                "end": 21,
                "label": "EMAIL",
                "raw_label": "EMAIL_ADDRESS",
                "start": 6,
                "text": "joe@example.com"
              }
            ],
            "detector": "presidio",
            "summary": {
              "by_label": {
                "EMAIL": 1
              },
              "span_count": 1
            },
            "text": "Email joe@example.com about the trip to Elgin, TX."
          }
        ],
        "properties": {
          "detected_spans": {
            "description": "Spans detected by the chosen detector.",
            "items": {
              "$ref": "#/components/schemas/SpanOut"
            },
            "title": "Detected Spans",
            "type": "array"
          },
          "detector": {
            "description": "Detector that produced the spans.",
            "title": "Detector",
            "type": "string"
          },
          "summary": {
            "$ref": "#/components/schemas/SummaryOut"
          },
          "text": {
            "description": "Echo of the request `text`.",
            "title": "Text",
            "type": "string"
          },
          "warning": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Non-fatal warning surfaced by the detector backend, if any.",
            "title": "Warning"
          }
        },
        "required": [
          "detector",
          "text",
          "detected_spans",
          "summary"
        ],
        "title": "FindResponse",
        "type": "object"
      },
      "HealthResponse": {
        "description": "Response from `/api/health`.",
        "examples": [
          {
            "default_detector": "opf",
            "loaded_detectors": [
              "opf"
            ],
            "status": "ok"
          }
        ],
        "properties": {
          "default_detector": {
            "description": "Detector used when requests omit `detector`.",
            "examples": [
              "opf"
            ],
            "title": "Default Detector",
            "type": "string"
          },
          "loaded_detectors": {
            "description": "Names of detectors that have been initialised so far.",
            "examples": [
              [
                "opf"
              ]
            ],
            "items": {
              "type": "string"
            },
            "title": "Loaded Detectors",
            "type": "array"
          },
          "status": {
            "const": "ok",
            "description": "Always `ok` when this endpoint responds.",
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "status",
          "default_detector",
          "loaded_detectors"
        ],
        "title": "HealthResponse",
        "type": "object"
      },
      "OpfOptions": {
        "additionalProperties": false,
        "description": "Options that only apply when `detector` is `opf`.",
        "properties": {
          "decode_mode": {
            "default": "viterbi",
            "description": "OPF decode strategy. `viterbi` (default) maximises sequence probability; `argmax` picks the most likely label per token independently. **Currently advisory** \u2014 the OPF detector reads its decode mode from the server's `OPF_DECODE_MODE` env at startup; per-request override is reserved for a follow-up that extends `OPFDetector.detect()`.",
            "enum": [
              "viterbi",
              "argmax"
            ],
            "examples": [
              "viterbi"
            ],
            "title": "Decode Mode",
            "type": "string"
          }
        },
        "title": "OpfOptions",
        "type": "object"
      },
      "ReplaceRequest": {
        "description": "Request for `/api/replace` \u2014 `FindRequest` plus a `mode` field that picks\nhow detected spans are rewritten.",
        "examples": [
          {
            "detector": "presidio",
            "mode": "label_token",
            "text": "Email alice@x.com or call +1-415-555-0100."
          }
        ],
        "properties": {
          "categories": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/CanonicalLabel"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Canonical categories to keep. Omit or set to `null` to keep every category the detector produces. An empty list `[]` is a deliberate \"match nothing\" filter and returns zero spans \u2014 use `null` if you mean \"no filter\". Values outside the canonical taxonomy are rejected with `422`.",
            "examples": [
              [
                "EMAIL",
                "PHONE"
              ]
            ],
            "title": "Categories"
          },
          "detector": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Detector name from `GET /api/detectors`. Omit to use the server's `DEFAULT_DETECTOR` (set via env, typically `opf`).",
            "examples": [
              "presidio",
              "opf",
              "gliner"
            ],
            "title": "Detector"
          },
          "mode": {
            "default": "label",
            "description": "How to rewrite each detected span. `redact` -> `********` (fixed asterisks). `label` -> `[EMAIL]` (default). `label_number` -> `[EMAIL_1]` (per-request counter; duplicates reuse the number). `label_token` -> `[EMAIL_jRc7QGn]` (deterministic 7-char Skyflow vault token; requires `SKYFLOW_TOKEN_VAULT_*` env).",
            "enum": [
              "redact",
              "label",
              "label_number",
              "label_token"
            ],
            "examples": [
              "label",
              "label_token"
            ],
            "title": "Mode",
            "type": "string"
          },
          "options": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DetectorOptions"
              },
              {
                "type": "null"
              }
            ],
            "description": "Per-detector options namespace. The entry matching the top-level `detector` is consulted; other entries are accepted but ignored.",
            "examples": [
              {
                "opf": {
                  "decode_mode": "argmax"
                }
              }
            ]
          },
          "text": {
            "description": "Free-form text to scan for PII.",
            "examples": [
              "Email joe@example.com about the trip to Elgin, TX."
            ],
            "title": "Text",
            "type": "string"
          }
        },
        "required": [
          "text"
        ],
        "title": "ReplaceRequest",
        "type": "object"
      },
      "ReplaceResponse": {
        "description": "Response from `/api/replace`.",
        "examples": [
          {
            "detected_spans": [
              {
                "end": 17,
                "label": "EMAIL",
                "raw_label": "EMAIL_ADDRESS",
                "replaced": true,
                "replacement": "[EMAIL_MGaE1Bo]",
                "start": 6,
                "text": "alice@x.com"
              },
              {
                "end": 42,
                "label": "PHONE",
                "raw_label": "PHONE_NUMBER",
                "replaced": true,
                "replacement": "[PHONE_vRXiWKZ]",
                "start": 27,
                "text": "+1-415-555-0100"
              }
            ],
            "detector": "presidio",
            "mode": "label_token",
            "replaced_text": "Email [EMAIL_MGaE1Bo] or call [PHONE_vRXiWKZ].",
            "summary": {
              "by_label": {
                "EMAIL": 1,
                "PHONE": 1
              },
              "span_count": 2
            },
            "text": "Email alice@x.com or call +1-415-555-0100."
          }
        ],
        "properties": {
          "detected_spans": {
            "description": "Spans detected by the chosen detector, with their replacements.",
            "items": {
              "$ref": "#/components/schemas/ReplacedSpan"
            },
            "title": "Detected Spans",
            "type": "array"
          },
          "detector": {
            "description": "Detector that produced the spans.",
            "examples": [
              "presidio"
            ],
            "title": "Detector",
            "type": "string"
          },
          "mode": {
            "description": "Echo of the request `mode`.",
            "enum": [
              "redact",
              "label",
              "label_number",
              "label_token"
            ],
            "examples": [
              "label_token"
            ],
            "title": "Mode",
            "type": "string"
          },
          "replaced_text": {
            "description": "`text` with each detected span replaced by its `replacement`. Overlapping spans: the earlier-starting span wins; later overlaps are skipped here (they still appear in `detected_spans`).",
            "examples": [
              "Email [EMAIL_MGaE1Bo]."
            ],
            "title": "Replaced Text",
            "type": "string"
          },
          "summary": {
            "$ref": "#/components/schemas/SummaryOut"
          },
          "text": {
            "description": "Echo of the request `text`.",
            "examples": [
              "Email alice@x.com."
            ],
            "title": "Text",
            "type": "string"
          },
          "warning": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Non-fatal warning surfaced by the detector backend, if any.",
            "title": "Warning"
          }
        },
        "required": [
          "detector",
          "mode",
          "text",
          "detected_spans",
          "replaced_text",
          "summary"
        ],
        "title": "ReplaceResponse",
        "type": "object"
      },
      "ReplacedSpan": {
        "description": "One detected span plus the string it was rewritten to in `replaced_text`.",
        "properties": {
          "end": {
            "description": "Exclusive character offset in `text`.",
            "examples": [
              17
            ],
            "title": "End",
            "type": "integer"
          },
          "label": {
            "description": "Canonical label for the span (e.g. `EMAIL`, `PERSON`).",
            "examples": [
              "EMAIL"
            ],
            "title": "Label",
            "type": "string"
          },
          "raw_label": {
            "description": "Detector's native label before mapping into the canonical taxonomy.",
            "examples": [
              "EMAIL_ADDRESS"
            ],
            "title": "Raw Label",
            "type": "string"
          },
          "replaced": {
            "description": "`true` if this span was actually spliced into `replaced_text`; `false` if it was suppressed as a later-starting overlap of an earlier-starting span. To reconstruct exactly what changed, filter to `replaced=true`.",
            "examples": [
              true
            ],
            "title": "Replaced",
            "type": "boolean"
          },
          "replacement": {
            "description": "The string the renderer produced for this span. Only spliced into `replaced_text` when `replaced=true`; for skipped overlaps this value is still populated (the renderer ran) but did not land.",
            "examples": [
              "[EMAIL_MGaE1Bo]"
            ],
            "title": "Replacement",
            "type": "string"
          },
          "start": {
            "description": "Inclusive character offset in `text`.",
            "examples": [
              6
            ],
            "title": "Start",
            "type": "integer"
          },
          "text": {
            "description": "Substring of the original input.",
            "examples": [
              "alice@x.com"
            ],
            "title": "Text",
            "type": "string"
          }
        },
        "required": [
          "label",
          "raw_label",
          "start",
          "end",
          "text",
          "replacement",
          "replaced"
        ],
        "title": "ReplacedSpan",
        "type": "object"
      },
      "SpanOut": {
        "description": "Plain span for `/api/find` \u2014 no replacement text.",
        "properties": {
          "end": {
            "description": "Exclusive character offset in `text`.",
            "examples": [
              21
            ],
            "title": "End",
            "type": "integer"
          },
          "label": {
            "description": "Canonical label.",
            "examples": [
              "EMAIL"
            ],
            "title": "Label",
            "type": "string"
          },
          "raw_label": {
            "description": "Detector's native label before mapping into the canonical taxonomy.",
            "examples": [
              "EMAIL_ADDRESS"
            ],
            "title": "Raw Label",
            "type": "string"
          },
          "start": {
            "description": "Inclusive character offset in `text`.",
            "examples": [
              6
            ],
            "title": "Start",
            "type": "integer"
          },
          "text": {
            "description": "Substring of the original input.",
            "examples": [
              "joe@example.com"
            ],
            "title": "Text",
            "type": "string"
          }
        },
        "required": [
          "label",
          "raw_label",
          "start",
          "end",
          "text"
        ],
        "title": "SpanOut",
        "type": "object"
      },
      "SummaryOut": {
        "description": "Per-response detection summary. `by_label` maps canonical label to count.",
        "properties": {
          "by_label": {
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Count of spans per canonical label.",
            "examples": [
              {
                "EMAIL": 1,
                "PHONE": 1
              }
            ],
            "title": "By Label",
            "type": "object"
          },
          "span_count": {
            "description": "Total number of spans detected.",
            "examples": [
              2
            ],
            "title": "Span Count",
            "type": "integer"
          }
        },
        "required": [
          "span_count",
          "by_label"
        ],
        "title": "SummaryOut",
        "type": "object"
      }
    }
  },
  "info": {
    "contact": {
      "name": "local-privacy",
      "url": "https://github.com/jstjoe/local-privacy"
    },
    "description": "Unified PII detection across **OPF**, **GLiNER**, **Presidio**, and **Skyflow**.\nPick a backend with the `detector` field; canonical labels apply uniformly across all of them.\n\n## Endpoints\n\n- `POST /api/find` \u2014 find sensitive data; return spans only, no text rewriting.\n- `POST /api/replace` \u2014 find spans and replace each one under one of four modes.\n- `GET /api/detectors` \u2014 list registered detectors and their category coverage.\n- `GET /api/health` \u2014 liveness probe; does not exercise detector backends.\n\n## Versioning\n\nThe API is pre-`1.0`. `info.version` is the only version surface today \u2014\nevery breaking change to request or response shape lands as a minor bump\n(`0.x.0 -> 0.(x+1).0`); non-breaking additions land as patch bumps.\n\nURL paths are unversioned (`/api/...`). When the API stabilizes, the\nintent is to move to **header-based date-string versioning** in the style\nof Stripe \u2014 clients will pin to a release date via `API-Version:\n2026-05-13`. Until that header lands, treat `info.version` as the contract.\n\n## Canonical labels\n\nEvery detector's raw output maps into a 15-label taxonomy:\n`PERSON`, `EMAIL`, `PHONE`, `ADDRESS`, `URL`, `DATE`, `ACCOUNT`, `SECRET`, `USERNAME`,\n`DEMOGRAPHIC`, `ORGANIZATION`, `OCCUPATION`, `MONEY`, `VEHICLE`, `PHYSICAL`.\nDetectors vary in coverage \u2014 `GET /api/detectors` reports each detector's category list.\n",
    "license": {
      "name": "AGPL-3.0-or-later",
      "url": "https://www.gnu.org/licenses/agpl-3.0.html"
    },
    "summary": "Unified PII detection across OPF, GLiNER, Presidio, and Skyflow.",
    "title": "Sensitive Data Detector API",
    "version": "0.6.1"
  },
  "openapi": "3.1.0",
  "paths": {
    "/api/detectors": {
      "get": {
        "description": "Return every detector registered in this deployment plus the canonical categories each can produce. `loaded` flips to `true` after first use (or at startup if the detector is listed in `EAGER_LOAD`). `proxy=true` means the detector calls an external service.",
        "operationId": "list_detectors_api_detectors_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DetectorsResponse"
                }
              }
            },
            "description": "Registry snapshot."
          }
        },
        "summary": "List registered detectors",
        "tags": [
          "Meta"
        ]
      }
    },
    "/api/find": {
      "post": {
        "description": "Run the chosen detector over `text` and return canonical-labelled spans.\n\nNo rewriting is performed \u2014 call `/api/replace` for that.\n\nFilter detector output to a subset of canonical labels with `categories`.\nOPF-only: pass `options.opf.decode_mode` to override the default Viterbi decoding.",
        "operationId": "find_api_find_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FindRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FindResponse"
                }
              }
            },
            "description": "Detected spans plus per-label counts."
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "label_token_unconfigured": {
                    "summary": "label_token mode without vault env",
                    "value": {
                      "detail": "mode='label_token' requires SKYFLOW_TOKEN_VAULT_URL and SKYFLOW_TOKEN_VAULT_ID env vars to be set"
                    }
                  },
                  "unknown_detector": {
                    "summary": "Unknown detector",
                    "value": {
                      "detail": "unknown detector 'foo'; available: ['gliner', 'opf', 'presidio']"
                    }
                  }
                }
              }
            },
            "description": "Unknown detector or missing config for the chosen mode."
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "bad_category": {
                    "summary": "Non-canonical value in `categories`",
                    "value": {
                      "detail": [
                        {
                          "input": "FOO",
                          "loc": [
                            "body",
                            "categories",
                            0
                          ],
                          "msg": "Input should be 'PERSON', 'EMAIL', 'PHONE', ...",
                          "type": "enum"
                        }
                      ]
                    }
                  },
                  "unknown_opf_option": {
                    "summary": "Unknown key in `options.opf`",
                    "value": {
                      "detail": [
                        {
                          "input": "argmax",
                          "loc": [
                            "body",
                            "options",
                            "opf",
                            "decod_mode"
                          ],
                          "msg": "Extra inputs are not permitted",
                          "type": "extra_forbidden"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "description": "Request body failed Pydantic validation. Common causes: a value in `categories` that isn't a canonical label, an unknown key in `options.opf`, or a wrong type on any field."
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "detector_failure": {
                    "summary": "Detector backend errored",
                    "value": {
                      "detail": "skyflow: upstream 503"
                    }
                  },
                  "vault_failure": {
                    "summary": "Token vault call failed",
                    "value": {
                      "detail": "label_token: vault insert failed: 401"
                    }
                  }
                }
              }
            },
            "description": "Detector backend failure or vault call failure."
          }
        },
        "summary": "Find sensitive data",
        "tags": [
          "Find"
        ]
      }
    },
    "/api/health": {
      "get": {
        "description": "Always returns `200` when the process is up. Does **not** probe detector backends \u2014 use `/api/detectors` to inspect which detectors have been loaded.",
        "operationId": "health_api_health_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            },
            "description": "Liveness status plus which detectors are currently loaded."
          }
        },
        "summary": "Liveness probe",
        "tags": [
          "Meta"
        ]
      }
    },
    "/api/replace": {
      "post": {
        "description": "Find spans, then rewrite each one under the chosen `mode`. Four modes, in increasing strength of identity preservation:\n\n| `mode` | Looks like | What it preserves |\n|---|---|---|\n| `redact` | `********` | Nothing \u2014 fixed 8-char asterisk run regardless of span length. |\n| `label` | `[EMAIL]` | Category only. Default. |\n| `label_number` | `[EMAIL_1]` | Identity **within one request** via per-label counter; duplicate `(label, text)` reuses its number. Dropped-overlap spans (`replaced=false`) still consume a counter slot, so the kept sequence may skip numbers \u2014 see the overlap notes below. |\n| `label_token` | `[EMAIL_MGaE1Bo]` | Identity **across requests and detectors** via a Skyflow vault. Deterministic \u2014 same plaintext maps to the same 7-char token forever. |\n\n**Overlapping spans:** the earlier-starting span wins; later overlaps are skipped in `replaced_text` but still appear in `detected_spans` with `replaced=false`. Filter to `replaced=true` to reconstruct exactly what landed.\n\n**`label_token` requirements:** `SKYFLOW_TOKEN_VAULT_URL`, `SKYFLOW_TOKEN_VAULT_ID`, and a bearer (`SKYFLOW_TOKEN_BEARER_TOKEN`, falling back to `SKYFLOW_BEARER_TOKEN`). The vault must be configured per the token-vault setup guide \u2014 one table with one `tok_<label>` column per canonical label, each `DETERMINISTIC_FPT` with regex `^[A-Za-z0-9]{7}$`. Spans whose canonical label has no vault column fall back to `[LABEL]` for that span only.",
        "operationId": "replace_api_replace_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReplaceRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReplaceResponse"
                }
              }
            },
            "description": "Replaced text, the spans that were rewritten, and per-label counts."
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "label_token_unconfigured": {
                    "summary": "label_token mode without vault env",
                    "value": {
                      "detail": "mode='label_token' requires SKYFLOW_TOKEN_VAULT_URL and SKYFLOW_TOKEN_VAULT_ID env vars to be set"
                    }
                  },
                  "unknown_detector": {
                    "summary": "Unknown detector",
                    "value": {
                      "detail": "unknown detector 'foo'; available: ['gliner', 'opf', 'presidio']"
                    }
                  }
                }
              }
            },
            "description": "Unknown detector or missing config for the chosen mode."
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "bad_category": {
                    "summary": "Non-canonical value in `categories`",
                    "value": {
                      "detail": [
                        {
                          "input": "FOO",
                          "loc": [
                            "body",
                            "categories",
                            0
                          ],
                          "msg": "Input should be 'PERSON', 'EMAIL', 'PHONE', ...",
                          "type": "enum"
                        }
                      ]
                    }
                  },
                  "unknown_opf_option": {
                    "summary": "Unknown key in `options.opf`",
                    "value": {
                      "detail": [
                        {
                          "input": "argmax",
                          "loc": [
                            "body",
                            "options",
                            "opf",
                            "decod_mode"
                          ],
                          "msg": "Extra inputs are not permitted",
                          "type": "extra_forbidden"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "description": "Request body failed Pydantic validation. Common causes: a value in `categories` that isn't a canonical label, an unknown key in `options.opf`, or a wrong type on any field."
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "detector_failure": {
                    "summary": "Detector backend errored",
                    "value": {
                      "detail": "skyflow: upstream 503"
                    }
                  },
                  "vault_failure": {
                    "summary": "Token vault call failed",
                    "value": {
                      "detail": "label_token: vault insert failed: 401"
                    }
                  }
                }
              }
            },
            "description": "Detector backend failure or vault call failure."
          }
        },
        "summary": "Replace sensitive data",
        "tags": [
          "Replace"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "Local dev",
      "url": "http://localhost:8000"
    }
  ],
  "tags": [
    {
      "description": "Find-only endpoint. Returns spans without rewriting the input.",
      "name": "Find"
    },
    {
      "description": "Find plus rewriting under one of four modes: `redact`, `label`, `label_number`, `label_token`.",
      "name": "Replace"
    },
    {
      "description": "Registry and liveness endpoints.",
      "name": "Meta"
    }
  ]
}