`POST /v1/moderations` classifies one block of text against a saved preset or an inline policy.

## Authentication [#authentication]

Send a Flagline machine key as a bearer token:

```http
POST /v1/moderations
Authorization: Bearer mod_live_...
Content-Type: application/json
Idempotency-Key: optional-client-key
```

The key must be active, unrevoked, allowed to use the requested level, and attached to a tenant whose billing status is `active` or `trialing`. The tenant comes only from the key row. A selected workspace, request field, or client-supplied tenant ID is never authorization.

## Request [#request]

| Field            | Required | Notes                                                                                            |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `input`          | Yes      | The text to classify. Capped at 8,000 UTF-8 bytes after NFC normalization.                       |
| `preset_id`      | One of   | UUID of a saved preset. Resolves its active version.                                             |
| `preset`         | One of   | Full inline policy content. Never saved or shown in the dashboard.                               |
| `level`          | No       | `light`, `standard`, or `heavy`. Omitted uses the workspace default. Must be allowed by the key. |
| `on_failure`     | No       | `error`, `allow`, `flag`, or `block`. Overrides the preset and workspace defaults.               |
| `input_overflow` | No       | `reject` or `truncate`. Omitted uses the workspace default.                                      |

`preset_id` and `preset` are mutually exclusive, and exactly one is required.

### Saved preset [#saved-preset]

```json
{
  "input": "You are useless and should quit.",
  "preset_id": "8a5f0f2e-5c9d-4f2a-a1f8-0f8f6f9c1b2a",
  "level": "standard"
}
```

### Inline preset [#inline-preset]

An inline preset is content only. It may not set `id`, `source`, `version`, or `enabled`. Category thresholds use the engine field names `flagThreshold` and `blockThreshold`.

```json
{
  "input": "You are useless and should quit.",
  "preset": {
    "name": "Support replies",
    "description": "Rules for a customer support inbox.",
    "defaultLevel": "standard",
    "categories": [
      {
        "id": "harassment",
        "name": "Harassment",
        "description": "Targeted abuse or repeated personal insults.",
        "flagThreshold": 0.45,
        "blockThreshold": 0.85,
        "severity": 7,
        "allowExamples": [],
        "blockExamples": []
      }
    ]
  }
}
```

Inline policies are limited to 25 categories and validated by the same engine preset schema that runs saved presets. An inline preset is compiled for that request only.

## Response [#response]

```json
{
  "id": "3f30a1d8-0b9c-4a44-9d55-3b2f6f0f0d21",
  "decision": "flag",
  "flagged": true,
  "categories": [{ "category_id": "harassment", "score": 0.61 }],
  "level": "standard",
  "model": "pinned-model-id",
  "escalated": false,
  "cached": false,
  "degraded": false
}
```

- `decision` is `allow`, `flag`, or `block`. Your application decides what to do with it.
- `flagged` is `true` for both `flag` and `block`.
- `categories` contains every evaluated category and its score. It is not the request text.
- `model` names the model that produced a non-degraded decision. It can be `null` when inference failed before any model call.
- `escalated` reports whether the second tier was used.
- `cached` is `true` only for a complete private-cache hit. Shared caching is not active in this release.
- `degraded` is `true` only when an explicit decision-shaped `on_failure` supplied the verdict after inference was unavailable. A degraded response includes no invented category scores.

The raw input is not stored. The audit stores a domain-separated hash, scores, thresholds, the pinned model, the preset version, and the charge.

## Failure behavior [#failure-behavior]

The fallback precedence is:

```text
explicit request on_failure > preset failurePolicy > workspace default > "error"
```

The default is an error response (`503`). `allow`, `flag`, or `block` return a degraded `200` instead. A degraded decision is audited and charged, but it is not test evidence for publishing a preset.

## Limits and retries [#limits-and-retries]

- **Body.** 512 KiB maximum, streamed and enforced during the read.
- **Raw input.** 65,536 bytes before the applied cap.
- **Applied input.** 8,000 UTF-8 bytes of NFC-normalized text.
- **Idempotency.** An `Idempotency-Key` is scoped to the tenant and key for 24 hours. A completed replay returns the original response and decision ID without charging again. A different explicit request shape returns `409 idempotency_conflict`. A replay still consumes a rate-limit token.
- **Rate and concurrency.** Per-key hard limits are enforced through the dedicated limits Redis. A refusal returns `429` with `Retry-After`.
- **Daily spend ceiling.** Optional per key. It bounds committed charges in a UTC day, not provider cost from failed inference.
- **Deadline.** The deployment deadline is 30 seconds. A workspace setting may shorten it. A timeout returns `408`.

<Callout type="warning" title="Retry rules">
Retry `429` and `503` responses with backoff. For a retry that must not double-charge, reuse the
same `Idempotency-Key`. If you receive `503 commit_outcome_unknown`, do not assume the charge was
rolled back; retry with the same key if one was supplied.
</Callout>

## Errors [#errors]

Errors use a fixed shape:

```json
{
  "error": {
    "code": "inference_unavailable",
    "message": "The moderation service is temporarily unavailable."
  }
}
```

| Status     | Codes                                                                    |
| ---------- | ------------------------------------------------------------------------ |
| 400 or 422 | `invalid_request`; 400 also `invalid_json`; 422 also `preset_invalid`    |
| 401        | `unauthenticated`                                                        |
| 403        | `account_inactive`, `level_not_allowed`                                  |
| 404        | `preset_not_found`                                                       |
| 408        | `request_timeout`                                                        |
| 409        | `preset_unusable`, `idempotency_conflict`, `idempotency_in_progress`     |
| 413        | `payload_too_large`, `input_too_large`                                   |
| 415        | `unsupported_media_type`                                                 |
| 429        | `rate_limited`, `concurrency_limited`, `spend_ceiling_exceeded`          |
| 499        | `request_aborted`                                                        |
| 503        | `inference_unavailable`, `service_unavailable`, `commit_outcome_unknown` |

Error messages are fixed for each code and never include request text, preset content, provider responses, or SQL details.

## API keys [#api-keys]

Create keys in the dashboard under **API Keys**. A key carries:

- A name.
- One or more allowed levels.
- A per-minute rate limit and a concurrency limit.
- An optional daily spend ceiling in USD.

The secret is shown once. Revocation keeps the key's history and stops new requests immediately. This API does not create or change presets.