export const metadata = {
  title: "Processing Options",
  description:
    "Tune replacement categories, confidence thresholds, and AI pass behavior for each FaithTranscripts request.",
  alternates: { canonical: "/docs/api/options" },
};

# Processing Options

Every `POST /transcripts` call accepts an optional top-level `options`
object. All fields are optional with sane defaults. Options are echoed back
on the response so you can confirm what actually ran.

## Shape

```jsonc
{
  "options": {
    // Which replacement categories to apply. Defaults to all.
    "replacement_categories": [
      "person",
      "place",
      "theology",
      "church",
      "bible",
    ],

    // Deterministic suggestion acceptance threshold (0..1).
    // Suggestions below this are surfaced as "needs_review"
    // instead of being auto-applied.
    "auto_apply_confidence": 0.9,

    // AI-pass settings. Same prompt and flow as the web app.
    "ai_pass": {
      "enabled": true,
      "confidence_threshold": 0.75,
    },
  },
  // Stripe-style metadata: flat key/value map of strings.
  "metadata": {
    "episode_id": "ep-482",
    "producer": "Jane",
  },
}
```

## Field reference

| Field                          | Type       | Default | Purpose                                                        |
| ------------------------------ | ---------- | ------- | -------------------------------------------------------------- |
| `replacement_categories`       | `string[]` | all     | Limit deterministic replacements to these categories.          |
| `auto_apply_confidence`        | `number`   | `0.9`   | Minimum confidence for auto-applied deterministic suggestions. |
| `ai_pass.enabled`              | `boolean`  | `false` | Run the AI validation pass after the deterministic pass.       |
| `ai_pass.confidence_threshold` | `number`   | `0.75`  | Minimum AI confidence before a suggestion is merged.           |
| `metadata`                     | `object`   | `{}`    | Top-level; echoed back on reads. Opaque to us.                 |

### Replacement categories

Categories match the `dictionaryRule.category` enum used internally:

- `person` — people names (Pastor Smith, Charles Spurgeon)
- `place` — geographic names (Nineveh, Galatia)
- `theology` — theological terms (propitiation, imputation)
- `church` — organizations, denominations, events
- `bible` — Bible book names, chapter/verse references

### `auto_apply_confidence`

Raise this to be more conservative: more suggestions will land in the
review queue instead of being auto-applied. Lower it to lean heavier on
the deterministic pass.

### `ai_pass`

Passing `enabled: true` enqueues the AI validation pass after the
deterministic pass completes. Its output is filtered by
`confidence_threshold` before being merged.

The AI pass behaves exactly as it does on the web app — same prompt, same
flow, same structured output. The only API knobs are whether it runs and
the confidence threshold for its output.

### `metadata`

This is for your use, anything you pass in here is echoed back on reads.

- Flat key/value map of strings
- At most 50 keys
- Keys at most 40 chars
- Values at most 500 chars

Use it to tag transcripts with your own identifiers so you can reconcile
API responses with your own data model.

## Defaults live in the dashboard

Your org's dashboard-side defaults (categories, thresholds, whether AI
pass is on by default) are applied when `options` is omitted or partial,
with per-request overrides winning. The common case is a two-field
POST: `source_type` + `content`/`url`.

## Things that are always on

To keep API-produced transcripts consistent with dashboard-produced ones,
these behaviors are **not configurable** via the API:

- Your org's custom dictionary rules are always applied on top of the global dictionary.
- Your org's learned rule overrides (suppress, force_ai_review, set_confidence) are always applied.

If you need different behavior, change it in the dashboard — the API will
pick up the change on the next request.